GETHOSTBYNAME(3N)                    BSD                     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 information
     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 nonzero, this sets the option to
     send all queries  to  the  name  server  using  TCP  and  to  retain  the
     connection after each call to gethostbyname or gethostbyaddr.

     endhostent closes the TCP connection.

FILES
     /etc/hosts

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

DIAGNOSTICS
     Error return status from gethostbyname and gethostbyaddr is indicated  by
     return  of  a  null  pointer.   The  external integer h_errno can 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.

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.

CAVEATS
     gethostent reads the  next  line  of  /etc/hosts,  opening  the  file  if
     necessary.

     sethostent is redefined to open and rewind the  file.   If  the  stayopen
     argument  is  nonzero,  the  hosts database will not be closed after each
     call to gethostbyname or gethostbyaddr.  endhostent is redefined to close
     the file.