The GNU C Library - Host Names

Host Names

Besides the standard numbers-and-dots notation for Internet addresses, you can also refer to a host by a symbolic name. The advantage of a symbolic name is that it is usually easier to remember. For example, the machine with Internet address `128.52.46.32' is also known as `churchy.gnu.ai.mit.edu'; and other machines in the `gnu.ai.mit.edu' domain can refer to it simply as `churchy'.

Internally, the system uses a database to keep track of the mapping between host names and host numbers. This database is usually either the file `/etc/hosts' or an equivalent provided by a name server. The functions and other symbols for accessing this database are declared in `netdb.h'. They are BSD features, defined unconditionally if you include `netdb.h'.

Data Type struct hostent

This data type is used to represent an entry in the hosts database. It has the following members:

char *h_name

This is the ``official'' name of the host.

char **h_aliases

These are alternative names for the host, represented as a null-terminated vector of strings.

int h_addrtype

This is the host address type; in practice, its value is always AF_INET . In principle other kinds of addresses could be represented in the data base as well as Internet addresses; if this were done, you might find a value in this field other than AF_INET . See Socket Addresses.

int h_length

This is the length, in bytes, of each address.

char **h_addr_list

This is the vector of addresses for the host. (Recall that the host might be connected to multiple networks and have different addresses on each one.) The vector is terminated by a null pointer.

char *h_addr

This is a synonym for h_addr_list[0] ; in other words, it is the first host address.

As far as the host database is concerned, each address is just a block of memory h_length bytes long. But in other contexts there is an implicit assumption that you can convert this to a struct in_addr or an unsigned long int . Host addresses in a struct hostent structure are always given in network byte order; see Byte Order.

You can use gethostbyname or gethostbyaddr to search the hosts database for information about a particular host. The information is returned in a statically-allocated structure; you must copy the information if you need to save it across calls.

Function struct hostent * gethostbyname (const char *name)

The gethostbyname function returns information about the host named name. If the lookup fails, it returns a null pointer.

Function struct hostent * gethostbyaddr (const char *addr, int length, int format)

The gethostbyaddr function returns information about the host with Internet address addr. The length argument is the size (in bytes) of the address at addr. format specifies the address format; for an Internet address, specify a value of AF_INET .

If the lookup fails, gethostbyaddr returns a null pointer.

If the name lookup by gethostbyname or gethostbyaddr fails, you can find out the reason by looking at the value of the variable h_errno . (It would be cleaner design for these functions to set errno , but use of h_errno is compatible with other systems.) Before using h_errno , you must declare it like this:

	extern int h_errno;

Here are the error codes that you may find in h_errno :

HOST_NOT_FOUND

No such host is known in the data base.

TRY_AGAIN

This condition happens when the name server could not be contacted. If you try again later, you may succeed then.

NO_RECOVERY

A non-recoverable error occurred.

NO_ADDRESS

The host database contains an entry for the name, but it doesn't have an associated Internet address.

You can also scan the entire hosts database one entry at a time using sethostent , gethostent , and endhostent . Be careful in using these functions, because they are not reentrant.

Function void sethostent (int stayopen)

This function opens the hosts database to begin scanning it. You can then call gethostent to read the entries.

If the stayopen argument is nonzero, this sets a flag so that subsequent calls to gethostbyname or gethostbyaddr will not close the database (as they usually would). This makes for more efficiency if you call those functions several times, by avoiding reopening the database for each call.

Function struct hostent * gethostent ()

This function returns the next entry in the hosts database. It returns a null pointer if there are no more entries.

Function void endhostent ()

This function closes the hosts database.