HP-UX Reference (11i v2 07/12) - 3 Library Functions A-M (vol 6)

g
gethostent(3N) gethostent(3N)
In a multithreaded application,
gethostent() , gethostbyaddr()
, and gethostbyname()
use
thread-specific storage that is re-used in each call. The return value,
struct hostent, should be unique
for each thread and should be saved, if desired, before the thread makes the next
gethost*() call. The
return value must be saved before a subsequent call to the function
getaddrinfo()
or get-
nameinfo()
, because these functions may internally call the
gethost*() function which may
overwrite their return value.
For enumeration in multithreaded applications, the position within the enumeration is a process-wide pro-
perty shared by all threads.
sethostent() may be used in a multithreaded application, but resets the
enumeration position for all threads. If multiple threads interleave calls to
gethostent() , the threads
will enumerate disjoint subsets of the host database.
Arguments
Currently, only the Internet address format is understood. In calls to
gethostbyaddr()
, the parame-
ter addr must be a pointer to an in_addr structure, an Internet address in network order (see
byteorder(3N)) and the header file
<netinet/in.h>
). The parameter len must be the number of bytes
in an Internet address; that is,
sizeof (struct in_addr)
. The parameter type must be the con-
stant
AF_INET.
RETURN VALUE
If successful, gethostbyname()
, gethostbyaddr(), and gethostent() return a pointer to the
requested
hostent structure.
gethostbyname() and gethostbyaddr()
return NULL if their host or addr parameters, respec-
tively, cannot be found in the database. If
/etc/hosts is being used, they also return NULL if they are
unable to open /etc/hosts .
gethostbyaddr() also returns NULL if either its addr or len parameter is invalid.
gethostent() always returns NULL if the name server is being used.
ERRORS
If the name server is being used and gethostbyname()
or gethostbyaddr() returns a NULL
pointer, the external integer
h_errno contains one of the following values:
HOST_NOT_FOUND No such host is known.
TRY_AGAIN 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.
NO_RECOVERY This is a non-recoverable error.
NO_ADDRESS 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
h_errno may not be meaningful.
EXAMPLES
The following code excerpt counts the number of host entries:
int count = 0;
(void) sethostent(0);
while (gethostent() != NULL)
count++;
(void) endhostent();
The following sample program prints the canonical name, aliases, and "." separated Internet IP addresses
for a given "." separated IP address.
#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
#include <netinet/in.h>
main(int argc, const char **argv)
{
HP-UX 11i Version 2: December 2007 Update − 3 − Hewlett-Packard Company 495