HP-UX Reference (11i v2 04/09) - 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
property 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>
Section 3−−388 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: September 2004