getaddrinfo Subroutine

Purpose

Protocol-independent hostname-to-address translation.

Library

Library (libc.a)

Syntax

#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo (hostname, servname, hints, res)
const char *hostname;
const char *servname;
const struct addrinfo *hints;
struct addrinfo **res;

Description

The hostname and servname parameters describe the hostname and/or service name to be referenced. Zero or one of these arguments may be NULL. A non-NULL hostname may be either a hostname or a numeric host address string (a dotted-decimal for IPv4 or hex for IPv6). A non-NULL servname may be either a service name or a decimal port number.

The hints parameter specifies hints concerning the desired return information. The hostname and servname parameters are pointers to null-terminated strings or NULL. One or both of these arguments must be a non-NULL pointer. In a normal client scenario, both the hostname and servname parameters are specified. In the normal server scenario, only the servname parameter is specified. A non-NULL hostname string can be either a host name or a numeric host address string (for example, a dotted-decimal IPv4 address or an IPv6 hex address). A non-NULL servname string can be either a service name or a decimal port number.

The caller can optionally pass an addrinfo structure, pointed to by the hints parameter, to provide hints concerning the type of socket that the caller supports. In this hints structure, all members other than ai_flags, ai_eflags ai_family, ai_socktype, and ai_protocol must be zero or a NULL pointer. A value of PF_UNSPEC for ai_family means the caller will accept any protocol family. A value of zero for ai_socktype means the caller accepts any socket type. A value of zero for ai_protocol means the caller accepts any protocol. For example, if the caller handles only TCP and not UDP, the ai_socktype member of the hints structure should be set to SOCK_STREAM when the getaddrinfo subroutine is called. If the caller handles only IPv4 and not IPv6, the ai_family member of the hints structure should be set to PF_INET when getaddrinfo is called. If the hints parameter in getaddrinfo is a NULL pointer, it is the same as if the caller fills in an addrinfo structure initialized to zero with ai_family set to PF_UNSPEC.

Upon successful return, a pointer to a linked list of one or more addrinfo structures is returned through the res parameter. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a NULL pointer is encountered. In each returned addrinfo structure the three members ai_family, ai_socktype, and ai_protocol are the corresponding arguments for a call to the socket subroutine. In each addrinfo structure, the ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.

If the AI_PASSIVE bit is set in the ai_flags member of the hints structure, the caller plans to use the returned socket address structure in a call to the bind subroutine. If the hostname parameter is a NULL pointer, the IP address portion of the socket address structure will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address.

If the AI_PASSIVE bit is not set in the ai_flags member of the hints structure, the returned socket address structure is ready for a call to the connect subroutine (for a connection-oriented protocol) or the connect, sendto, or sendmsg subroutine (for a connectionless protocol). If the hostname parameter is a NULL pointer, the IP address portion of the socket address structure is set to the loopback address.

If the AI_CANONNAME bit is set in the ai_flags member of the hints structure, upon successful return the ai_canonname member of the first addrinfo structure in the linked list points to a NULL-terminated string containing the canonical name of the specified hostname.

If the AI_NUMERICHOST flag is specified, a non-NULL nodename string supplied is a numeric host address string. Otherwise, an (EAI_NONAME) error is returned. This flag prevents any type of name resolution service (such as, DNS) from being invoked.

If the AI_NUMERICSERV flag is specified, a non-NULL servname string supplied is a numeric port string. Otherwise, an (EAI_NONAME) error is returned. This flag prevents any type of name resolution service (such as, NIS+) from being invoked.

If the AI_V4MAPPED flag is specified along with an ai_family value of AF_INET6, the getaddrinfo subroutine returns IPv4-mapped IPv6 addresses when no matching IPv6 addresses (ai_addrlen is 16) are found. For example, when using DNS, if no AAAA or A6 records are found, a query is made for A records. Any found are returned as IPv4-mapped IPv6 addresses. The AI_V4MAPPED flag is ignored unless ai_family equals AF_INET6.

If the AI_EXTFLAGS is specified in the ai_flags member of the hints structure and ai_eflags is specified as a non zero value, the address selection algorithm is affected. The address selection algorithm orders the list of returned addrinfo structures using a set of ordered rules (RFC 3484) taking into account the address contained in the ai_addr member of each addrinfo structure and the source addresses from which this address can be reached. The ai_eflags expresses preferences meaning that the rules described below will be applied if a higher rule has not ordered the set of addresses before.

The ai_eflags can be set to a combination of the following flags:

For instance, the IPV6_PREFER_SRC_TMP ai_eflags means that the address selection algorithm will order the returned addrinfo structures with addresses reachable from a temporary address before the ones with addresses reachable from a public address whenever possible. Setting contradictory flags (e.g. IPV6_PREFER_SRC_TMP and IPV6_PREFER_SRC_PUBLIC) at the same time results in the error EINVAL.

If the AI_ADDRCONFIG flag is specified, a query for AAAA or A6 records should occur only if the node has at least one IPv6 source address configured. A query for A records should occur only if the node has at least one IPv4 source address configured. The loopback address is not considered valid as a configured source address.

All of the information returned by the getaddrinfo subroutine 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, freeaddrinfo subroutine is called.

The addrinfo structure is defined as:

struct addrinfo {
  int               ai_flags;          /* AI_PASSIVE, AI_CANONNAME */
  int               ai_family;         /* PF_xxx */
  int               ai_socktype;       /* SOCK_xxx */
  int               ai_protocol;       /* 0 or IP=PROTO_xxx for IPv4 and IPv6 */
  size_t            ai_addrlen;        /* length of ai_addr */
  char              *ai_canonname;     /* canoncial name for hostname */
  struct sockaddr   *ai_addr;          /* binary address */
  struct addrinfo   *ai_next;          /* next structure in linked list */
  int ai_eflags; /* Extended flags for special usage */
}

Return Values

If the query is successful, a pointer to a linked list of one or more addrinfo structures is returned via the res parameter. A zero return value indicates success. If the query fails, a non-zero error code is returned.

Error Codes

The following names are the non-zero error codes. See netdb.h for further definition.