gethostbyname() — Get a host entry by name

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

X/Open: 
#define _XOPEN_SOURCE_EXTENDED 1
#include <netdb.h>
extern int h_errno;

struct hostent *gethostbyname(const char *name);
Berkeley sockets: 
#define _OE_SOCKETS
#include <netdb.h>

struct hostent *gethostbyname(char *name);

General description

The gethostbyname() call tries to resolve the host name through a name server, if one is present. If a name server is not present, gethostbyname() searches the local host tables until a matching host name is found or an EOF marker is reached.
Parameter
Description
name
The name of the host.

The gethostbyname() call returns a pointer to a hostent structure for the host name specified on the call.

gethostent(), gethostbyaddr(), and gethostbyname() all use the same static area to return the hostent structure. This static area is only valid until the next one of these functions is called on the same thread.

If you want gethostbyname() to bypass the name server and instead resolve the host name using the local host tables, you must define the RESOLVE_VIA_LOOKUP symbol before including any sockets-related include files in your source program.

If the name server is not present or the RESOLVE_VIA_LOOKUP option is in effect, you can use the X_SITE environment variable to specify different local host tables and override those supplied by the z/OS global resolver during initialization.
Note: For more information on these local host tables or the environment variables, see z/OS V2R1.0 Communications Server: IP Configuration Guide.

gethostent(), gethostbyaddr(), and gethostbyname() all use the same static area to return the HOSTENT structure. This static area is only valid until the next one of these functions is called on the same thread.

The netdb.h include file defines the hostent structure and contains the following elements:
Element
Description
h_addr_list
A pointer to a NULL-terminated list of host network addresses.
h_addrtype
The type of address returned; currently, it is always set to AF_INET.
h_aliases
A zero-terminated array of alternative names for the host.
h_length
The length of the address in bytes.
h_name
The official name of the host.
The following function (X/Open sockets only) is defined in netdb.h and should be used by multithreaded applications when attempting to reference h_errno return on error: 
int *__h_errno(void);

Also use this function when you invoke gethostbyname() in a DLL. This function returns a pointer to a thread-specific value for the h_errno variable.

Special Behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Note: The gethostbyaddr() and gethostbyname() functions have been moved to obsolescence in Single UNIX Specification, Version 3 and may be withdrawn in a future version. The getaddrinfo() and getnameinfo() functions are preferred for portability.

Returned value

The return value points to static data that is overwritten by subsequent calls. A pointer to a hostent structure indicates success. A NULL pointer indicates an error or End Of File (EOF).

If unsuccessful in X/Open, gethostbyname() sets h_errno to one of the following values:
Error Code
Description
HOST_NOT_FOUND
No such host is known.
NO_DATA
The server recognized the request and the name but no address is available. Another type of request to the name server might return an answer.
NO_RECOVERY
An unexpected server failure occurred from which there is no recovery.
TRY_AGAIN
A temporary error such as no response from a server, indicating the information is not available now but may be at a later time.

Related information

Parent topic: Library functions