getaddrinfo.3n (2010 09)

g
getaddrinfo(3N) getaddrinfo(3N)
address portion of the socket address will be set to
loopback address.
If the
AI_CANONNAME bit is set, then upon successful return,
getad-
drinfo() will return the ai_canonname member of the first
addrinfo
structure, which is a NULL terminated string containing the canonical name of
the specified host.
If an
AI_V4MAPPED flag is specified with an
ai_family value of AF_INET6,
getaddrinfo() returns IPv4-mapped IPv6 addresses when it does not find
any matching IPv6 addresses. getaddrinfo()
ignores an AI_V4MAPPED
flag if the ai_family is not equal to
AF_INET6.
If an
AI_ALL flag is used with an
AI_V4MAPPED flag, getaddrinfo()
returns all the matching IPv6 and IPv4 addresses.
getaddrinfo()
ignores
an
AI_ALL flag without an AI_V4MAPPED
flag.
If an
AI_ADDRCONFIG
flag is specified, then IPv4 addresses are returned only
if an IPv4 address is configured in the local system, and IPv6 addresses are
returned only if an IPv6 address is configured in the local system. In this case,
the loopback address is not considered as a valid configured address.
ai_family The protocol family the caller will accept. If this member is set to
PF_UNSPEC,
then the caller will accept any protocol family. If the caller handles only IPv4
stack and not IPv6 stack, then the
ai_family must be set to PF_INET
.
ai_protocol The protocol the caller supports. If ai_protocol is set to 0, then the caller
will accept any protocol.
ai_socktype The socket type the caller supports. If ai_socktype is set to 0, then the caller
will accept any socket type. However, if the caller handles only TCP and not
UDP, then the ai_socktype must be set to SOCK_STREAM.
ai_addrlen The length, in bytes, of the IPv4 or IPv6 address.
ai_canonname The canonical name of the host.
ai_addr The binary address of the host.
ai_next The next addrinfo structure in the linked list.
The above argument,
const struct addrinfo *hints, is optional. If the caller wants to provide
information such as the type of socket and protocol family that the caller supports, the caller can specify
them using the addrinfo structure. When this information is passed to getaddrinfo()
, all the
fields other than
ai_flags, ai_family, ai_socktype, and ai_protocol must be set to zero
or
a NULL pointer.
When
getaddrinfo() returns successfully,
**res holds a pointer to a linked list of one or more
addrinfo structures. The caller can process each addrinfo structure in this list by following the
ai_next pointer, until a NULL pointer is encountered. In each of the returned addrinfo structures,
the three members ai_family, ai_socktype, and ai_protocol are used as arguments to the
socket() function call. The ai_addr member points to a socket address structure whose length is
specified by the ai_addrlen member.
Destination Address Selection
getaddrinfo() supports the Destination Address Selection algorithm defined in RFC 3484. This
feature can be enabled by setting the ndd tunable, ip6_addr_sel_enable,to1. See ndd(1M) for
information on setting a network tunable parameter. Upon enabling the feature,
getaddrinfo() sorts
the linked list of addrinfo structures based on the Destination Address Selection rules defined in RFC
3484. This sorting process ensures that the best possible addresses are at the beginning of the list.
Return Value for getaddrinfo()
The return value from the
getaddrinfo() function is 0 upon success, or a nonzero error code.
The following are the nonzero error codes given by
getaddrinfo(). These are defined in <netdb.h>:
EAI_ADDRFAMILY Address family for hostname not supported.
EAI_AGAIN Temporary failure in name resolution.
EAI_BADFLAGS Invalid value for ai_flags.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010