Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

getaddrinfo(3) OSS Library Calls Reference Manual
AI_V4MAPPED
Requests the return of all IPv4-mapped IPv6 addresses when the address family
is AF_INET6 and there are no matching IPv6 addresses. This flag is ignored if
the address family is AF_INET.
A TCP or UDP client typically specifies nonNULL values for both the hostname and service
parameters. A TCP client loops through all the returned socket address structures, calling the
socket( ) and connect( ) functions for each address until a connection succeeds. A UDP client
calls connect( ) or the sendto( ) function.
A TCP or UDP server typically specifies a nonNULL value for service but not hostname. It also
specifies the AI_PASSIVE flag in the hints struct. The returned socket address structs should
contain the IP address INADDR_ANY or IN6ADDR_ANY_INIT. A TCP server then calls the
socket( ), bind( ), and listen( ) functions. A UDP server calls socket( ), bind( ), and the
recvfrom( ) function.
If the client or server handles only one type of socket, set hints.ai_socktype to
SOCK_STREAM or SOCK_DGRAM to avoid having multiple addrinfo structs returned.
NOTES
This function, along with getipnodebyname( ), are protocol-independent replacements for
gethostbyname( ). getaddrinfo( ) provides functionality beyond what getipnodebyname( ) pro-
vides because getaddrinfo( ) handles both the host name and the service.
Appropriate use of this function can eliminate calls to the getservbyname( ) function and pro-
vide protocol independence.
RETURN VALUES
Upon sucessful completion, this function returns 0 (zero) and result points to a new list of
address information structures. Otherwise, getaddrinfo( ) returns one of the following error
codes:
EAI_AGAIN The name could not be resolved this time. Future attempts may succeed.
EAI_BADFLAGS
The flags parameter has an invalid value.
EAI_FAIL A non-recoverable error occurred.
EAI_FAMILY Address family was not recognized or address length was invalid.
EAI_MEMORY
A memory allocation failure occurred.
EAI_NONAME
Name does not resolve to supplied parameters.
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 (error code found in errno)
3−12 Hewlett-Packard Company 527187-017