NAME
freeaddrinfo, getaddrinfo - get address information
SYNOPSIS
#include <sys/socket.h>
#include <netdb.h>
void freeaddrinfo(struct addrinfo *ai);
int getaddrinfo(const char *restrict nodename,
const char *restrict servname,
const struct addrinfo *restrict hints,
struct addrinfo **restrict res);
DESCRIPTION
The freeaddrinfo() function shall free one or more addrinfo structures
returned by getaddrinfo(), along 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().
The 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.
Note: In many cases it is implemented by the Domain Name System, as
documented in RFC 1034, RFC 1035, and RFC 1886.
The freeaddrinfo() 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-null pointer.
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 family is AF_INET,
AF_INET6, or AF_UNSPEC, valid descriptive names include host names.
If the specified address family is AF_INET or AF_UNSPEC, address
strings using Internet standard dot notation as specified in
inet_addr() are valid.
If the specified address family is AF_INET6 or AF_UNSPEC, standard 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 is not 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_INET, AF_INET6, or 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 may direct the operation by providing options and by
limiting the returned information to a specific socket type, address
family, and/or protocol. In this hints structure every member other
than ai_flags, ai_family, ai_socktype, and ai_protocol shall be set to
zero or a null pointer. A value of AF_UNSPEC for ai_family means that
the caller shall accept any address family. A value of zero for
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_flags,
ai_socktype, and ai_protocol fields, and AF_UNSPEC for the ai_family
field.
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, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
AI_ALL, and AI_ADDRCONFIG.
If the 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 IPv6 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
connect(), sendto(), or 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 null.
If the 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 name).
Note: Since different implementations use different conceptual models,
the terms ‘‘canonical name’’ and ‘‘alias’’ cannot be precisely
defined for the general case. However, Domain Name System
implementations are expected to interpret them as they are used
in RFC 1034.
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.
If the AI_NUMERICHOST flag is specified, then a non-null nodename
string supplied shall be a numeric host address string. Otherwise, an
[EAI_NONAME] error is returned. This flag shall prevent any type of
name resolution service (for example, the DNS) from being invoked.
If the AI_NUMERICSERV flag is specified, then a non-null servname
string supplied shall be a numeric port string. Otherwise, an
[EAI_NONAME] error shall be returned. This flag shall prevent any type
of name resolution service (for example, NIS+) from being invoked.
If the AI_V4MAPPED flag is specified along with an ai_family of
AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses on
finding no matching IPv6 addresses ( ai_addrlen shall be 16). The
AI_V4MAPPED flag shall be ignored unless ai_family equals AF_INET6. If
the AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo()
shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
without the AI_V4MAPPED flag is ignored.
If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
returned only if an IPv4 address is configured on the local system,
and IPv6 addresses shall be returned only if an IPv6 address is
configured on the local system.
The 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.
If the 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 AF_UNSPEC and ai_protocol is not zero, then addresses
are 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 ai_family and
ai_protocol.
RETURN VALUE
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 ERRORS section.
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_family, ai_socktype, and 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_addr and ai_addrlen are
usable as the arguments to the connect() or bind() functions with such
a socket, according to the AI_PASSIVE flag.
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.
Note: This makes it easier to compare socket address structures.
ERRORS
The getaddrinfo() function shall fail and return the corresponding
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 errno.
EAI_OVERFLOW
An argument buffer overflowed.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
If the caller handles only TCP and not UDP, for example, then the
ai_protocol member of the hints structure should be set to IPPROTO_TCP
when getaddrinfo() is called.
If the caller handles only IPv4 and not IPv6, then the ai_family member
of the hints structure should be set to AF_INET when getaddrinfo() is
called.
The term ‘‘canonical name’’ is misleading; it is taken from the Domain
Name System (RFC 2181). It should be noted that the canonical name is a
result of alias processing, and not necessarily a unique attribute of a
host, address, or set of addresses. See RFC 2181 for more discussion of
this in the Domain Name System context.
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
connect() , gai_strerror() , gethostbyaddr() , getnameinfo() ,
getservbyname() , socket() , the Base Definitions volume of
IEEE Std 1003.1-2001, <netdb.h>, <sys/socket.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .