The
gethostbyname(),
gethostbyname2() and
gethostbyaddr() functions each return a pointer to an object with the following structure describing an internet host.
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 */
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
The members of this structure are:
h_name
Official name of the host.
h_aliases
A NULL-terminated array of alternative 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 NULL-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.
In the case of
gethostbyname() and
gethostbyname2(), the host is specified by name, or using a string representation of a numeric address. In the case of
gethostbyaddr(), the host is specified using a binary representation of an address.
The returned
struct hostent structure may contain the result of a simple string to binary conversion, information obtained from the domain name resolver (see
resolver(3)), broken-out fields from a line in
/etc/hosts, or database entries supplied by the
yp(8) system. The order of the lookups is controlled by the ‘hosts' entry in
nsswitch.conf(5).
When using the domain name resolver,
gethostbyname() and
gethostbyname2() will search for the named host in the current domain and its parents unless the name ends in a dot. If the name contains no dot, and if the environment variable “
HOSTALIASES” contains the name of an alias file, the alias file will first be searched for an alias matching the input name. See
hostname(7) for the domain search procedure and the alias file format.
The
gethostbyname2() function is an evolution of
gethostbyname() which is intended to allow lookups in address families other than
AF_INET, for example
AF_INET6. Currently the
af argument must be specified as
AF_INET or
AF_INET6, else the function will return
NULL after having set
h_errno to
NETDB_INTERNAL.
The
gethostent() function reads the next line of the
/etc/hosts file, opening the file if necessary.
The
sethostent() function may be used to request the use of a connected TCP socket for queries. If the
stayopen flag is non-zero, this sets the option to send all queries to the name server using TCP and to retain the connection after each call to
gethostbyname(),
gethostbyname2(), or
gethostbyaddr(). Otherwise, queries are performed using UDP datagrams.
The
endhostent() function closes the TCP connection.
The
herror() function writes a message to the diagnostic output consisting of the string parameter
s, the constant string ": ", and a message corresponding to the value of
h_errno.
The
hstrerror() function returns a string which is the message text corresponding to the value of the
err parameter.