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

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