gethostbyname(3)                    CLIX                    gethostbyname(3)



  NAME

    gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent - Gets a
    network host entry

  LIBRARY

    Berkeley Software Distribution Library (libbsd.a)

  SYNOPSIS

    #include <netdb.h>

    extern int h_errno;

    struct hostent *gethostbyname(
      char *name );

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

    struct hostent *gethostent(
      void );

    void sethostent(
      int stayopen );

    void endhostent(
      void );

  DESCRIPTION

    The commands gethostbyname and gethostbyaddr return a pointer to an object
    with the following structure.  This structure contains information
    obtained from the broken-out fields from a line in the file /etc/hosts,
    or, if the local host is configured to be a Domain Name System (DNS)
    client, from a query to its nameserver.  The DNS query is attempted first.
    If the DNS query fails, a local lookup in /etc/hosts is attempted.

    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, backward compatibility */




  2/94 - Intergraph Corporation                                              1

  gethostbyname(3)                    CLIX                    gethostbyname(3)



    The members of this structure are as follows:

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

    The command sethostent allows a request for the use of a connected socket
    using Transmission Control Protocol (TCP) for queries.  A nonzero stayopen
    flag 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.

    The command endhostent closes the TCP connection.

    The commands gethostbyname and gethostbyaddr sequentially search from the
    beginning of the file until a matching hostname or address and type is
    found or until EOF is encountered.  Internet addresses may be obtained
    from character strings representing numbers expressed in the Internet
    standard ``.'' notation with the functions described in inet().  If an
    address is supplied, the length of the address must also be supplied.

  FILES

    /etc/hosts
           Host name database.

    /etc/resolv.conf
           DNS client configuration file.

  RETURN VALUES

    Error return status from gethostbyname and gethostbyaddr is indicated by
    the 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 command h_errno can have the following values:

    HOST_NOT_FOUND
           No such host is known.



  2                                              Intergraph Corporation - 2/94

  gethostbyname(3)                    CLIX                    gethostbyname(3)



    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
           This is a nonrecoverable error.

    NO_ADDRESS
           The requested name is valid but does not have an IP address; this
           is not a temporary error.  This means another type of request to
           the name server will result in an answer.

  BUGS

    All information is contained in a static area so it must be copied to be
    saved.  Only the Internet address format is currently understood.

  NOTES

    The command gethostent reads the next line of /etc/hosts, opening the file
    if necessary.

    DNS expects and returns fully-qualified names (e.g. host.dom.ain) in all
    transactions.  In forming a query the DNS resolver appends the default
    domain from /etc/resolv.conf.

    The h_aliases list is not filled in the case of a DNS response.

    The command sethostent is redefined to open and rewind the file.  If the
    stayopen argument is nonzero, the hosts database will not be closed after
    each call to gethostbyname or gethostbyaddr.  The command endhostent is
    redefined to close the file.

  RELATED INFORMATION

    Function: hosts(4)

    Commands: namex(8)















  2/94 - Intergraph Corporation                                              3