gethostbyname

This function gets host data corresponding to a host name.

At a Glance

Header file: Winsock.h
Windows CE versions: 1.0 and later

Syntax

struct hostent * gethostbyname(const char *name);

Parameters

name

[out] Pointer to the null-terminated string that contains the host name to resolve.

Return Values

A pointer to the HOSTENT structure indicates no error occurred. A NULL pointer indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The gethostbyname function returns a pointer to a HOSTENT structure—a structure allocated by Windows Sockets. The HOSTENT structure contains the results of a successful search for the host specified in the name parameter.

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, so the application should copy data it needs before issuing other Windows Sockets function calls.

The gethostbyname function cannot resolve IP address strings passed to it. Such a request is treated exactly as if an unknown host name were passed. Use inet_addr to convert an IP address string the string to an actual IP address, then use another function, gethostbyaddr, to obtain the contents of the HOSTENT structure.

The gethostbyname function resolves the string returned by a successful call to gethostname.

Note   Japanese Version Winsock calls to get the machine IP address will fail if the machine name is entered in Japanese characters.

See Also

gethostbyaddr, inet_ntoa, WSAStartup