gethostbyname()

NAME

gethostbyname(), gethostbyaddr(), gethostent(), sethostent(), endhostent(), herror() - get network host entry (and h_errno variable)

SYNOPSIS

#include <netdb.h>
extern int h_errno;


struct hostent *gethostbyname (const char *name)
struct hostent *gethostbyaddr (const void *addr, int len, int type)
struct hostent *gethostent (void)
void sethostent (int stayopen)
void endhostent (void)
void herror (char *string)

DESCRIPTION

The gethostbyname(2) and gethostbyaddr(2) functions each return a pointer to an object with the following structure describing an Internet host referenced by name or by address, respectively.

The gethostbyname(2) function searches for information on a host named name, and returns a pointer to a struct hostent.

The gethostbyaddr(2) function searches for information about a host with the host address addr. The address is a string, in the dot-separated Internet Protocol (IP) format. The buffer specified by addr is len bytes in size. The type is the supported network type (always AF_INET in this implementation).

The struct hostent structure contains the information obtained from the Winsock dynamic-link library (DLL) configuration on the local computer (regardless of how your Windows networking system is configured):

struct hostent {
   char * h_name;  /* official name of host */
   char ** h_aliases;   /* alias list */
   int h_addrtype; /* host address type */
   int h_length; 	/* length of address */
   char ** h_addr_list; /* list of addresses from name server */
};

For backwards compatibility, the address is also defined as:

#define   h_addr  h_addr_list[0]

The members of this structure are:

h_name: Official name of the host. Argument supplied for gethostbyname(2).
h_aliases: A zero terminated array of alternate names for the host.
h_addrtype: The type of address being returned; currently always AF_INET.
h_length: The length, in bytes, of the address.
h_addr_list: A zero terminated array of network addresses for the host. Host addresses are returned in network byte order.
h_addr: The first address in h_addr_list; this is for backward compatibility.

The calls gethostent(2), sethostent(2), and endhostent(2) search the hosts file (%WINDIR%/system32/drivers/etc/hosts) instead of the name server. The gethostent(2) function reads the next line of the hosts file, opening the file if necessary.

The sethostent(2) function opens or rewinds the hosts file, or does both. If the stayopen argument is non-zero, the file will not be closed after each call to gethostbyname(2) or gethostbyaddr(2).

The endhostent(2) function closes the file.

DIAGNOSTICS

Error return status from gethostbyname(2) and gethostbyaddr(2) is indicated by return of a null pointer. The external integer h_errno can then be checked to determine whether this is a temporary failure or an invalid or unknown host. The routine herror(3) can be used to print an error message describing the failure. If its argument string is non-NULL, string is printed, followed by a colon and a space. The error message is printed with a trailing newline.

The variable h_errno can have the following values:

HOST_NOT_FOUND: No such host is known.
TRY_AGAIN: This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time might succeed.
NO_RECOVERY: Some unexpected server failure was encountered. This is a nonrecoverable error.
NO_DATA: The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder can be registered for this domain.

NOTES

The sockets mechanism in Interix is built around the Microsoft Winsock DLL. Configuring the network information for sockets depends upon your Winsock configuration; see the appropriate system documentation.

These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Currently the functions only understand the Internet address format.