4.3BSD - /usr/man/cat3/gethostent.0

GETHOSTBYNAME(3N)                                            GETHOSTBYNAME(3N)


NAME
       gethostbyname,  gethostbyaddr, gethostent, sethostent, endhostent - get
       network host entry

SYNOPSIS
       #include <netdb.h>

       extern int h_errno;

       struct hostent *gethostbyname(name)
       char *name;

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

       struct hostent *gethostent()

       sethostent(stayopen)
       int stayopen;

       endhostent()


DESCRIPTION
       Gethostbyname and gethostbyaddr each return a pointer to an object with
       the  following  structure.  This structure contains either the informa‐
       tion obtained from the name server, named(8), or broken-out fields from
       a  line  in  /etc/hosts.  If the local name server is not running these
       routines do a lookup in /etc/hosts.

              struct    hostent {
                   char *h_name;  /* official 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 from name server */
              };
              #define   h_addr  h_addr_list[0]   /* address, for backward compatibility */

       The members of this structure are:

       h_name       Official name of the host.

       h_aliases    A zero terminated array of alternate names for the host.

       h_addrtype   The type  of  address  being  returned;  currently  always
                    AF_INET.

       h_length     The length, in bytes, of the address.

       h_addr_list  A zero terminated array of network addresses for the host.
                    Host addresses are returned in network byte order.

       h_addr       The first address in h_addr_list;  this  is  for  backward
                    compatiblity.

       Sethostent allows a request for the use of a connected socket using TCP
       for queries.  If the stayopen flag is non-zero, this sets the option to
       send all queries to the name server using TCP and to retain the connec‐
       tion after each call to gethostbyname or gethostbyaddr.

       Endhostent closes the TCP connection.

DIAGNOSTICS
       Error return status from gethostbyname and gethostbyaddr  is  indicated
       by  return of a null pointer.  The external integer h_errno may then be
       checked to see whether this is a temporary failure  or  an  invalid  or
       unknown host.

       h_errno can have the following values:

              HOST_NOT_FOUND  No such host is known.

              TRY_AGAIN       This is usually a temporary error and means that
                              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.

FILES
       /etc/hosts

SEE ALSO
       hosts(5), resolver(3), named(8)

CAVEAT
       Gethostent  is  defined,  and  sethostent and endhostent are redefined,
       when libc is built to use only the routines to lookup in /etc/hosts and
       not the name server.

       Gethostent  reads the next line of /etc/hosts, opening the file if nec‐
       essary.

       Sethostent is redefined to open and rewind the file.  If  the  stayopen
       argument is non-zero, the hosts data base will not be closed after each
       call to gethostbyname or gethostbyaddr.   Endhostent  is  redefined  to
       close the file.

BUGS
       All  information  is contained in a static area so it must be copied if
       it is to be saved.  Only  the  Internet  address  format  is  currently
       understood.


4.2 Berkeley Distribution        May 20, 1986                GETHOSTBYNAME(3N)