gethostent(3N) — Series 300/400

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.

Name Service Switch based Operation

The above mentioned library routines internally call the name service switch to access the "hosts" database lookup policy configured in the /etc/nsswitch.conf (see switch(4)) file. The lookup policy defines the order and the criteria used to resolve host names and internet addresses using one or more of the alternate database operations listed below i.e. the Name Server, the NIS server or the non-server operations.

Name Server Operation

If the named name server (see named (1M)) is used for name or address resolution, then the function :

gethostent() Always returns a NULL pointer.

sethostent(), Requests the use of a connected stream socket for queries to the name server if the stayopen flag is non-zero. The connection is retained after each call to gethostbyname() or gethostbyaddr().

endhostent() Closes the stream socket connection.

gethostbyname()

gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, berkeley.edu, Berkeley.EDU , and BERKELEY.EDU all match the entry for berkeley.edu.

NIS Server Operation

If ypserv, the Network Information Service server is used for name or address resolution, then the function :

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

gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, berkeley.edu, Berkeley.EDU , and BERKELEY.EDU all match the entry for berkeley.edu.

Non-Server Operation

If /etc/hosts file is used for name or address resolution, then the function :

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 name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case.

gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its addr parameter 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.

ERRORS

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