gethostbyname
,
gethostbyaddr
, gethostent
,
sethostent
, endhostent
,
herror
— get network host
entry
#include
<netdb.h>
extern int
h_errno;
struct hostent *
gethostbyname
(char
*name);
struct hostent *
gethostbyname2
(char
*name, int af);
struct hostent *
gethostbyaddr
(char
*addr, int len,
type);
struct hostent *
gethostent
();
sethostent
(int
stayopen);
endhostent
();
herror
(char
*string);
Gethostbyname
(),
gethostbyname2
(),
and
gethostbyaddr
()
each return a pointer to a hostent structure (see
below) describing an internet host referenced by name or by address, as the
function names indicate. This structure contains either the information
obtained from the name server, or broken-out fields from a line in
/etc/hosts. If the local name server is not running,
these routines do a lookup in /etc/hosts.
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 zero-terminated array of alternate names for the host.
- h_addrtype
- The type of address being returned; usually
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.
When using the nameserver,
gethostbyname
()
will search for the named host in each parent domain given in the
“search
” directive of
resolv.conf(5)
unless the name contains 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.
Gethostbyname2
()
is an evolution of gethostbyname
() 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
else the function will return
NULL
after having set h_errno
to NETDB_INTERNAL
.
Sethostent
()
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
() or
gethostbyaddr
().
Otherwise, queries are performed using UDP datagrams.
Endhostent
()
closes the TCP connection.
HOSTALIASES
- Name of file containing (host alias,
full hostname) pairs.
Error return status from gethostbyname
()
and gethostbyaddr
() is indicated by return of a null
pointer. The external integer h_errno may then be
checked to see whether this is a temporary failure or an invalid or unknown
host. The routine herror
() can be used to print an
error message describing the failure. If its argument
string is non-NULL, it is printed, followed by a colon
and a space. The error message is printed with a trailing newline.
h_errno can have the following values:
NETDB_INTERNAL
- This indicates an internal error in the library, unrelated to the network
or name service. errno will be valid in this case;
see
perror.
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 may succeed.
NO_RECOVERY
- Some unexpected server failure was encountered. This is a non-recoverable
error, as one might expect.
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 may be registered for this domain.
Gethostent
()
is defined, and
sethostent
()
and
endhostent
()
are redefined, when libc is built to use only the
routines to lookup in /etc/hosts and not the name
server:
Gethostent
()
reads the next line of /etc/hosts, opening the file
if necessary.
Sethostent
()
is redefined to open and rewind the file. If the
stayopen argument is non-zero, the hosts data base
will not be closed after each call to
gethostbyname
() or
gethostbyaddr
().
Endhostent
()
is redefined to close the file.
All information is contained in a static area so it must be copied
if it is to be saved. Only the Internet address format is currently
understood.