NAME

gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent − get network host entry

SYNOPSIS

cc [ flag ... ] file ... −lnsl [ library ... ]

#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>

struct hostent ∗gethostbyname(const char ∗name);

struct hostent ∗gethostbyaddr(const char ∗addr, int len, int type);

struct hostent ∗gethostent(void);

int sethostent(int stayopen);

int endhostent(void);

MT-LEVEL

Unsafe

DESCRIPTION

gethostent(), gethostbyaddr(), and gethostbyname() each return a host entry. 

The entry may come from one of the following sources: the hosts file (see hosts(4)), the NIS maps “hosts.byname” and “hosts.byaddr”, the NIS+ table “hosts” and the Internet Domain Name Service (DNS).  The sources and their lookup order are specified in the /etc/nsswitch.conf file (see nsswitch.conf(4) and the NOTES section in this man page for details).  Some name services such as NIS will return only one name for a host, whereas others such as NIS+ or DNS will return all aliases. 

gethostbyname() searches for a host entry with a given hostname. 

gethostbyaddr() searches for a host entry with a given hostaddress. 

gethostent() enumerates host entries:  successive calls to gethostent() will return either successive host entries or NULL.  Enumeration may not be supported by some sources. 

sethostent() “rewinds” to the beginning of the enumeration of host entries.  If the stayopen flag is non-zero, resources such as open file descriptors are not deallocated after each call to gethostbyaddr() and gethostbyname().  Calls to gethostbyname() and gethostbyaddr() may leave the enumeration in an indeterminate state, so sethostent() should be called before the first gethostent(). 

endhostent() may be called to indicate that host processing is complete; the system may then close any open hosts file, deallocate storage, and so forth.  It is legitimate, but possibly less efficient, to call more host routines after endhostent(). 

The internal representation of a host entry is a structure defined in <netdb.h> with the following members:

char∗h_name;
char∗∗h_aliases;
inth_addrtype;
inth_length;
char∗∗h_addr_list;

Host addresses are supplied in network order. 

RETURN VALUES

gethostbyname() and gethostbyaddr() return a pointer to a struct hostent if they successfully locate the requested entry; otherwise they return NULL, and set an integer h_errno to indicate one of these errors: HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY, NO_DATA and NO_ADDRESS (see /usr/include/netdb.h). 

gethostent() returns a pointer to a struct hostent if it successfully enumerates an entry; otherwise it returns NULL, indicating the end of the enumeration. 

FILES

/etc/hosts

/etc/netconfig

/etc/nsswitch.conf

/usr/lib/switch.so

SEE ALSO

netdir(3N), hosts(4), netconfig(4), nsswitch.conf(4)

NOTES

All information is contained in a static area so it must be copied if it is to be saved. 

gethostbyname() performs much the same function as netdir_getbyname(). To ensure that the two produce consistent results, gethostbyname() is implemented in terms of netdir_getbyname().  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. 

Similarly, gethostbyaddr() performs much the same function as netdir_getbyaddr() and is implemented in terms of it.

There is no analogue of gethostent() in the netdir routines, so gethostent() goes straight to the “hosts” entry in nsswitch.conf.  It may thus produce results that are inconsistent with the results of gethostbyname() and gethostbyaddr(). 

Even without this inconsistency, the use of gethostent() is deprecated; enumeration is well-defined for the hosts file and is supported (albeit inefficiently) for NIS and NIS+, but in general may not be well-defined.  The semantics of enumeration are discussed in nsswitch.conf(4). 

These interfaces are unsafe in multithreaded applications.  Unsafe interfaces should be called only from the main thread. 

BUGS

Only the Internet address format, AF_INET, is currently understood. 

Programs that call gethostbyname() or gethostbyaddr() routines cannot be linked statically since the implementation of these routines requires dynamic linker functionality to access shared objects at run time. 

SunOS 5.2  —  Last change: 22 Jan 1993