GETHOSTBYNAME(3N)   RISC/os Reference Manual    GETHOSTBYNAME(3N)



NAME
     gethostbyname, gethostbyaddr, gethostent, sethostent,
     endhostent - get network host entry

SYNOPSIS
   Headers
     For -systype sysv:

     #include <bsd/sys/types.h>
     #include <bsd/netdb.h>

     For -systype bsd43:

     #include <netdb.h>

   Declarations
     extern int herrno;

     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()

DESCRIPTION
     gethostbyname and gethostbyaddr each return a pointer to an
     object with the following structure.  This structure con-
     tains 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.




                         Printed 1/15/91                   Page 1

GETHOSTBYNAME(3N)   RISC/os Reference Manual    GETHOSTBYNAME(3N)



     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.

     sethostent allows a request for the use of a connected
     socket using TCP 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.

     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 tem-
     porary failure or an invalid or unknown host.

     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 authorita-
                          tive server.  A retry at some later
                          time may succeed.

          NO_RECOVERY     This is a non-recoverable 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.

FILES
     /etc/hosts





 Page 2                  Printed 1/15/91

GETHOSTBYNAME(3N)   RISC/os Reference Manual    GETHOSTBYNAME(3N)



SEE ALSO
     resolver(3), hosts(4), resolv.conf(4).
     named(8) in the System Administrator's Reference Manual.

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.

ERRORS
     All information is contained in a static area so it must be
     copied if it is to be saved.  Only the Internet address for-
     mat is currently understood.

NOTE
     When these routines are used in a program which is compiled
     in -systype sysv, they are not resolved by libc.a.  See
     intro(3-SysV) for more information.





























                         Printed 1/15/91                   Page 3