GETHOSTENT

C Interface

        #include <sys/types.h>

        #include <sys/socket.h>

        #include <netinet/in.h>

        #include <netdb.h>



        extern int h_errno;



        struct hostent *gethostent()



        struct hostent *gethostbyname(name)

        char *name;



        struct hostent *gethostbyaddr(addr, len, type)

        char *addr;

        int len, type;



        sethostent(stayopen)

        int stayopen;



        endhostent()

Description

The gethostent, gethostbyname, and gethostbyaddr subroutines return a pointer to a structure defined as follows in netdb.h:

   struct  hostent {

   char   *h_name;         /* official name of host             */

   char   **h_aliases;     /* alias list                        */

   int    h_addrtype;      /* 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 as follows:

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; currently always AF_INET.
h_length: The length, in bytes, of the address.
h_addr_list: A null-terminated array of network addresses for the host.
h_addr: The first address in h_addr_list; this is for compatibility with previous HP-UX implementations, where a struct hostent contains only one network address per host.

If the local system is configured to use the name server, then:

The gethostent subroutine always returns a null pointer.
The sethostent subroutine, if the stayopen flag is non-zero, requests the use of a connected stream socket for queries to the name server. The connection is retained after each call to gethostbyname or gethostbyaddr.
The endhostent subroutine closes the stream socket connection.

The gethostbyname and gethostbyaddr subroutines each retrieve host information from the name server through the resolver. Names are matched in a case-insensitive manner; for example, berkeley.edu, Berkeley.EDU, and BERKELEY.EDU would all match the entry for berkeley.edu.

The resolver reads the configuration file RESLVCNF.NET.SYS to get the default domain name and the Internet address of the initial hosts running the name server. If the environment variable LOCALDOMAIN is set by the user, that name is used as the default domain (overriding any other default). If the name server Internet addresses are not listed in the configuration file, the resolver aborts and the hosts file is tried (see below). If there are errors in the configuration file, they are silently ignored.

If the local system is not using the name server, then:

The gethostent subroutine reads the next line of HOSTS.NET.SYS, opening the file if necessary.
The sethostent subroutine opens and rewinds the file. If the stayopen flag is non-zero, the host database is not closed after each call to gethostent (either directly or indirectly through one of the other gethost calls).
The endhostent subroutine closes the file.
The gethostbyname subroutine sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its parameter name is found, or until EOF is encountered. Names are matched in a case-insensitive manner; for example, berkeley.edu, Berkeley.EDU, and BERKELEY.EDU would all match the entry for berkeley.edu.
The gethostbyaddr subroutine sequentially searches from the beginning of the file until an Internet address matching its parameter addr is found, or until EOF is encountered.

In calls to gethostbyaddr, the parameter addr must point to an internet address in network order (refer to the inet section) and the addr parameter must be 4-byte aligned, or an escape is generated. The parameter len must be the number of bytes in an Internet address, that is, sizeof (struct in_addr). The parameter type must be the constant AF_INET.

Return Value

If successful, gethostbyname, gethostbyaddr, and gethostent return a pointer to the requested hostent struct. The gethostbyname and gethostbyaddr subroutines return NULL if their host or addr parameters, respectively, cannot be found in the database. If hosts.net.sys is being used, they also return NULL if they are unable to open hosts.net.sys. The gethostbyaddr subroutine also returns NULL if either its addr or len parameter is invalid. The gethostent subroutine always returns NULL if the name server is being used.

If the name server is being used and gethostbyname or gethostbyaddr returns a NULL pointer, the external integer h_errno contains one of 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 time later may succeed.
[NO_RECOVERY]: This is a non-recoverable error.
[NO_ADDRESS]: The requested name is valid but has no IP address; this is not a temporary error. This means that another type of request to the name server results in an answer.

If the name server is not being used, the value of h_errno may not be meaningful.

Restrictions

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.

MPE/iX Specific

The names of the hosts file and resolver configuration file on MPE/iX are HOSTS.NET.SYS and RESLVCNF.NET.SYS, as opposed to /etc/hosts and /etc/resolv.conf on HP-UX.

Author

UCB (University of California at Berkeley)

Files

HOSTS.NET.SYS, RESLVCNF.NET.SYS