gethostent(3N)

NAME

gethostent(), gethostbyaddr(), gethostbyname(), sethostent(), endhostent() — get, set, or end network host entry

SYNOPSIS

#include <sys/socket.h> 
#include <netinet/in.h> 
#include <netdb.h> 

struct hostent *gethostent(void); 

struct hostent *gethostbyname(const char *name); 

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 sethostent(int stayopen); 

int endhostent(void); 

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

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 nsswitch.conf(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 these 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.

The return value, struct hostent, must be saved before a subsequent call to the functions gethost*(), getaddrinfo(), and getnameinfo().

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 getnameinfo(), 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 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.

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> 

main(int argc, const  char **argv) 
{ 
     u_int 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 no 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); 
} 

WARNINGS

Programs that use the interfaces described in this manpage cannot be linked statically because the implementations of these functions employ dynamic loading and linking of shared objects at run time.

h_errno is referenced as an extern int for single thread applications and is defined as function call macro for multithreaded applications in file /usr/include/netdb.h. Applications that reference h_errno need to include /usr/include/netdb.h.

OBSOLESCENT INTERFACES

int gethostent_r(struct hostent *result, 
                 struct hostent_data *buffer); 

int gethostbyname_r(const char *name, 
                    struct hostent *result, 
                    struct hostent_data *buffer); 

int gethostbyaddr_r(const char *addr, 
                    int len, 
                    int type, 
                    struct hostent *result, 
                    struct hostent_data *buffer); 

int sethostent_r(int stayopen, struct hostent_data *buffer); 

int endhostent_r(struct hostent_data *buffer); 

The above reentrant interfaces have been moved from libc to libd4r. They are included to support existing applications and may be removed in the future release. New multithreaded applications should use the regular APIs (those without the -r suffix).

The reentrant interfaces function the same as the regular interfaces without the -r suffix. However, gethostent_r(), gethostbyname_r(), and gethostbyaddr_r() expect to be passed the address of a struct hostent and will store the address of the result at the supplied parameter. The passed in address of struct hostent_data in the reentrant interfaces cannot be a NULL pointer.

The reentrant routines return -1 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.

AUTHOR

gethostent() was developed by Sun Microsystems Inc.

FILES

/etc/hosts

STANDARDS CONFORMANCE

gethostent(): XPG4