herror

NAME

       gethostbyname, gethostbyaddr, gethostent, sethostent, end-
       hostent, herror - get network host entry

SYNOPSIS

       #include <netdb.h>

       extern int h_errno;

       struct hostent *gethostbyname(name)
       char *name;

       struct hostent *gethostbyname2(name, af)
       char *name; int af;

       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,  gethostbyname2,  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_addrtype   The type of address being  returned;  usually
                    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'' con-
       tains 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.

       Gethostbyname2  is  an evolution of gethostbyname intended
       to allow lookups in address families other  than  AF_INET,
       for  example  AF_INET6.  Currently the af argument must be
       specified as AF_INET else the function  will  return  NULL
       after having set h_errno to NETDB_INTERNAL.

       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:

              NETDB_INTERNAL  This indicates an internal error in
                              the library, unrelated to the  net-
                              work  or  name service.  errno will
                              be valid in  this  case;  see  per-


              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.