The getnameinfo call is a replacement for the existing gethostbyaddr and getservbyport APIs. The getnameinfo call takes an input IP address, an input port number, or both, and returns (when resolution is successful) the hostname or the service location. These parameters are passed in a sockaddr structure that also contains the address family.

For input link-local IPv6 addresses, the zone index value in the sockaddr structure is also used as an input by getnameinfo processing. The zone index value in this instance is returned as scope information that is appended to the output host name, using the format hostname%scopeinformation. The form of the scope information can be the numeric form of the zone index value or the interface name associated with the zone index value, which is identified using the if_indextoname() function (see Interface identification for details). The format of the scope information returned to the application as part of the hostname is determined by the flag, NI_NUMERICSCOPE, on the getnameinfo() call. The total length of the combined host name and scope information must be able to fit within the buffer passed by the application (up to a maximum buffer size of 255 characters in length), or the value is truncated to fit within the buffer.

In addition to IP address or port number, one of which must be present on a valid getnameinfo invocation, the application can specify more input to the Resolver on the getnameinfo invocation. This input is optional. The input settings include the following settings (various input flag settings can be specified):

NI_NOFQDN

Specifies that only the host name portion of the fully qualified domain name (FQDN) is returned for local hosts.

NI_NUMERICHOST

Specifies that the numeric form of the host name, its IP address, is returned instead of its name. No resolution takes place for the specified input if the NI_NUMERICHOST flag is on.

NI_NUMERICSERV

Specifies that the numeric form of the service name, the port number, is returned instead of the service name. No resolution takes place for the specified input if the NI_NUMERICSERV flag is on.

NI_NAMEREQD

Specifies that an error is returned if the host name cannot be located. (If NI_NAMEREQD is not specified, the numeric form of the host name, the IP address, is returned).

NI_DGRAM

Specifies that the service is a datagram service (SOCK_DGRAM). The default behavior assumes that the service is a stream service.

NI_NUMERICSCOPE

Specifies that the numeric form of the scope information, its interface index, appended to the host name, is returned instead of the interface name. If the input IP address was not a link-local address, or if the application did not request that the host name be returned as output, scope information is not returned, and the setting of NI_NUMERICSCOPE is ignored. If NI_NUMERICSCOPE is not specified, the default is to return the interface name when scope information is appended to the host name.