packages/net/tcpip/v2_0/doc/gethost.man

   1 NAME
   2        gethostbyname, gethostbyaddr, herror, hstrerror - get network host entry
   3
   4 SYNOPSIS
   5        #include <network.h>
   6
   7        struct hostent *gethostbyname(const char *name);
   8
   9        struct hostent *gethostbyaddr(const char *addr, int len, int type);
  10
  11        void herror(const char *s);
  12
  13        const char * hstrerror(int err);
  14
  15 DESCRIPTION
  16        The gethostbyname() function returns a structure  of  type
  17        hostent  for  the  given host name.  Here name is either a
  18        host name, or an IPv4 address in standard dot notation, or
  19        an IPv6 address in colon (and possibly dot) notation. (See
  20        RFC 1884 for the description of IPv6 addresses.)  If  name
  21        is  an  IPv4  or  IPv6 address, no lookup is performed and
  22        gethostbyname() simply copies name into the  h_name  field
  23        and  its struct in_addr equivalent into the h_addr_list[0]
  24        field of the returned hostent structure.  If name  doesn't
  25        end  in  a dot and the environment variable HOSTALIASES is
  26        set, the alias file pointed to by HOSTALIASES  will  first
  27        be  searched for name.  (See hostname(7) for the file for
  28        mat.)  The current domain and  its  parents  are  searched
  29        unless name ends in a dot.
  30
  31        The  gethostbyaddr()  function returns a structure of type
  32        hostent for the given host address addr of length len  and
  33        address  type  type.   The only valid address type is cur
  34        rently AF_INET.
  35
  36        The  (obsolete) herror() function prints the error message
  37        associated with the current value of h_errno on stderr.
  38
  39        The (obsolete) hstrerror() function takes an error  number
  40        (typically  h_errno) and returns the corresponding message
  41        string.
  42
  43        The domain name queries carried out by gethostbyname() and
  44        gethostbyaddr()  use  a  combination  of any or all of the
  45        name server named(8), a broken out line  from  /etc/hosts,
  46        and the Network Information Service (NIS or YP), depending
  47        upon the contents of the  order  line  in  /etc/host.conf.
  48        (See   resolv+(8)).    The  default  action  is  to  query
  49        named(8), followed by /etc/hosts.
  50
  51        The hostent structure is defined in <netdb.h> as follows:
  52
  53               struct hostent {
  54                       char    *h_name;        /* official name of host */
  55                       char    **h_aliases;    /* alias list */
  56                       int     h_addrtype;     /* host address type */
  57                       int     h_length;       /* length of address */
  58                       char    **h_addr_list;  /* list of addresses */
  59               }
  60               #define h_addr  h_addr_list[0]  /* for backward compatibility */
  61
  62        The members of the hostent structure are:
  63
  64        h_name The official name of the host.
  65
  66        h_aliases
  67               A zero-terminated array of  alternative  names  for
  68               the host.
  69
  70        h_addrtype
  71               The type of address; always AF_INET at present.
  72
  73        h_length
  74               The length of the address in bytes.
  75
  76        h_addr_list
  77               A  zero-terminated  array  of network addresses for
  78               the host in network byte order.
  79
  80        h_addr The first address in h_addr_list for backward  com
  81               patibility.
  82
  83 RETURN VALUE
  84        The  gethostbyname()  and gethostbyaddr() functions return
  85        the hostent structure  or  a  NULL  pointer  if  an  error
  86        occurs.   On  error,  the  h_errno variable holds an error
  87        number.
  88
  89 ERRORS
  90        The variable h_errno can have the following values:
  91
  92        HOST_NOT_FOUND
  93               The specified host is unknown.
  94
  95        NO_ADDRESS or NO_DATA
  96               The requested name is valid but does not have an IP
  97               address.
  98
  99        NO_RECOVERY
 100               A non-recoverable name server error occurred.
 101
 102        TRY_AGAIN
 103               A temporary error occurred on an authoritative name
 104               server.  Try again later.