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