gethostent(3N)

Requires Optional LAN/X.25 Software

NAME

gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent − get network host entry

SYNOPSIS

#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>

extern int h_errno;

struct hostent ∗gethostent(void);

struct hostent ∗gethostbyname(const char ∗name);

struct hostent ∗gethostbyaddr(

const char ∗addr,
int len,
int type);

int sethostent(int stayopen);

int endhostent(void);

DESCRIPTION

gethostent, gethostbyname, and gethostbyaddr each return a pointer to a structure of type hostent, defined as follows in <netdb.h>:

struct hostent {
        char    *h_name;
        char    **h_aliases;
        int     h_addrtype;
        int     h_length;
        char    **h_addr_list;
};
#define h_addr h_addr_list[0]

The members of this structure are:

h_name The 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; 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, named(1M):

• gethostent always returns a NULL pointer.

• sethostent, 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.

• endhostent closes the stream socket connection.

• gethostbyname and gethostbyaddr each retrieve host information from the name server. 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.

If the local system is not configured to use the name server but is running the Network Information Service server, ypserv(1M):

• gethostent returns the next entry in the NIS database.

• sethostent initializes an internal key for the NIS database. If the stayopen flag is non-zero, the internal key is not cleared after calls to endhostent.

• endhostent clears the internal NIS database key.

• gethostbyname and gethostbyaddr each retrieve host information from the NIS database. Names are matched in a case-sensitive manner. For example, berkeley.edu match the entry for berkeley.edu, but Berkeley. EDU and BERKELEY.EDU do not.

If the local system is using neither the local name server nor the Network Information Service server:

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

• sethostent opens and rewinds the file. If the stayopen flag is non-zero, the host data base is not closed after each call to gethostent (either directly or indirectly through one of the other gethost calls).

• endhostent closes the file.

• gethostbyname 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, as described above in the name server case.

• gethostbyaddr 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 (see byteorder(3N)). 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. gethostbyname and gethostbyaddr return NULL if their host or addr parameters, respectively, cannot be found in the database. If /etc/hosts is being used, they also return NULL if they are unable to open /etc/hosts. gethostbyaddr also returns NULL if either its addr or len parameter is invalid. gethostent always returns NULL if the name server is being used.

DIAGNOSTICS

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

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

WARNINGS

All information is contained in a static area so it must be copied if it is to be saved.

AUTHOR

gethostent was developed by the University of California, Berkeley.

FILES

/etc/hosts

Museum

Related Articles