hpux 10.20 - gethostent (3)
NAME
gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(),
gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(),
endhostent(), endhostent_r() - get network host entry
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
extern int h_errno;
struct hostent *gethostent(void);
int gethostent_r(struct hostent *result,
struct hostent_data *buffer);
struct hostent *gethostbyname(const char *name);
int gethostbyname_r(const char *name,
struct hostent *result,
struct hostent_data *buffer);
struct hostent *gethostbyaddr(const char *addr,
int len,
int type);
_XOPEN_SOURCE_EXTENDED only
struct hostent *gethostbyaddr(const void *addr,
size_t len,
int type);
int gethostbyaddr_r(const char *addr,
int len,
int type,
struct hostent *result,
struct hostent_data *buffer);
int sethostent(int stayopen);
int sethostent_r(int stayopen, struct hostent_data *buffer);
int endhostent(void);
int endhostent_r(struct hostent_data *buffer);
_XOPEN_SOURCE_EXTENDED only
void sethostent(int stayopen);
void endhostent(void);
DESCRIPTION
The gethostent(), gethostbyname(), and gethostbyaddr() functions each
return a pointer to a structure of type hostent, defined as follows in
<netdb.h>:
struct hostent {
char *h_name;
char **h_aliases;
int h_addrtype;
int h_length;
char **h_addr_list;
};
#define h_addr h_addr_list[0]
The members of this structure are:
h_name The official name of the host.
h_aliases A null-terminated array of alternate names
for the host.
h_addrtype The type of address being returned; always
AF_INET.
h_length The length, in bytes, of the address.
h_addr_list A null-terminated array of network addresses
for the host.
h_addr The first address in h_addr_list; this is for
compatibility with previous HP-UX
implementations where a struct hostent
contains only one network address per host.
Reentrant Interfaces
gethostent_r(), gethostbyname_r(), and gethostbyaddr_r() expect to be
passed the address of a struct hostent and will store the result at
the supplied location. An additional parameter, a pointer to a struct
hostent_data, must also be supplied. This structure is used to store
data, to which fields in the struct hostent will point, as well as
state information such as open file descriptors. The struct
hostent_data is defined in the header file <netdb.h>.
sethostent_r() and endhostent_r() are to be used only in conjunction
with gethostent_r() and take the same pointer to a struct hostent_data
as a parameter. If the Network Information Service is being used,
sethostent_r() initializes an internal database key. If the
/etc/hosts file is being used, sethostent_r() opens or rewinds the
file. If the named name server (see named(1M)) is being used, then
sethostent_r() has no effect. endhostent_r() should always be called
to ensure that files are closed and internally allocated data
structures are released.
The stayopen parameter to sethostent_r() currently has no effect.
However, sethostent() can still be used to keep the /etc/hosts file
open, or to use connected stream sockets to the name server, when
making calls to gethostbyaddr_r() and gethostbyname_r().
The hostf field in the struct hostent_data must be initialized to NULL
before it is passed to either gethostent_r() or sethostent_r() for the
first time. The current field in the struct hostent_data must be
initialized to NULL before it is passed to gethostbyname_r() or
gethostbyaddr_r() for the first time. Thereafter, these fields should
not be modified in any way. These are the only hostent_data fields
that should ever be explicitly accessed.
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
/etc/nsswitch.conf file (see switch(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 the
three 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 named name server (see
named(1M) and resolver(4)) for name or address resolution, then the
function:
gethostent() Always returns a NULL pointer.
sethostent(), 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
gethostbyname() or gethostbyaddr().
endhostent() Closes the stream socket connection.
gethostbyname()
gethostbyaddr() Each retrieves host information from the
name server. Names are matched without
respect to uppercase or lowercase. For
example, berkeley.edu, Berkeley.EDU, and
BERKELEY.EDU all match the entry for
berkeley.edu.
NIS Server Operation
If ypserv, the server for the Network Information Service (see
ypserv(1M)), is used for name or address resolution, then the
function:
gethostent() Returns the next entry in the NIS
database.
sethostent() Initializes an internal key for the NIS
database. If the stayopen flag is non-
zero, the internal key is not cleared
after calls to endhostent().
endhostent() Clears the internal NIS database key.
gethostbyname()
gethostbyaddr() Each retrieves host information from the
NIS database. Names are matched without
respect to uppercase or lowercase. For
example, berkeley.edu, Berkeley.EDU, and
BERKELEY.EDU all match the entry for
berkeley.edu.
Nonserver Operation
If the /etc/hosts file is used for name or address resolution, then
the function:
gethostent() Reads the next line of /etc/hosts, opening
the file if necessary.
sethostent() opens and rewinds the file. If the
stayopen flag is non-zero, the host data
base is not closed after each call to
gethostent() (either directly or
indirectly through one of the other
gethost calls).
endhostent() Closes the file.
gethostbyname() 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.
gethostbyaddr() Sequentially searches from the beginning
of the file until an Internet address
matching its addr parameter is found, or
until EOF is encountered.
Arguments
Currently, only the Internet address format is understood. In calls
to gethostbyaddr(), 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 <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 constant 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, respectively, 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.
For the reentrant (_r) versions of these routines, -1 is returned if
the operation is unsuccessful or, in the case of gethostent_r(), if
the end of the hosts list has been reached. 0 is returned otherwise.
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;
struct hostent htbuf;
struct hostent_data hdbuf;
hdbuf.hostf = NULL;
(void) sethostent_r(0, &hdbuf);
while (gethostent_r(&htbuf, &hdbuf) != -1)
count++;
(void) endhostent_r(&hdbuf);
WARNINGS
For the non-reentrant versions of these routines, all information is
contained in a static area so it must be copied if it is to be saved.
gethostent(), gethostbyaddr(), gethostbyname(), sethostent(), and
endhostent() are unsafe in multi-thread applications. gethostent_r(),
gethostbyaddr_r(), gethostbyname_r(), sethostent_r(), and
endhostent_r() are MT-Safe and should be used instead.
AUTHOR
gethostent() was developed by the University of California, Berkeley.
FILES
/etc/hosts
SEE ALSO
named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4),
ypfiles(4).
STANDARDS CONFORMANCE
gethostent(): XPG4