getaddrinfo(3N)

getaddrinfo()

Hostname-to-address translation is done in a protocol-independent fashion using the getaddrinfo() function.

The getaddrinfo() function returns an integer. The input arguments hostname and servname are pointers to null-terminated strings or NULL. One or both of these two arguments must be a non-NULL pointer.

In the normal client scenario, both hostname and servname are specified. The non-NULL hostname string can be either a hostname or a numeric host address string (a dotted-decimal IPv4 address or a hexadecimal IPv6 address). The non-NULL servname string can be either a service name or a decimal port number. However, in the server scenario, only servname is specified.

The third input argument is a pointer to the structure of type addrinfo defined as follows in <netdb.h>:

The members of this structure are:

The above argument is optional. If the caller wants to provide information such as the type of socket and protocol family that the caller supports, the caller can specify them using the addrinfo structure. When this information is passed to getaddrinfo(), all the fields other then ai_flags, ai_family, ai_socktype, and ai_protocol must be set to zero or a NULL pointer.

When it returns successfully, **res holds a pointer to a linked list of one or more addrinfo structures. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a NULL pointer is encountered. In each of the returned addrinfo structures, the three members ai_family, ai_socktype, and ai_protocol are used as arguments to the socket() function call. The ai_addr member points to a socket address structure whose length is specified by the ai_addrlen member.

The return value from the getaddrinfo() function is 0 upon success, or a nonzero error code. The following are the nonzero error codes given by getaddrinfo(). These are defined in <netdb.h>:

freeaddrinfo()

All the information returned by getaddrinfo() is dynamically allocated: the addrinfo structures, the socket address structures, and canonical host name strings pointed to by the addrinfo structures. To return this information to the system, the function freeaddrinfo() is called:

The addrinfo structure pointed to by the ai argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated until a NULL ai_next pointer is encountered.

gai_strerror()

To aid applications in printing error messages based on the EAI_xxx codes returned by getaddrinfo(), the gai_strerror function is defined.

The argument is one of the EAI_xxx values defined earlier, and the return value points to a string describing the error. If the argument is not one of the EAI_xxx values, the function still returns a pointer to a string whose contents indicate an unknown error.

getnameinfo()

The getnameinfo() function is used to look up a hostname and service name, given the binary address and port. The function is defined as follows:

This function looks up an IP address and port number provided by the caller in the DNS and system-specific database, and returns text strings for both in buffers provided by the caller.

The function indicates successful completion by a zero return value; a non-zero return value indicates failure.

If the address is IPv6 unspecified address ( :: ), then the following actions occur:

The host argument contains the numeric form of the IPv6 address and getnameinfo() does not perform a lookup for the IPv6 address.

The first argument, sa, points to either a sockaddr_in structure (for IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address and port number. The salen argument gives the length of the sockaddr_in or sockaddr_in6 structure.

The function returns the hostname associated with the IP address in the buffer pointed to by the host argument. The caller provides the size of this buffer via the hostlen argument. The service name associated with the port number is returned in the buffer pointed to by serv, and the servlen argument gives the length of this buffer. The caller specifies not to return either string by providing zero values for the hostlen or servlen arguments. Otherwise, the caller must provide buffers large enough to hold the hostname and the service name, including the terminating null characters.

Unfortunately, most systems do not provide constants that specify the maximum size of either a fully-qualified domain name or a service name. Therefore, to aid the application in allocating buffers for these two returned strings, the following constants are defined in <netdb.h>:

In recent versions of DNS/BIND, the first value NI_MAXHOST is actually defined as the constant MAXDNAME in the header file <arpa/nameser.h>. (Older versions of BIND define this constant to be 256.)

The final argument to the getnameinfo() function is a flag that changes the default actions of this function. By default, the fully-qualified domain name (FQDN) for the host is looked up in the DNS and returned. If the flag bit NI_NOFQDN is set, only the hostname portion of the FQDN is returned for local hosts.

If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be located in the DNS, the numeric form of the host's address is returned instead of its name (by calling inet_ntop() instead of gethostbyaddr()).

If the flag bit NI_NAMEREQD is set, an error is returned if the host's name cannot be located in the DNS.

If the flag bit NI_NUMERICSERV is set, the numeric form of the service address (port number) is returned instead of its name. The two NI_NUMERICxxx flags are required to support the -n flag that many commands provide.

A fifth flag bit, NI_DGRAM, specifies that the service is a datagram service, and causes getservbyport() to be called with a second argument of "udp" instead of its default of "tcp". This is required for the few ports (512-514) that have different services for UDP and TCP.

These NI_xxx flags are defined in <netdb.h> along with the AI_xxx flags already defined for getaddrinfo().

Name Service Switch-Based Operation

The getnameinfo() and getaddrinfo() library routines internally call the name service switch to access the ipnodes database lookup policy configured in the /etc/nsswitch.conf file (see nsswitch.conf(4)) for the name/address resolution, and services database lookup policy for the service/port resolution. The lookup policy defines the order and criteria of the supported name services that can be used for resolution. If addresses are not gathered after contacting all the ipnodes directives, and if the caller has set the ai_family to AF_INET or set ai_flags to AI_V4MAPPED with an ai_family of AF_INET6, getaddrinfo()/getnameinfo() use the hosts directive in the /etc/nsswitch.conf file to resolve the hostname/address. In this case, when the hosts directive hostname/address resolution fails, the error number returned will be that of the error returned by the hosts directive lookup. The operations of these name services, Domain Name Server and Nonserver Modes, are described below:

Nonserver Operation

During a name/address resolution, if the database is configured for files resolution, getnameinfo() and getaddrinfo() use the /etc/hosts file for resolution. Similarly, if the services database is configured for files resolution, the /etc/services file is used for resolution. If the /etc/hosts file is used for name/address resolution, the method used by the functions getnameinfo() and getaddrinfo() to search an address is listed below:

Obsolescent Interfaces

The following interfaces are included to support existing applications and may be removed in future releases.

New applications must use the APIs getaddrinfo() and getnameinfo() for name/address resolution.

Obsolescent Directive

The ipnodes directive, which is used by the getaddrinfo() and getnameinfo() APIs, may not be supported in future HP-UX releases. In order to minimize the impact to applications, it is recommended that you have the same configuration for the hosts and the ipnodes directives.