Protocol-independent node name and service name translation

The getaddrinfo function is considered a replacement for the existing gethostbyname and getservbyname APIs. The getaddrinfo function takes an input host name, an input service name, or both, and returns one or more addrinfo structures upon successful resolution. The getaddrinfo function also accepts a host name or service name in numerical form as input, and returns the same value in presentation form by using the addrinfo structure. An addrinfo structure contains the following output information:

A pointer to a sockaddr_in or sockaddr_in6 structure containing an IP address and service port. For IPv6 link-local addresses, the sockaddr_in6 structure might contain the zone index, if scope information was provided as part of the input host name. See Scope information about getaddrinfo calls for details.
Length of sockaddr structure and family type (AF_INET, AF_INET6) of the sockaddr structure
Socktype and protocol values usable with this sockaddr structure
Pointer to canonical name associated with the input host name (applicable only in the first addrinfo structure)
Pointer to next addrinfo structure (set to 0 in the last element of the chain)

The storage for the addrinfo structures is allocated by the resolver from the application's address space, and the application should use the freeaddrinfo API to release the addrinfo structures when the information is no longer required. The application should not manipulate the chain of addrinfo structures returned by way of getaddrinfo, but rather the application should simply return the entire chain, as received, to the resolver by way of freeaddrinfo.

In addition to hostname or servicename, one of which must be present on a valid getaddrinfo invocation, the application can specify additional input to the resolver on the getaddrinfo invocation. This input is optional, and if specified, is passed by way of an input addrinfo structure. The input settings include the following possibilities:

Family type of sockaddr structure required on output.
Socktype and protocol values for which the returned IP address and port number must work. This would be used primarily for cases where a service name was being resolved, as might typically have been done previously by way of getservbyname.
Various input flag settings include the following settings:
- AI_ADDRCONFIG
- AI_ALL
- AI_CANONNAME
- AI_NUMERICHOST
- AI_NUMERICSERV
- AI_PASSIVE
- AI_V4MAPPED

If no specific input from the application is provided, the resolver assumes that any sockaddr type (that is, both IPv4 and IPv6 addresses) is acceptable as output. Thus, by default, the resolver searches for both IPv6 and IPv4 addresses by way of DNS or by way of local host files (such as /etc/hosts). This searching might not always be the best choice for the application that issues getaddrinfo. By using the input fields, an application that issues getaddrinfo() can influence the processing that the resolver function provides for that request in the following ways:

The application can specify that the sockaddr returned by getaddrinfo should be of family type AF_INET, AF_INET6 or AF_UNSPEC (meaning either family type would be acceptable). For example, if AF_INET is specified, the resolver does not perform any searches for IPv6 addresses for hostname, because the output requested must be an IPv4 address.
The application can specify that the following addresses are returned:
- Both IPv6 and IPv4 addresses should be returned
- IPv4 should be returned only if there are no IPv6 addresses resolved
- Only IPv6 addresses should be returned
- Only IPv4 addresses should be returned.
This information, indicated by the input combination of family type and the AI_ALL and AI_V4MAPPED flags, to a large extent controls the types of searches performed by the Resolver during the course of the processing.
The application can specify that IPv6 addresses should be returned only when the system has IPv6 interfaces defined and can specify that IPv4 addresses should be returned only when IPv4 interfaces are defined. This preference, indicated by way of the AI_ADDRCONFIG flag, allows the application to eliminate resolution searches looking for addresses that cannot be used by the application.
The application can specify whether the sockaddr returned should contain an address for passive (that is, the INADDR_ANY address) or active (that is, the loopback address) socket activation. This choice is indicated by way of the AI_PASSIVE flag, and is applicable only in the absence of an input hostname value.
The application can specify that only translation from presentation to numeric format should be performed for hostname, or service name, or both. This option is indicated by setting the AI_NUMERICHOST flag (for hostname) or the AI_NUMERICSERV (for servicename) flag, which indicates that the associated input value must be in numeric format or the getaddrinfo request should be failed.
The application can specify that only a given socktype or protocol value should be used for looking up the port number associated with the input servicename, or can request that all valid socktype types and protocols (TCP and UDP) be used for the getservbyname processing. This preference is indicated by way of the socktype and protocol settings.

With such a flexible interface, the application programmer must decide what inputs are reasonable for the capabilities of the application being created or modified.

Table 1 shows the two most likely application usages and the suggested getaddrinfo input settings that coincide with that functionality:

IPv6-capable when the underlying system is IPv6 capable
IPv4-capable only

Table 1. Getaddrinfo application capabilities 1
Application capabilities	Sockaddr family to request	Additional flags to set	Expected outputs
(IPv4 only) Application is pure IPv4 and cannot handle any IPv6 addresses.	AF_INET	AI_ADDRCONFIG	Getaddrinfo returns one or more addrinfo structures, each pointing to an IPv4 address saved in an AF_INET sockaddr. No addrinfo structures are returned if there are no IPv4 interfaces defined on the system. No searches of any kind are performed for IPv6 addresses as part of this request.
(IPv6 capable) Application wants all known addresses for hostname, in IPv6 format when the system supports IPv6, or in IPv4 format otherwise.	AF_UNSPEC	One of the following groups: AI_ADDRCONFIG and AI_ALL AI_ADDRCONFIG, AI_V4MAPPED, and AI_ALL	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddrs consists of one of the following sets: All AF_INET6 sockaddrs, containing IPv6 or mapped IPv4 addresses, if the system supports IPv6 processing (only when AI_V4MAPPED coded). AF_INET6 sockaddrs, containing IPv6 addresses, and AF_INET sockaddrs, containing IPv4 addresses, if the system supports IPv6 processing (only when AI_V4MAPPED is NOT coded). All AF_INET sockaddrs, containing IPv4 addresses, if the system does not support IPv6 processing. In all cases, the IPv6 addresses are returned only if there is an IPv6 interface defined on the system, and the IPv4 addresses are returned only if there is an IPv4 interface defined.

An application with no interest in using IPv6 wants to use the first entry in Table 1; otherwise, if there is some interest in using IPv6 functionality, an application would achieve the greatest flexibility by using the second table entry. Using the IPv6 entry approach, the application places the burden of supplying a workable sockaddr structure on the Resolver logic. If IPv6 is supported on the system, the Resolver endeavors to return AF_INET6 sockaddrs to the application; otherwise, the Resolver returns AF_INET sockaddrs to the application. The choice of coding or not coding AI_V4MAPPED in this situation depends on the application's preference regarding receiving AF_INET6 sockaddrs: the more the application wants to deal exclusively with AF_INET6 sockaddrs, the more reason to code AI_V4MAPPED.

Table 1 should be sufficient for most application usages. However, there are other likely application capability models possible, and Table 2 provides some guidance on how to code the Getaddrinfo invocations for those applications.

Table 2. Getaddrinfo application capabilities 2
Application capabilities	Sockaddr family to request	Additional flags to set	Expected outputs
Application is pure IPv6 and cannot handle any mapped IPv4 addresses.	AF_INET6	AI_ADDRCONFIG	Getaddrinfo returns one or more addrinfo structures, each pointing to an IPv6 address saved in an AF_INET6 sockaddr. No addrinfo structure is returned if there are no IPv6 interfaces defined on the system. No searches of any kind are performed for IPv4 addresses as part of this request.
Application prefers IPv6 addresses, requires IPv6 address format, but can handle mapped IPv4 addresses if necessary.	AF_INET6	AI_ADDRCONFIG, AI_V4MAPPED	Getaddrinfo returns one or more addrinfo structures, each pointing to an AF_INET6 sockaddr. The addresses in the sockaddrs structure consist of one of the following sets: All IPv6 addresses, if there is an IPv6 interface defined on the system and IPv6 addresses exist for hostname All mapped IPv4 addresses, if there were no IPv6 addresses to be returned for hostname and there was an IPv4 interface defined for the system
Application prefers IPv6 addresses, but can handle native IPv4 addresses if necessary.	AF_UNSPEC	AI_ADDRCONFIG	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddrs consist of one of the following sets: All AF_INET6 sockaddrs that contain IPv6 addresses, if there is an IPv6 interface defined on the system and IPv6 addresses exist for hostname All AF_INET sockaddrs that contain IPv4 addresses, if there were no IPv6 addresses to be returned for hostname and there was an IPv4 interface defined for the system
Application wants all known addresses for hostname, in IPv6 format.	AF_INET6	AI_ADDRCONFIG, AI_V4MAPPED, AI_ALL	Getaddrinfo returns one or more addrinfo structures, each pointing to an AF_INET6 sockaddr. The addresses within the sockaddrs consist of all IPv6 addresses, if there is an IPv6 interface defined on the system, and mapped IPv4 addresses, if there is an IPv4 interface defined for the system, associated with hostname.
Application wants all known addresses for hostname, in native (IPv6 or IPv4) format.	AF_UNSPEC	AI_ADDRCONFIG, AI_ALL	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddr structures are a mixture of AF_INET6 sockaddrs (each containing an IPv6 address) and AF_INET sockaddrs (each containing an IPv4 address). The IPv6 addresses are returned only if there is an IPv6 interface defined on the system, and the IPv4 addresses are returned only if there was an IPv4 interface defined for the system.
Application wants all known addresses for hostname, regardless of system connectivity, in native format.	AF_UNSPEC	AI_ALL	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddr structures can be a mixture of AF_INET6 sockaddrs (each containing an IPv6 address) or AF_INET sockaddrs (each containing an IPv4 address), depending on the address resolution.
Default settings when IPv6 is enabled on the system.	AF_UNSPEC	NONE	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddrs consists of one of the following sets: All AF_INET6 sockaddrs, containing IPv6 addresses, if there is an IPv6 address defined for hostname in any queried domain name server or defined in a local hosts table. No searches for IPv4 addresses are performed for hostname. All AF_INET sockaddrs, containing IPv4 addresses, if there are no IPv6 addresses found for hostname. In either case, the actual availability of IPv6 or IPv4 interfaces on the system is not taken into consideration.
Default settings when IPv6 is not enabled on the system.	AF_UNSPEC	NONE	Getaddrinfo returns one or more addrinfo structures, each pointing to a sockaddr structure. The sockaddr structures can be a mixture of AF_INET6 sockaddrs (each containing an IPv6 address) or AF_INET sockaddrs (each containing an IPv4 address), depending on the address resolution performed. The actual availability of IPv6 or IPv4 interfaces on the system is not taken into consideration.

Regardless of the application model in use, and because output from getaddrinfo can be a chain of addrinfo structures, the application should attempt to use each address, in the order received, to open a socket and connect or send a datagram to the target host name until it is successful, versus simply using the first address and stopping if a failure is encountered.

The application is now responsible for freeing the storage (addrinfo and sockaddr structures, and so on) associated with the new resolver APIs. The new freeaddrinfo API should be used to free this storage. If the application neglects to perform this step, the resolver cleans up the storage when the process ends, but storage constraints might occur before termination if a large number of getaddrinfo APIs are performed.

Scope information about getaddrinfo calls

The getaddrinfo process accepts scope information as part of the input host name. Scope information is defined as an interface name or the interface index that uniquely identifies a specific interface to be used with a link-local IPv6 address (see Interface identification for information about interface indexes). An application might need to pass scope information to the resolver so that the resulting sockaddr_in6 structures have the appropriate zone index value set by the resolver. The zone index is determined using the if_nametoindex() function if the input scope information is an interface name, or it is determined by converting the input interface index value into binary form.

Scope information is provided in the format hostname%scopeinformation, where the scope information can be the interface name or an interface index. The combined hostname%scopeinformation cannot exceed 255 characters in length; if the information is longer, the request fails.

Rules: When getaddrinfo processes scope information the following rules apply:

Scope information can be present only in the following cases:
- The host name portion of the input is not null (for example, input that is not in the form %scopeinformation)
- If a numeric form of host name is specified, the numeric form must represent an IPv6 address
If scope information is specified as an interface name, the interface name must resolve to a zone index using the if_nametoindex() function.
If scope information is specified as an interface index, the index must be valid for this system.

If any of these verification steps fail, the getaddrinfo request fails.

Zone indexes apply only to link-local IPv6 addresses in z/OS® Communications Server. If the input host name specified by the application does not resolve to a link-local IPv6 address, any scope information provided as part of the host name is ignored.

See Support for scope information for more general information about scope information in the z/OS Communications Server environment.