freeaddrinfo(), getaddrinfo() -- get address information

SYNOPSIS

#include <sys/socket.h>

#include <netdb.h>

void freeaddrinfo(struct addrinfo *ai);

int getaddrinfo(const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res);

Calling freedaddrinfo() frees the linked list of addrinfo structures pointed to by ai. In truth. ai points to the first structure in the list while the ai_next field of that structure points to the next structure in the list. As long as ai_next is not null, each structure pointed is freed as is any additional storage associated with these structures. Normally, the linked list used by this function has been returned by the getaddrinfo()

The getaddrinfo() function takes a host name (or other service location name), service name, or some combination of the two and determines a set of socket addresses and supplemental information that you can use to create a socket for addressing the specified service. Many implementations, like the NuTCRACKER Platform, use the Domain Name System (DNS) to make this determination.

The nodename parameter points to the service location name or address, while the servname parameter points to the service name or address. At least one of these must be specified; the other can be a null pointer.

For a non-null nodename, valid values to identify the service location include host names (when the associated address family is AF_INET, AF_INET6, or AF_UNSPEC), addresses in Internet standard dot notation (for address families AF_INET and AF_UNSPEC), and addresses in standard IPv6 format (for address families AF_INET6 and AF_UNSPEC), Internet standard dot notation is described on the inet_addr() reference page. The IPv6 format is described on the inet_ntop() reference page. When no address family is associated, getaddrinfo() tries to resolve the name in all supported families and returns all appropriate results.

A null nodename indicates the service location is local to the caller.

For a non-null service, valid values to identify the requested service can either be a descriptive name or a decimal port number (when the associated address family is AF_INET,` AF_INET6 or AF_UNSPEC),

A null servname indicates that getaddrinfo() is to return network-level address for the specified nodename.

The hints parameter points to an addrinfo structure that defines the limits of what getaddrinfo() is to return. Only the following members of this structure have any real meaning; all other should be set to 0 or to a null pointer:

ai_flags

Contains the bitwise-inclusive OR of one or more of the following flags:

AI_PASSIVE

When set, this flag specifies that the returned addresses are suitable for use when binding a socket to accept incoming connections for the specified service. The IP address portion of the returned address structure is set to INADDR_ANY or IN6ADDR_ANY_INIT for IPv4 or IPv6 addresses, respectively.

When not set, the returned addresses are suitable for use with the connect() function (for a connection-mode protocol) or with connect(), send(), or sendmsg() (for a connectionless protocol). The IP address portion of the socket address structure is set to the loopback address.

This flag is ignored when nodename is not null.

AI_CANONNAME

When set, getaddrinfo() tries to determine the canonical name for nodename (for example, nodename may be a alias or a shorthand notation). However, it is important to note that a numeric host address is not a name and as such, does not have a canonical name.

This flag is ignored when nodename is null.

AI_NUMERICHOST

When set, nodename is interpreted as a numeric host address and if it is not a valid numeric address, the error code EAI_NONAME is returned. No name resolution service (for example, DNS) is called.

This flag is ignored when nodename is null.

AI_NUMERICSERV

When this flag is set, nodename is interpreted as a numeric port and if it is not a valid numeric port, the error code EAI_NONAME is returned. No name resolution service (for example, NIS+) is called.

This flag is ignored when nodename is null.

AI_V4MAPPED

When this flag is set and the ai_family member is set to AF_INET6, getaddrinfo() returns IPv4-mapped IPv6 addresses when it cannot find any matching IPv6 addresses. The ai_addrlen member of such addresses is set to 16.

This flag is ignored when ai_family is not AF_INET6.

AI_ALL

When this flag is set and AI_V4MAPPED is also set, getaddrinfo() returns all matching IPv6 and IPv4 addresses.

This flag is ignored when AI_V4MAPPED is not set.

AI_ADDRCONFIG

When set, getaddrinfo() only returns IPv4 addresses when the local system has an IPv4 address configured. Similarly, it only returns IPv6 address when an IPv6 address is configured.

ai_family

Limits the returned addresses to those of the specified address family. A value of AF_UNSPEC means addresses from all families that can be used nodename and servname are to be returned.

ai_socktype

Limits the returned addresses to those with the specified socket type (as defined on the socket() reference page. A value of 0 means addresses with any socket type are to be returned.

ai_protocol

Limits the returned addresses to those with the specified protocol. A value of 0 means addresses with any protocol are to be returned.

When hints is a null pointer, getaddrinfo() returns all addresses.

PARAMETERS

ai: Points to a linked list of address structures that are to be freed by freeaddrinfo().
hints: Points to an address structure that determines which addresses are to be returned byt getaddrinfo().
nodename: Points to the service location name or address.
res: Points to the location where getaddrinfo() stores a pointer to a linked list of address structures containing the socket addresses returned by that function.
servname: Points to the service name or address.

RETURN VALUES

On success, getaddrinfo() and freeaddrinfo() return 0.

In addition, getaddrinfo() sets the location to which the res parameter points to a linked list of one or more addrinfo structures containing a socket address and the information to create the corresponding socket. These are the addresses returned by this function. The following members of the addrinfo structures are set as described:

ai_next: Points to the next structure in the list. For the last structure in the list, this is a null pointer.
ai_addr: Is a socket address suitable for use with the connect() function or, if the AI_PASSIVE flag set, the bind() function.
ai_addrlen: Is the length of the socket address in ai_addr. Again, this value is for use with connect() or bind().
ai_family: Specifies the address family for the socket address. This can be used with the socket() function.
ai_socktype: Specifies the socket type for the socket address. This can be used with the socket() function.
ai_protocol: Specifies the protocol for the socket address. This can be used with the socket() function.
ai_canonname: When the AI_CANONNAME flag is set, this member of the first returned addrinfo structure points to the canonical name corresponding to nodename. When a canonical name is not available, nodename is used as the canonical name.

All additional fields in the returned addrinfo structures are set to zero.

When freeaddrinfo() or getaddrinfo() does not complete successfully, they return one of the following non-zero error codes:

EAI_AGAIN: The specified name cannot be currently resolved. Further attempts might succeed.
EAI_BADFLAGS: The flags parameter is set to an invalid value.
EAI_FAIL: A fatal error (with no recovery possibility) occurred when attempting to resolve a name.
EAI_FAMILY: An unrecognized address family was specified.
EAI_MEMORY: A memory allocation failure occurred while attempting to set aside space for a return value,
EAI_NONAME: The supplied parameters do not result in a resolved name. At least one of the nodename or servname parameters must be supplied.
EAI_SERVICE: The specified socket type does not support the service given.
EAI_SOCKTYPE: An unrecognized socket type was specified.
EAI_SYSTEM: A system error occurred; the errno variable has been set to indicate that error.
EAI_OVERFLOW: The buffer for a parameter overflowed.

freeaddrinfo(), getaddrinfo()
get address information

Function

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO

freeaddrinfo(), getaddrinfo() get address information

Function

freeaddrinfo(), getaddrinfo()
get address information