gethostent(3N) gethostent(3N)
NAME
gethostent(), gethostbyaddr(), gethostbyname(), sethostent(), endhostent() - get, set, or end network host entry
SYNOPSIS
DESCRIPTION
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 connection 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 without 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 necessary.
Opens and rewinds the file.
If the stayopen 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 from the beginning of the file
until a host name (among either the official names or the aliases) matching its name parameter is found, or
until EOF is encountered. Names are matched without 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 parameter is found, or until EOF is encountered.
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 applications, 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 structure, 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 parameter 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 integer 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 authoritative server. A retry at some later time may
succeed.
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 number of host entries:
The following sample program prints the canonical name, aliases, and "." separated Internet IP addresses for a given "." separated IP
address.
WARNINGS
Programs that use the interfaces described in this manpage cannot be linked statically because the implementations of these functions
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 Applica-
tions 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 suffix. 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 operation 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.
FILES
SEE ALSO
named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), nsswitch.conf(4), ypfiles(4), thread_safety(5).
STANDARDS CONFORMANCE
gethostent(3N)