freeaddrinfo

freeaddrinfo(), getaddrinfo()

get address information 

Function


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);


DESCRIPTION

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.


CONFORMANCE

UNIX 03.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
connect(), gai_strerror(), gethostbyaddr(), getnameinfo(), getservbyname(), socket()

Miscellaneous:
sockets


PTC MKS Toolkit 10.2 Documentation Build 28.