gethostbyname()

Description

Get host information corresponding to a hostname.

#include <winsock.h>

struct hostent FAR * PASCAL FAR gethostbyname ( const char FAR * name);

name

A pointer to the name of the host.

Remarks

gethostbyname() returns a pointer to a hostent structure as described under gethostbyaddr(). The contents of this structure correspond to the hostname name. The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

A gethostbyname() implementation must not resolve IP address strings passed to it. Such a request should be treated exactly as if an unknown host name were passed. An application with an IP address string to resolve should use inet_addr() to convert the string to an IP address, then gethostbyaddr() to obtain the hostent structure.

Return Value

If no error occurs, gethostbyname() returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.
WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.
WSAHOST_NOT_FOUND
Authoritative Answer Host not found.
WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
WSANO_DATA
Valid name, no data record of requested type.
WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.
WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall()

See Also

WSAAsyncGetHostByName(), gethostbyaddr()

---

[Back: gethostbyaddr()]
[Next: gethostname()]