g_h_b_n(3)

NAME

     g_h_b_n,   gethostbyname,    gethostbyaddr,    gethostent,    sethostent,
     endhostent, herror - get network host entry

SYNOPSIS

     #include <net/gen/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()

     herror(string)
     char *string;

DESCRIPTION

     Gethostbyname and gethostbyaddr each return a pointer to an  object  with
     the following structure describing an internet host referenced by name or
     by address, respectively.  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.

     When using the nameserver, gethostbyname will search for the  named  host
     in  the current domain and its parents unless the name ends in a dot.  If
     the  name  contains   no   dot,   and   if   the   environment   variable
     ``HOSTALAIASES''  contains the name of an alias file, the alias file will
     first be searched for an alias matching the input name.  See  hostname(7)
     for the domain search procedure and the alias file format.

     Sethostent may be used to request the use of a connected TCP  socket  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  connection
     after  each  call  to gethostbyname or gethostbyaddr.  Otherwise, queries
     are performed using UDP datagrams.

     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.   The routine herror can be used to print an error message
     describing the failure.  If  its  argument  string  is  non-NULL,  it  is
     printed,  followed  by a colon and a space.  The error message is printed
     with a trailing newline.

     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     Some unexpected server failure was encountered.  This  is
                     a non-recoverable error.



     NO_DATA         The requested name is valid  but  does  not  have  an  IP
                     address;  this  is not a temporary error. This means that
                     the name is known to the name  server  but  there  is  no
                     address  associated  with  this  name.   Another  type of
                     request to the name server using this  domain  name  will
                     result in an answer; for example, a mail-forwarder may be
                     registered for this domain.

FILES

     /etc/hosts

SEE ALSO

     resolver(3), hosts(5), hostname(7), 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
     necessary.

     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.