gethostbyname
This function retrieves host information corresponding to a host name from a host database.
struct hostent FAR* gethostbyname(
const char FAR* name
);
Parameters
- name
[out] Pointer to the null-terminated name of the host to resolve.
Return Values
If no error occurs, this function returns a pointer to the hostent structure. If an error occurs, it returns a NULL pointer, and a specific error number can be retrieved by calling WSAGetLastError.
The following table shows the possible error codes.
| Error code | Description |
|---|---|
| WSANOTINITIALISED | A successful WSAStartup call must occur before using this function. |
| WSAENETDOWN | The network subsystem has failed. |
| WSAHOST_NOT_FOUND | An authoritative answer host was not found. |
| WSATRY_AGAIN | A nonauthoritative host was not found, or the server failure. |
| WSANO_RECOVERY | A nonrecoverable error occurred. |
| WSANO_DATA | A valid name exists, but no data record of the requested type exists. |
| WSAEINPROGRESS | A blocking Winsock call is in progress, or the service provider is still processing a callback function. |
| WSAEFAULT | The name parameter is not a valid part of the user address space. |
| WSAEINTR | The socket was closed. |
Note Japanese Version Winsock calls to get the machine IP address will fail if the machine name is entered in Japanese characters.
Remarks
This function returns a pointer to a hostent structure, which is 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 any information it needs before issuing any other Windows Sockets function calls.
This 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 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.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Winsock2.h.
Link Library: Ws2.lib.
See Also
gethostbyaddr | gethostname | hostent | inet_addr | WSAGetLastError | WSAStartup
Last updated on Saturday, April 10, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.