gethostbyname

This function gets host data corresponding to a host name.

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.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

gethostbyaddr, inet_ntoa, WSAStartup

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.