11.20 Obsolete IPv6 Address Lookup Functions

While IPv6 was being developed, the API to request the lookup of an IPv6 address went through several iterations. The resulting API was complicated and not sufficiently flexible, so it was deprecated in RFC 2553 [Gilligan et al. 1999]. RFC 2553 introduced its own new functions, which were finally simply replaced by getaddrinfo and getnameinfo in RFC 3493 [Gilligan et al. 2003]. This section briefly describes some of the old API to assist in the conversion of programs using the old API.

The `RES_USE_INET6` Constant

Since gethostbyname doesn't have an argument to specify what address family is of interest (like getaddrinfo's hints.ai_family struct entry), the first revision of the API used the RES_USE_INET6 constant, which had to be added to the resolver flags using a private, internal interface. This API was not very portable since systems that used a different internal resolver interface had to mimic the BIND resolver interface to provide it.

Enabling RES_USE_INET6 caused gethostbyname to look up AAAA records first, and only look up A records if a name had no AAAA records. Since the hostent structure only has one address length field, gethostbyname could only return either IPv6 or IPv4 addresses, but not both.

Enabling RES_USE_INET6 also caused gethostbyname2 to return IPv4 addresses as IPv4-mapped IPv6 addresses. We will describe gethostbyname2 next .

The `gethostbyname2` Function

The gethostbyname2 function adds an address family argument to gethostbyname .

#include <sys/socket.h>

#include <netdb.h>

struct hostent *gethostbyname2 (const char * name , int af ) ;

Returns: non-null pointer if OK, NULL on error with h_errno set

When the af argument is AF_INET , AF_INET , gethostbyname2 behaves just like gethostbyname , looking up and returning IPv4 addresses. When the af argument is AF_INET6 , AF_INET6 , gethostbyname2 looks up and returns only AAAA records for IPv6 addresses.

The `getipnodebyname` Function

RFC 2553 [Gilligan et al. 1999] deprecated RES_USE_INET6 and gethostbyname2 because of the global nature of the RES_USE_INET6 flag and the wish to provide more control over the returned information. It introduced the getipnodebyname function to solve some of these problems.

#include <sys/socket.h>

#include <netdb.h>

struct hostent *getipnodebyname (const char * name , int af , int flags , int * error_num ) ;

Returns: non-null pointer if OK, NULL on error with error_num set

This function returns a pointer to the same hostent structure that we described with gethostbyname . The af and flags arguments map directly to getaddrinfo's hints.ai_family and hints.ai_flags arguments. For thread safety, the return value is dynamically allocated, so it must be freed with the freehostent function.

#include <netdb.h>

void freehostent (struct hostent *ptr ) ;

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

The getipnodebyname and its matching getipnodebyaddr functions are deprecated by RFC 3493 [Gilligan et al. 2003] in favor of getaddrinfo and getnameinfo .

11.21 Other Networking Information

Our focus in this chapter has been on hostnames and IP addresses and service names and their port numbers . But looking at the bigger picture, there are four types of information ( related to networking) that an application might want to look up: hosts, networks, protocols, and services. Most lookups are for hosts ( gethostbyname and geth ²stbyaddr ), with a smaller number for services ( getservbyname and getservbyaddr ), and an even smaller number for networks and protocols.

All four types of information can be stored in a file and three functions are defined for each of the four types:

A getXXXent function that reads the next entry in the file, opening the file if necessary.
A setXXXent function that opens (if not already open ) and rewinds the file.
An endXXXent function that closes the file.

Each of the four types of information defines its own structure, and the following definitions are provided by including the <netdb.h> header: the hostent , netent , protoent , and servent structures.

In addition to the three get , set , and end functions, which allow sequential processing of the file, each of the four types of information provides some keyed lookup functions. These functions go through the file sequentially (calling the getXXXent function to read each line), but instead of returning each line to the caller, these functions look for an entry that matches an argument. These keyed lookup functions have names of the form getXXXbyYYY . For example, the two keyed lookup functions for the host information are gethostbyname (look for an entry that matches a hostname) and gethostbyaddr (look for an entry that matches an IP address). Figure 11.21 summarizes this information.

Figure 11.21. Four types of network-related information.

graphics/11fig21.gif

How does this apply when the DNS is being used? First, only the host and network information is available through the DNS. The protocol and service information is always read from the corresponding file. We mentioned earlier in this chapter (with Figure 11.1) that different implementations employ different ways for the administrator to specify whether to use the DNS or a file for the host and network information.

Second, if the DNS is being used for the host and network information, then only the keyed lookup functions make sense. You cannot, for example, use gethostent and expect to sequence through all entries in the DNS! If gethostent is called, it reads only the /etc/hosts file and avoids the DNS.

Although the network information can be made available through the DNS, few people set this up. [Albitz and Liu 2001] describes this feature. Typically, however, administrators build and maintain an /etc/networks file and it is used instead of the DNS. The netstat program with the -i option uses this file, if present, and prints the name for each network. However, classless addressing (Appendix A) makes these functions fairly useless, and these functions do not support IPv6 at all, so new applications should avoid using network names.