NAME

getaddrinfo, freeaddrinfo - get address information¹

SYNOPSIS

#include <sys/socket.h>
#include <netdb.h>

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

void freeaddrinfo(struct addrinfo *ai);

DESCRIPTION

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 must be a non-null pointer.

The format of a valid name depends on the protocol family or families. If a specific family is not given and the name could be interpreted as valid within multiple supported families, the implementation will attempt to resolve the name in all supported families and, in absence of errors, one or more successful results will be 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 as specified in XSH specification. If the specified address family is AF_INET or AF_UNSPEC, address strings using Internet standard dot notation as specified on the inet_addr() man page are valid.

If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described on the inet_pton() man page 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 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 argument hints is not null, it refers to a structure containing input values that may 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 must be zero or a null pointer. A value of AF_UNSPEC for ai_family means that the caller will accept any protocol family. A value of zero for ai_socktype means that the caller will accept any socket type. A value of zero for ai_protocol means that the caller will accept any protocol. If hints is a null pointer, the behavior must be as if it referred to a structure containing the value zero for the ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC for the ai_family field.

Notes:

1. 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.

2. If the caller handles only IPv4 and not IPv6, then the ai_family member of the hints structure should be set to PF_INET when getaddrinfo() is called.

The ai_flags field to which hints parameter points must have the value zero or be the bitwise OR of one or more of the values AI_PASSIVE, AI_CANONNAME and AI_NUMERICHOST.

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

If the flag AI_CANONNAME 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 flag AI_NUMERICHOST is specified then a non-null nodename string must be a numeric host address string. Otherwise an error of [EAI_NONAME] is returned. This flag prevents any type of name resolution service (for example, the DNS) from being invoked.

If the flag AI_NUMERICSERV is specified then a non-null servname string must be a numeric port string. Otherwise an error [EAI_NONAME] is returned. This flag prevents any type of name resolution service (for example, NIS+) from being invoked.

The ai_socktype field to which argument hints points specifies the socket type for the service, as defined on the socket() man page. If a specific socket type is not given (for example, a value of zero) and the service name could be interpreted as valid with multiple supported socket types, the implementation will attempt to resolve the service name for all supported socket types and, in absense of errors, all possible successful results will be returned. A non-zero socket type value will limit the returned information to values with the specified socket type.

If the ai_family field to which hints points has the value AF_UNSPEC, addresses are returned for use with any protocol family that can be used with the specified nodename and/or servname. Otherwise, addresses are returned for use only with the specified protocol family. If ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses are returned for use only with the specified protocol 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.

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 field of the structure is not null, the entire list of structures is freed. The freeaddrinfo() function must support the freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo().

Functions getaddrinfo() and freeaddrinfo() must be thread-safe.

RETURN VALUE

A zero return value for getaddrinfo() indicates successful completion; a non-zero return value indicates failure.

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 must include at least one addrinfo structure. The ai_next field 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() function. The fields ai_family, ai_socktype, and ai_protocol are usable as the arguments to the socket() function to create a socket suitable for use with the returned address. The fields ai_addr and ai_addrlen 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 field 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 argument nodename or a string with the same contents. The contents of the ai_flags field of the returned structures is undefined.

All fields in socket address structures returned by getaddrinfo() that are not filled in through an explicit argument (for example, sin6_flowinfo and sin_zero) must be set to zero.

Note:

This makes it easier to compare socket address structures.

ERRORS

[EAI_AGAIN]

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

[EAI_BADFLAGS]

The flags parameter 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]

The name does not resolve for the supplied parameters.

Neither nodename nor servname were passed. At least one of these must be passed.

[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.

SEE ALSO

connect(), gethostbyname(), getipnodebyname(), getnameinfo(), getservbyname(), socket(). <netdb.h>, <sys/socket.h>.

CHANGE HISTORY

First released in Issue 5.2.

Footnotes

1.

Based on functions defined in IEEE P1003.1g/D6.6, Copyright 1997, IEEE. All rights reserved.