NAME
gethostbyname,
gethostbyname2,
gethostbyaddr,
gethostent,
sethostent,
endhostent,
herror,
hstrerror —
get network host entry
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *
gethostbyname(
const
char *name);
struct hostent *
gethostbyname2(
const
char *name,
int af);
struct hostent *
gethostbyaddr(
const
void *addr,
socklen_t
len,
int type);
struct hostent *
gethostent(
void);
void
sethostent(
int
stayopen);
void
endhostent(
void);
void
herror(
const char
*string);
const char *
hstrerror(
int
err);
DESCRIPTION
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.
FILES
- /etc/hosts
-
DIAGNOSTICS
Error return status from
gethostbyent(),
gethostbyname(),
gethostbyname2(), 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.
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 may succeed.
-
-
NO_RECOVERY
- Some unexpected server failure was encountered. This is a
non-recoverable 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 may be registered for
this domain.
SEE ALSO
resolver(3),
hosts(5),
nsswitch.conf(5),
hostname(7),
named(8)
HISTORY
The
herror() function appeared in
4.3BSD. The
endhostent(),
gethostbyaddr(),
gethostbyname(),
gethostent(), and
sethostent() functions
appeared in
4.2BSD. The
gethostbyname2() function first appeared in bind-4.9.4. IPv6
support was implemented in WIDE Hydrangea IPv6 protocol stack kit.
CAVEATS
If the search routines specified in
nsswitch.conf(5) decide
to read the
/etc/hosts file,
gethostbyname(),
gethostbyname2(), and
gethostbyaddr() will read the next line of the file,
re-opening the file if necessary.
The
sethostent() function opens and/or rewinds the file
/etc/hosts. If the
stayopen argument
is non-zero, the file will not be closed after each call to
gethostbyname(),
gethostbyname2(),
gethostbyaddr(), or
gethostent().
The
endhostent() function closes the file.
BUGS
These functions use static data storage; if the data is needed for future use,
it should be copied before any subsequent calls overwrite it. Only the
Internet address format is currently understood.
The
gethostent() does not currently follow the search order
specified in
nsswitch.conf(5) and only
reads the
/etc/hosts file.