Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function retrieves host information corresponding to a host name from a host database.

Note:
The gethostbyname function has been deprecated by the introduction of the getaddrinfofunction. Developers who create Windows Sockets 2 applications are urged to use the getaddrinfo function instead of gethostbyname.

Syntax 

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

Parameters

name

[out] Pointer to the null-terminated name of the host to resolve.

Return Value

If no error occurs, this function returns a pointer to the hostentstructure. 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 WSAStartupcall 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 nameparameter 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 hostentstructure, which is a structure allocated by Windows Sockets. The hostentstructure contains the results of a successful search for the host specified in the nameparameter.

The application must never attempt to modify this structure or to free anything inside the structure.. 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_addrto convert an IP address string to an actual IP address, then use another function, gethostbyaddr, to obtain the contents of the hostentstructure.

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

Requirements

Header winsock2.h
Library Ws2.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also