void freeaddrinfo(struct addrinfo *ai);
int getaddrinfo(const char *restrict nodename,
const char *restrict _servname_,
const struct addrinfo *restrict hints,
struct addrinfo **restrict res);
IEEE Std 1003.1-2017
The purpose is to get address information. The
freeaddrinfo() function shall free one or more
addrinfo structures returned by
with any additional storage associated with those structures. If the
ai_next field of the structure is not
null, the entire
list of structures shall be freed. The
freeaddrinfo() function shall support the freeing of arbitrary sublists of an
addrinfo list originally returned by
getaddrinfo() function shall translate the name of a service location (for example, a host name) and/or a service
name and shall return a set of socket addresses and associated information to be used in creating a socket with which to address
the specified service.
In many cases it is implemented by the Domain Name System, as documented in
RFC 1035, and
getaddrinfo() functions shall be thread-safe.
The nodename and servname arguments are either
null pointers or pointers to
null-terminated strings. One or both
of these two arguments shall be supplied by the application as a non-
The format of a valid name depends on the address family or families. If a specific family is not given and the name could be interpreted as valid within multiple supported families, the implementation shall attempt to resolve the name in all supported families and, in absence of errors, one or more results shall be returned.
If the nodename argument is not
null, it can be a descriptive name or can be an address string. If the specified address
descriptive names include host names. If the specified address family is
AF_UNSPEC, address strings using Internet
standard dot notation as specified in
inet_addr are valid.
If the specified address family is
IPv6 text forms described in
inet_ntop are valid.
If nodename is not
null, the requested service location is named by nodename, otherwise, the requested service
location is local to the caller.
If servname is
null, the call shall return network-level addresses for the specified nodename. If servname
null, it is a
null-terminated character string identifying the requested service. This can be either a descriptive name or a
numeric representation suitable for use with the address family or families. If the specified address family is
AF_UNSPEC, the service can be specified as a
string specifying a decimal port number.
If the hints argument is not
null, it refers to a structure containing input values that directs the operation by
providing options and by limiting the returned information to a specific socket type, address family, and/or protocol, as described
below. The application shall ensure that each of the
members, as well as each of the non-standard additional members, if any, of this hints structure is initialized. If any of
these members has a value other than the value that would result from default initialization, the behavior is
implementation-defined. A value of
ai_family means that the caller shall accept any address family. A value of
ai_socktype means that the caller shall accept any socket type. A value of zero for
ai_protocol means that
the caller shall accept any protocol. If hints is a
null pointer, the behavior shall be as if it referred to a structure
containing the value zero for the
ai_protocol fields, and
AF_UNSPEC for the
ai_flags field to which the hints parameter points shall be set to zero or be the bitwise-inclusive OR of one
or more of the values
AI_PASSIVE flag is specified, the returned address information shall be suitable for use in binding a socket for
accepting incoming connections for the specified service. In this case, if the nodename argument is
null, then the IP
address portion of the socket address structure shall be set to
INADDR_ANY for an
IPv4 address or
IN6ADDR_ANY_INIT for an
address. If the
AI_PASSIVE flag is not specified, the returned address information shall be suitable for a call to
connect() (for a connection-mode protocol) or for a call to
sendmsg() (for a connectionless protocol). In this case, if the nodename argument is
null, then the IP address portion of the socket address structure shall be set to the loopback address. The
AI_PASSIVE flag shall
be ignored if the nodename argument is not
AI_CANONNAME flag is specified and the nodename argument is not
null, the function shall attempt to determine the
canonical name corresponding to nodename (for example, if nodename is an alias or shorthand notation for a complete
- Since different implementations use different conceptual models, the terms
aliascannot be precisely defined for the general case. However, Domain Name System implementations are expected to interpret them as they are used in
A numeric host address string is not a
name, and thus does not have a
canonical name form; no address to host name translation is performed. See below for handling of the case where a canonical name cannot be obtained.
AI_NUMERICHOST flag is specified, then a non-
null nodename string supplied shall be a numeric host address string.
EAI_NONAME error is returned. This flag shall prevent any type of name resolution service (for example, the
from being invoked.
AI_NUMERICSERV flag is specified, then a non-
null servname string supplied shall be a numeric port string.
EAI_NONAME error shall be returned. This flag shall prevent any type of name resolution service (for example,
from being invoked.
By default, with an
getaddrinfo() shall return only
IPv6 addresses. If the
AI_V4MAPPED flag is
specified along with an
getaddrinfo() shall return
IPv6 addresses on finding
IPv6 addresses. The
AI_V4MAPPED flag shall be ignored unless
AF_INET6. If the
AI_ALL flag is
used with the
AI_V4MAPPED flag, then
getaddrinfo() shall return all matching
IPv4 addresses. The
AI_V4MAPPED flag shall be ignored.
AI_ADDRCONFIG flag is specified,
IPv4 addresses shall be returned only if an
IPv4 address is configured on the local
IPv6 addresses shall be returned only if an
IPv6 address is configured on the local system.
ai_socktype field to which argument hints points specifies the socket type for the service, as defined in socket. If a specific socket type is not given (for example, a value of zero) and the
service name could be interpreted as valid with multiple supported socket types, the implementation shall attempt to resolve the
service name for all supported socket types and, in the absence of errors, all possible results shall be returned. A non-zero
socket type value shall limit the returned information to values with the specified socket type.
ai_family field to which hints points has the value
AF_UNSPEC, addresses shall be returned for use with any
address family that can be used with the specified nodename and/or servname. Otherwise, addresses shall be returned
for use only with the specified address family. If
ai_family is not
ai_protocol is not zero, then
addresses shall be returned for use only with the specified address family and protocol; the value of
ai_protocol shall be
interpreted as in a call to the
socket() function with the corresponding values of
A zero return value for
getaddrinfo() indicates successful completion, a non-zero return value indicates failure. The possible values for the failures are listed in the
Upon successful return of
getaddrinfo(), the location to which res points shall refer to a linked list of
addrinfo structures, each of which shall specify a socket address and information for use in creating a socket with which to use that socket address. The list shall include at least one
addrinfo structure. The
ai_next field of each structure contains a pointer to the next structure on the list, or a
null pointer if it is the last structure on the list. Each structure on the list shall include values for use with a call to the
socket() function, and a socket address for use with the
connect() function or, if the
AI_PASSIVE flag was specified, for use with the
bind() function. The fields
ai_protocol shall be usable as the arguments to the
socket() function to create a socket suitable for use with the returned address. The fields
ai_addrlen are usable as the arguments to the
bind() functions with such a socket, according to the
If nodename is not
null, and if requested by the
AI_CANONNAME flag, the
ai_canonname field of the first returned
addrinfo structure shall point to a
null-terminated string containing the canonical name corresponding to the input nodename, if the canonical name is not available, then ai_canonname shall refer to the nodename argument or a string with the same contents. The contents of the ai_flags field of the returned structures are undefined.
All fields in socket address structures returned by
getaddrinfo() that are not filled in through an explicit argument (for example,
sin6_flowinfo) shall be set to zero.
This makes it easier to compare socket address structures.
getaddrinfo() function shall fail and return the corresponding error value if:
EAI_AGAIN- The name could not be resolved at this time. Future attempts may succeed.
EAI_BADFLAGS- The flags parameter had an invalid value.
EAI_FAIL- A non-recoverable error occurred when attempting to resolve the name.
EAI_FAMILY- The address family was not recognized.
EAI_MEMORY- There was a memory allocation failure when trying to allocate storage for the return value.
EAI_NONAME- The name does not resolve for the supplied parameters.
Neither nodename nor servname were supplied. At least one of these shall be supplied.
EAI_SERVICE- The service passed was not recognized for the specified socket type.
EAI_SOCKTYPE- The intended socket type was not recognized.
EAI_SYSTEM- A system error occurred, the error code can be found in