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 ‘158.121.106.19’ is also
known as ‘alpha.gnu.org’; and other machines in the ‘gnu.org’ domain can refer to it
simply as ‘alpha’.
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’.
struct hostent [Data Type]
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 either AF_
INET or AF_INET6, with the latter being used for IPv6 hosts. In principle
other kinds of addresses could be represented in the database as well as
Internet addresses; if this were done, you might find a value in this field
other than AF_INET or AF_INET6.
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 IPv4 addresses to a struct in_addr or an uint32_t. Host addresses in a struct
hostent structure are always given in network byte order;
You can use gethostbyname, gethostbyname2 or gethostbyaddr to search the hosts
database for information about a particular host. The information is returned in a staticallyallocated
structure; you must copy the information if you need to save it across calls. You
can also use getaddrinfo and getnameinfo to obtain this information.
struct hostent * gethostbyname (const char *name) [Function]
The gethostbyname function returns information about the host named name. If the
lookup fails, it returns a null pointer.
struct hostent * gethostbyname2 (const char *name, int af) [Function]
The gethostbyname2 function is like gethostbyname, but allows the caller to specify
the desired address family (e.g. AF_INET or AF_INET6) of the result.
struct hostent * gethostbyaddr (const char *addr, size t length, int format) [Function]
The gethostbyaddr function returns information about the host with Internet address
addr. The parameter addr is not really a pointer to char - it can be a pointer to
an IPv4 or an IPv6 address. The length argument is the size (in bytes) of the address
at addr. format specifies the address format; for an IPv4 Internet address, specify a
value of AF_INET; for an IPv6 Internet address, use AF_INET6.
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.)
Here are the error codes that you may find in h_errno:
HOST_NOT_FOUND
No such host is known in the database.
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.
The lookup functions above all have one in common: they are not reentrant and therefore
unusable in multi-threaded applications. Therefore provides the GNU C library a new set
of functions which can be used in this context.
int gethostbyname_r (const char *restrict name, struct hostent *restrict [Function]
result_buf, char *restrict buf, size t buflen, struct hostent **restrict
result, int *restrict h_errnop)
The gethostbyname_r function returns information about the host named name.
The caller must pass a pointer to an object of type struct hostent in the result buf
parameter. In addition the function may need extra buffer space and the caller must
pass an pointer and the size of the buffer in the buf and buflen parameters.
A pointer to the buffer, in which the result is stored, is available in *result after
the function call successfully returned. If an error occurs or if no entry is found, the
pointer *result is a null pointer. Success is signalled by a zero return value. If the
function failed the return value is an error number. In addition to the errors defined
for gethostbyname it can also be ERANGE. In this case the call should be repeated
with a larger buffer. Additional error information is not stored in the global variable
h_errno but instead in the object pointed to by h errnop.
Here’s a small example:
struct hostent *
gethostname (char *host)
{
Chapter 16: Sockets 404
struct hostent hostbuf, *hp;
size_t hstbuflen;
char *tmphstbuf;
int res;
int herr;
hstbuflen = 1024;
/* Allocate buffer, remember to free it to avoid memory leakage. */
tmphstbuf = malloc (hstbuflen);
while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
&hp, &herr)) == ERANGE)
{
/* Enlarge the buffer. */
hstbuflen *= 2;
tmphstbuf = realloc (tmphstbuf, hstbuflen);
}
/* Check for errors. */
if (res || hp == NULL)
return NULL;
return hp;
}
int gethostbyname2_r (const char *name, int af, struct hostent [Function]
*restrict result_buf, char *restrict buf, size t buflen, struct hostent
**restrict result, int *restrict h_errnop)
The gethostbyname2_r function is like gethostbyname_r, but allows the caller to
specify the desired address family (e.g. AF_INET or AF_INET6) for the result.
int gethostbyaddr_r (const char *addr, size t length, int format, [Function]
struct hostent *restrict result_buf, char *restrict buf, size t buflen, struct
hostent **restrict result, int *restrict h_errnop)
The gethostbyaddr_r function returns information about the host with Internet
address addr. The parameter addr is not really a pointer to char - it can be a pointer
to an IPv4 or an IPv6 address. The length argument is the size (in bytes) of the
address at addr. format specifies the address format; for an IPv4 Internet address,
specify a value of AF_INET; for an IPv6 Internet address, use AF_INET6.
Similar to the gethostbyname_r function, the caller must provide buffers for the
result and memory used internally. In case of success the function returns zero.
Otherwise the value is an error number where ERANGE has the special meaning that
the caller-provided buffer is too small.
You can also scan the entire hosts database one entry at a time using sethostent,
gethostent and endhostent. Be careful when using these functions because they are not
reentrant.
void sethostent (int stayopen) [Function]
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.
Chapter 16: Sockets 405
struct hostent * gethostent (void) [Function]
This function returns the next entry in the hosts database. It returns a null pointer
if there are no more entries.
void endhostent (void) [Function]
This function closes the hosts database.