NAME
gethostbyname, gethostbyname_r, gethostbyaddr,
gethostbyaddr_r, gethostent, gethostent_r, sethostent,
endhostent - get network host entry
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <netdb.h>
struct hostent *gethostbyname(const char *name);
struct hostent *gethostbyname_r(const char *name,
struct hostent *result, char *buffer, int buflen,
int *h_errnop);
struct hostent *gethostbyaddr(const char *addr, int len,
int type);
struct hostent *gethostbyaddr_r(const char *addr,
int length, int type, struct hostent *result,
char *buffer, int buflen, int *h_errnop);
struct hostent *gethostent(void);
struct hostent *gethostent_r(struct hostent *result,
char *buffer, int buflen, int *h_errnop);
int sethostent(int stayopen);
int endhostent(void);
MT-LEVEL
See the subsection "Reentrant Interfaces" in the DESCRIPTION
section of this page.
DESCRIPTION
These functions are used to obtain entries describing hosts.
An entry may come from any of the sources for hosts speci-
fied in the /etc/nsswitch.conf file (see nsswitch.conf(4)).
gethostbyname() searches for information for a host with the
hostname specified by the character-string parameter name.
gethostbyaddr() searches for information for a host with a
given host address. The parameter type specifies the family
of the address. This should be one of the address families
defined in <sys/socket.h>. The parameter addr must be a
pointer to a buffer containing the address. The address is
given in a form specific to the address family. See the
NOTES section below for more information. Also see the
EXAMPLES section below on how to convert a ``.'' separated
Internet IP address notation into the addr parameter. The
parameter len specifies the length of the buffer indicated
by addr.
The functions sethostent(), gethostent(), and endhostent()
are used to enumerate host entries from the database.
sethostent() sets (or resets) the enumeration to the begin-
ning of the set of host entries. This function should be
called before the first call to gethostent(). Calls to
gethostbyname() and gethostbyaddr() leave the enumeration
position in an indeterminate state. If the stayopen flag is
non-zero, the system may keep allocated resources such as
open file descriptors until a subsequent call to endhos-
tent().
Successive calls to gethostent() return either successive
entries or NULL, indicating the end of the enumeration.
endhostent() may be called to indicate that the caller
expects to do no further host entry retrieval operations;
the system may then deallocate resources it was using. It
is still allowed, but possibly less efficient, for the pro-
cess to call more host retrieval functions after calling
endhostent().
Reentrant Interfaces
The functions gethostbyname(), gethostbyaddr(), and gethos-
tent() use static storage that is re-used in each call, mak-
ing these functions unsafe for use in multithreaded applica-
tions.
The functions:
gethostbyname_r(),
gethostbyaddr_r(),
and
gethostent_r()
provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the ``_r'' suf-
fix. The reentrant interfaces, however, use buffers sup-
plied by the caller to store returned results, and are safe
for use in both single-threaded and multithreaded applica-
tions.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following
additional parameters. The parameter result must be a
pointer to a struct hostent structure allocated by the
caller. On successful completion, the function returns the
host entry in this structure. The parameter buffer must be
a pointer to a buffer supplied by the caller. This buffer
is used as storage space for the host data. All of the
pointers within the returned struct hostent result point to
data stored within this buffer (see RETURN VALUES). The
buffer must be large enough to hold all of the data associ-
ated with the host entry. The parameter buflen should give
the size in bytes of the buffer indicated by buffer. The
parameter h_errnop should be a pointer to an integer. An
integer error status value is stored there on certain error
conditions. (see ERRORS).
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_r(), the threads will enumerate disjoint subsets
of the host database.
Like their non-reentrant counterparts, gethostbyname_r() and
gethostbyaddr_r() leave the enumeration position in an
indeterminate state.
RETURN VALUES
Host entries are represented by the struct hostent structure
defined in <netdb.h>:
struct hostent {
char *h_name; /* canonical name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
};
See the EXAMPLES section below on how to retrieve a ``.''
separated Internet IP address string from the h_addr_list
field of struct hostent .
The functions gethostbyname(), gethostbyname_r(), gethost-
byaddr(), and gethostbyaddr_r() each return a pointer to a
struct hostent if they successfully locate the requested
entry; otherwise they return NULL.
The functions gethostent() and gethostent_r() each return a
pointer to a struct hostent if they successfully enumerate
an entry; otherwise they return NULL, indicating the end of
the enumeration.
The functions gethostbyname(), gethostbyaddr(), and gethos-
tent() use static storage, so returned data must be copied
before a subsequent call to any of these functions if the
data is to be saved.
When the pointer returned by the reentrant functions
gethostbyname_r(), gethostbyaddr_r(), and gethostent_r() is
not NULL, it is always equal to the result pointer that was
supplied by the caller.
The functions sethostent() and endhostent() return 0 on suc-
cess.
ERRORS
The reentrant functions gethostbyname_r(), gethostbyaddr_r()
and gethostent_r() will return NULL and set errno to ERANGE
if the length of the buffer supplied by caller is not large
enough to store the result. See intro(2) for the proper
usage and interpretation of errno in multithreaded applica-
tions.
On failures, the non-reentrant functions gethostbyname() and
gethostbyaddr() set a global integer h_errno to indicate one
of these error codes (defined in <netdb.h>):
HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY, NO_DATA, and
NO_ADDRESS. The reentrant functions gethostbyname_r() and
gethostbyaddr_r() set the integer pointed to by h_errnop to
one of these values in case of error.
EXAMPLES
Here is a sample program that gets 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 <<netinet/in.h>>
#include <<arpa/inet.h>>
#include <<netdb.h>>
main(int argc, const char **argv)
{
u_long addr;
struct hostent *hp;
char **p;
if (argc != 2) {
(void) printf("usage: %s IP-address\n", argv[0]);
exit (1);
}
if ((int)(addr = inet_addr(argv[1])) == -1) {
(void) printf("IP-address must be of the form a.b.c.d\n");
exit (2);
}
hp = gethostbyaddr((char *)&&addr, sizeof (addr), AF_INET);
if (hp == NULL) {
(void) printf("host information for %s not found\n", argv[1]);
exit (3);
}
for (p = hp->>h_addr_list; *p != 0; p++) {
struct in_addr in;
char **q;
(void) memcpy(&&in.s_addr, *p, sizeof (in.s_addr));
(void) printf("%s\t%s", inet_ntoa(in), hp->>h_name);
for (q = hp->>h_aliases; *q != 0; q++)
(void) printf(" %s", *q);
(void) putchar('\n');
}
exit (0);
}
Note that the above sample program is unsafe for use in mul-
tithreaded applications.
FILES
/etc/hosts
/etc/netconfig
/etc/nsswitch.conf
SEE ALSO
inet(3N), netdir(3N), hosts(4), netconfig(4),
nsswitch.conf(4)
WARNINGS
The reentrant interfaces gethostbyname_r(),
gethostbyaddr_r(), and gethostent_r() are included in this
release on an uncommitted basis only, and are subject to
change or removal in future minor releases.
NOTES
Programs that use the interfaces described in this manual
page cannot be linked statically since the implementations
of these functions employ dynamic loading and linking of
shared objects at run time.
In order to ensure that they all return consistent results,
gethostbyname(), gethostbyname_r(), and netdir_getbyname()
are implemented in terms of the same internal library func-
tion. This function obtains the system-wide source lookup
policy based on the inet family entries in netconfig(4) and
the hosts: entry in nsswitch.conf(4). Similarly, gethost-
byaddr(), gethostbyaddr_r(), and netdir_getbyaddr() are
implemented in terms of the same internal library function.
If the inet family entries in netconfig(4) have a ``-'' in
the last column for nametoaddr libraries, then the entry for
hosts in nsswitch.conf will be used; otherwise the name-
toaddr libraries in that column will be used, and
nsswitch.conf will not be consulted.
There is no analogue of gethostent() and gethostent_r() in
the netdir functions, so these enumeration functions go
straight to the hosts entry in nsswitch.conf. Thus enumera-
tion may return results from a different source than that
used by gethostbyname(), gethostbyname_r(), gethostbyaddr(),
and gethostbyaddr_r().
All the functions that return a struct hostent must always
return the canonical name in the h_name field. This name,
by definition, is the well-known and official hostname
shared between all aliases and all addresses. The underly-
ing source that satisfies the request determines the mapping
of the input name or address into the set of names and
addresses in hostent. Different sources might do that in
different ways. If there is more than one alias and more
than one address in hostent, no pairing is implied between
them.
The system will strive to put the addresses on the same sub-
net as that of the caller first.
When compiling multithreaded applications, see Intro(3),
Notes On Multithread Applications, for information about the
use of the _REENTRANT flag.
Use of the enumeration interfaces gethostent() and
gethostent_r() is discouraged; enumeration may not be sup-
ported for all database sources. The semantics of enumera-
tion are discussed further in nsswitch.conf(4).
The current implementations of these functions only return
or accept addresses for the Internet address family (type
AF_INET).
The form for an address of type AF_INET is a struct in_addr
defined in <netinet/in.h>. The functions described in
inet(3N), and illustrated in the EXAMPLES section above, are
helpful in constructing and manipulating addresses in this
form.