struct
hostent
*
gethostbyname(
const char *name
)
struct
hostent
*
gethostbyname2(
const char *name
, int af
)
struct
hostent
*
gethostbyaddr(
const char *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
)
),
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
h_aliases
h_addrtype
AF_INET
.
h_length
h_addr_list
h_addr
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.
/etc/hosts
),
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
TRY_AGAIN
NO_RECOVERY
NO_DATA
)
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.
/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.
The
gethostent()
does not currently follow the search order specified in
nsswitch.conf(5)
and only reads the
/etc/hosts
file.