NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <netdb.h>
     extern int h_errno;

     struct hostent *
     gethostbyname(const char *name);

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

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

     struct hostent *
     gethostent(void);

     void
     sethostent(int stayopen);

     void
     endhostent(void);

     void
     herror(const char *string);

     const char *
     hstrerror(int err);

DESCRIPTION    [Toc]    [Back]

     The  gethostbyname(),  gethostbyname2()  and gethostbyaddr()
functions 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 information obtained from the name
server
     (i.e.,  resolver(3)  and named(8)), broken-out fields from a
line in
     /etc/hosts, or database entries supplied by the  yp(8)  system.
     resolv.conf(5) describes how the particular database is chosen.

     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 NULL-terminated array of alternate names  for
the host.

     h_addrtype   The type of address being returned.

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


     The function gethostbyname() will search for the named  host
in the current
  domain  and its parents using the search lookup semantics detailed in
     resolv.conf(5) and hostname(7).

     gethostbyname2() is  an  advanced  form  of  gethostbyname()
which allows
     lookups  in address families other than AF_INET.  Currently,
the only supported
 address family besides AF_INET is AF_INET6.

     The gethostbyaddr() function will search for  the  specified
address of
     length len in the address family af.  The only address family currently
     supported is AF_INET.

     The sethostent() function 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.

     The endhostent() function closes the TCP connection.

     The herror() function prints an error message describing the
failure.  If
     its argument string is non-null, it is prepended to the message string
     and separated from it by a colon (`:') and a space.  The error message is
     printed  with a trailing newline.  The contents of the error
message is
     the same as  that  returned  by  hstrerror()  with  argument
h_errno.

ENVIRONMENT    [Toc]    [Back]

     HOSTALIASES   A  file  containing  local  host aliases.  See
hostname(7) for
                  more information.

     RES_OPTIONS  A list of options to  override  the  resolver's
internal defaults.
   See resolver(3) for more information.

FILES    [Toc]    [Back]

     /etc/hosts
     /etc/resolv.conf

DIAGNOSTICS    [Toc]    [Back]

     Error return status from gethostbyname(),  gethostbyname2(),
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 variable 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.

     NETDB_INTERNAL  An internal error occurred.  This may occurs
when an address
 family other than AF_INET or  AF_INET6
is specified
                     or  when a resource is unable to be allocated.

     NETDB_SUCCESS   The function completed successfully.

SEE ALSO    [Toc]    [Back]

     getaddrinfo(3), getnameinfo(3), resolver(3),  hosts(5),  resolv.conf(5),
     hostname(7), named(8)

HISTORY    [Toc]    [Back]

     The herror() function appeared in 4.3BSD.  The endhostent(),
     gethostbyaddr(),    gethostbyname(),    gethostent(),    and
sethostent() functions
 appeared in 4.2BSD.

CAVEATS    [Toc]    [Back]

     If  the search routines in resolv.conf(5) decide to read the
/etc/hosts
     file, gethostent() and other functions will  read  the  next
line of the
     file, re-opening the file if necessary.

     The  sethostent()  function  opens  and/or  rewinds the file
/etc/hosts.  If
     the stayopen argument is non-zero,  the  file  will  not  be
closed after each
     call     to     gethostbyname(),     gethostbyname2(),    or
gethostbyaddr().

     The endhostent() function closes the file.

BUGS    [Toc]    [Back]

     These functions use static data  storage;  if  the  data  is
needed for future
     use,  it  should be copied before any subsequent calls overwrite it.  Only
     the Internet address formats are currently understood.

     YP does not support any address families other than  AF_INET
and uses the
     traditional database format.

OpenBSD      3.6                          March      13,     1997