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 <netdb.h>
#include <netinet/in.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 specified 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.  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 beginning 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 endhostent(). 

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 process to call more host retrieval functions after calling endhostent(). 

Reentrant Interfaces

The functions gethostbyname(), gethostbyaddr(), and gethostent() use static storage that is re-used in each call, making these routines unsafe for use in multithreaded applications. 

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” suffix.  The reentrant interfaces, however, use buffers supplied by the caller to store returned results, and are safe for use in both single-threaded and multithreaded applications. 

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 associated 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 {

};

The functions gethostbyname(), gethostbyname_r(), gethostbyaddr(), 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 gethostent() 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 non-NULL, it is always equal to the result pointer that was supplied by the caller. 

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 applications. 

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. 

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

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) may be helpful in constructing and manipulating addresses in this form. 

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. 

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 supported for all database sources.  The semantics of enumeration are discussed further in nsswitch.conf(4). 

gethostbyname_r() and gethostbyname() are implemented in terms of netdir_getbyname() in order to ensure that they return consistent results.  Similarly, gethostbyaddr_r() and gethostbyaddr() are implemented in terms of netdir_getbyaddr(). Their behavior is controlled by the netconfig(4) entries for the inet family of transports.  If these entries include switch.so, then the entry for hosts in nsswitch.conf will also be used; otherwise nsswitch.conf will not be consulted. 

There is no analogue of gethostent_r() in the netdir routines, so gethostent_r() goes straight to the hosts entry in nsswitch.conf.  Thus enumeration may return results from a different source than that used by gethostbyname_r() and gethostbyaddr_r().

Sun Microsystems  —  Last change: 30 Mar 1993