FREEADDRINFO(3XNET) X/Open Networking Services Library Functions


NAME


freeaddrinfo, getaddrinfo - get address information

SYNOPSIS


cc [ flag ... ] file ... -lxnet [ library ... ]
#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 frees one or more addrinfo structures
returned by getaddrinfo(), along with any additional storage associated
with those structures. If the ai_next member of the structure is not
null, the entire list of structures is freed. The freeaddrinfo() function
supports the freeing of arbitrary sublists of an addrinfo list originally
returned by getaddrinfo().


The getaddrinfo() function translates the name of a service location (for
example, a host name) and/or a service name and returns a set of socket
addresses and associated information to be used in creating a socket with
which to address the specified service.


The nodename and servname arguments are either null pointers or pointers
to null-terminated strings. One or both of these two arguments are
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 attempts to
resolve the name in all supported families and, in absence of errors, one
or more results are 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(3XNET) are
valid.


If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
text forms described in inet_ntop(3XNET) 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 returns network-level addresses for the
specified nodename. If servname is not null, it is a null-terminated
character string identifying the requested service. This string 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 can 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 is set to 0 or a null
pointer. A value of AF_UNSPEC for ai_family means that the caller accepts
any address family. A value of 0 for ai_socktype means that the caller
accepts any socket type. A value of 0 for ai_protocol means that the
caller accepts any protocol. If hints is a null pointer, the behavior is
as if it referred to a structure containing the value 0 for the ai_flags,
ai_socktype, and ai_protocol members, and AF_UNSPEC for the ai_family
member.


The ai_flags member to which the hints parameter points is set to 0 or be
the bitwise-inclusive OR of one or more of the values AI_PASSIVE,
AI_CANONNAME, AI_NUMERICHOST, and AI_NUMERICSERV.


If the AI_PASSIVE flag is specified, the returned address information is
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 is 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 is suitable for a call to connect(3XNET) (for a connection-
mode protocol) or for a call to connect(), sendto(3XNET), or
sendmsg(3XNET) (for a connectionless protocol). In this case, if the
nodename argument is null, then the IP address portion of the socket
address structure is set to the loopback address.


If the AI_CANONNAME flag is specified and the nodename argument is not
null, the function attempts to determine the canonical name corresponding
to nodename (for example, if nodename is an alias or shorthand notation
for a complete name).


If the AI_NUMERICHOST flag is specified, then 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 (for
example, the DNS) from being invoked.


If the AI_NUMERICSERV flag is specified, then 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 from
being invoked.


If the AI_V4MAPPED flag is specified along with an ai_family of AF_INET6,
then getaddrinfo() returns IPv4-mapped IPv6 addresses on finding no
matching IPv6 addresses (ai_addrlen is 16). The AI_V4MAPPED flag is
ignored unless ai_family equals AF_INET6. If the AI_ALL flag is used
with the AI_V4MAPPED flag, then getaddrinfo() returns all matching IPv6
and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED flag is
ignored.


The ai_socktype member to which argument hints points specifies the
socket type for the service, as defined in socket(3XNET). If a specific
socket type is not given (for example, a value of 0) and the service name
could be interpreted as valid with multiple supported socket types, the
implementation attempts to resolve the service name for all supported
socket types and, in the absence of errors, all possible results are
returned. A non-zero socket type value limits the returned information to
values with the specified socket type.


If the ai_family member to which hints points has the value AF_UNSPEC,
addresses are returned for use with any address family that can be used
with the specified nodename and/or servname. Otherwise, addresses are
returned for use only with the specified address family. If ai_family is
not AF_UNSPEC and ai_protocol is not 0, then addresses are returned for
use only with the specified address family and protocol; the value of
ai_protocol is interpreted as in a call to the socket() function with the
corresponding values of ai_family and ai_protocol.

RETURN VALUES


A 0 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
refers to a linked list of addrinfo structures, each of which specifies a
socket address and information for use in creating a socket with which to
use that socket address. The list includes at least one addrinfo
structure. The ai_next member 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 includes 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(3XNET) function. The ai_family , ai_socktype, and ai_protocol
members are usable as the arguments to the socket() function to create a
socket suitable for use with the returned address. The ai_addr and
ai_addrlen members 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 member of the first returned addrinfo structure points to a
null-terminated string containing the canonical name corresponding to the
input nodename. If the canonical name is not available, then ai_canonname
refers to the nodename argument or a string with the same contents. The
contents of the ai_flags member of the returned structures are undefined.


All members in socket address structures returned by getaddrinfo() that
are not filled in through an explicit argument (for example,
sin6_flowinfo) are set to 0, making it easier to compare socket address
structures.

ERRORS


The getaddrinfo() function will fail if:

EAI_AGAIN
The name could not be resolved at this time. Future
attempts might succeed.


EAI_BADFLAGS
The ai_flags member of the addrinfo structure 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
he name does not resolve for the supplied parameters.
Neither nodename nor servname were supplied. At least one
of these must 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.


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.

ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO


connect(3XNET), gai_strerror(3XNET), gethostbyname(3XNET),
getnameinfo(3XNET), getservbyname(3XNET), inet_addr(3XNET),
inet_ntop(3XNET), socket(3XNET), attributes(5), standards(5)


February 25, 2017 FREEADDRINFO(3XNET)