gethostent(3N)gethostent(3N)NAMEgethostent(), gethostbyaddr(), gethostbyname(), sethostent(), endhos‐
tent() - get, set, or end network host entry
SYNOPSISDESCRIPTION
The and functions each return a pointer to a structure of type defined
as follows in
The members of this structure are:
The official name of the host.
A null-terminated array of alternate names for the host.
The type of address being returned; always
The length, in bytes, of the address.
A null-terminated array of network addresses for the host.
The first address in
this is for compatibility with previous HP-
UX implementations where a contains only one
network address per host.
Name Service Switch-Based Operation
These host entry library routines internally call the name service
switch to access the "hosts" database lookup policy configured in the
file (see nsswitch.conf(4)). The lookup policy defines the order and
the criteria of the supported name services used to resolve host names
and Internet addresses. The operations of these name services: Domain
Name Server, NIS, and nonserver mode (e.g., files) are listed below.
Domain Name Server Operation
If the local system is configured to use the name server (see named(1M)
and resolver(4)) for name or address resolution, then the function:
Always returns a NULL pointer.
Requests the use of a connected stream socket
for queries to the name server if the
stayopen flag is non-zero. The connec‐
tion is retained after each call to or
Closes the stream socket connection.
Each retrieves host information from the name
server.
Names are matched without
respect to uppercase or
lowercase. For example,
and all match the entry for
NIS Server Operation
If the server for the Network Information Service (see
ypserv(1M)), is used for name or address resolution, then
the function:
Returns the next entry in the NIS database.
Initializes an internal key for the NIS database.
If the stayopen flag is
non-zero, the internal key
is not cleared after calls
to
Clears the internal NIS database key.
Each retrieves host information from
the NIS database.
Names are
matched with‐
out respect
to uppercase
or lowercase.
For example,
and all match
the entry for
Nonserver Operation
If the file is used for name or address
resolution, then the function:
Reads the next line of opening the
file if nec‐
essary.
Opens and rewinds the file.
If the stay‐
open flag is
non-zero, the
host data
base is not
closed after
each call to
(either
directly or
indirectly
through one
of the other
calls).
Closes the file.
Sequentially searches host names
(among either the official names or
the aliases)
matching its
name parame‐
ter from the
beginning of
the file
until EOF is
encountered.
Names are
matched with‐
out respect
to uppercase
or lowercase,
as described
above in the
name server
case.
Sequentially searches from the
beginning of the file
until an
Internet
address
matching its
addr parame‐
ter is found,
or until EOF
is encoun‐
tered.
The return value, must be saved before a
subsequent call to the functions and
In a multithreaded application, and use
thread-specific storage that is re-used in
each call. The return value, should be
unique for each thread and should be saved,
if desired, before the thread makes the
next call. The return value must be saved
before a subsequent call to the function or
because these functions may internally call
the function which may overwrite their
return value.
For enumeration in multithreaded applica‐
tions, the position within the enumeration
is a process-wide property shared by all
threads. may be used in a multithreaded
application, but resets the enumeration
position for all threads. If multiple
threads interleave calls to the threads
will enumerate disjoint subsets of the host
database.
Arguments
Currently, only the Internet address format
is understood. In calls to the parameter
addr must be a pointer to an in_addr struc‐
ture, an Internet address in network order
(see byteorder(3N)) and the header file The
parameter len must be the number of bytes
in an Internet address; that is, The param‐
eter type must be the constant
RETURN VALUE
If successful, and return a pointer to the
requested structure.
and return NULL if their host or addr
parameters, respectively, cannot be found
in the database. If is being used, they
also return NULL if they are unable to open
also returns NULL if either its addr or len
parameter is invalid.
always returns NULL if the name server is
being used.
ERRORS
If the name server is being used and or
returns a NULL pointer, the external inte‐
ger contains one of the following values:
No such host is known.
This is usually a temporary error.
The local
server did
not receive a
response from
an authorita‐
tive server.
A retry at
some later
time may suc‐
ceed.
This is a non-recoverable error.
The requested name is valid but does
not have an IP address;
this is not a
temporary
error. This
means another
type of
request to
the name
server will
result in an
answer.
If the name server is not being used, the
value of may not be meaningful.
EXAMPLES
The following code excerpt counts the num‐
ber of host entries:
The following sample program prints the
canonical name, aliases, and "." separated
Internet IP addresses for a given "." sepa‐
rated IP address.
WARNINGS
Programs that use the interfaces described
in this manpage cannot be linked statically
because the implementations of these func‐
tions employ dynamic loading and linking of
shared objects at run time.
is referenced as an for single thread
applications and is defined as function
call macro for multithreaded applications
in file Applications that reference need to
include
OBSOLESCENT INTERFACES
The above reentrant interfaces have been
moved from to They are included to support
existing applications and may be removed in
the future release. New multithreaded
applications should use the regular APIs
(those without the suffix).
The reentrant interfaces function the same
as the regular interfaces without the suf‐
fix. However, and expect to be passed the
address of a and will store the address of
the result at the supplied parameter. The
passed in address of in the reentrant
interfaces cannot be a NULL pointer.
The reentrant routines return if the opera‐
tion is unsuccessful, or, in the case of if
the end of the hosts list has been reached.
is returned otherwise.
AUTHOR
was developed by Sun Microsystems Inc.
FILESSEE ALSOnamed(1M), ypserv(1M), resolver(3N),
ypclnt(3C), hosts(4), nsswitch.conf(4),
ypfiles(4), thread_safety(5).
STANDARDS CONFORMANCEgethostent(3N)