getaddrinfo(3) Library Functions Manual getaddrinfo(3)
NAME
getaddrinfo - Get address information for a network node and service
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <netdb.h>
int getaddrinfo( const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res);
STANDARDS
The getaddrinfo function supports POSIX.1g Draft 6.6.
Refer to the standards(5) reference page for more information about industry standards and associated tags.
PARAMETERS
Points to a network node name, alias, or numeric host address (for example, a IPv4 dotted-decimal address or an IPv6 hexadecimal address).
This is a null-terminated string or a NULL pointer. A NULL pointer means that the service location is local to the caller. You must spec-
ify a null-terminated string for the nodename or servname parameter, or both. Points to a network service name or port number. This is a
null-terminated string or a NULL pointer. A NULL pointer returns network-level addresses for the specified nodename. You must specify a
null-terminated string for the nodename or servname parameter, or both. Points to an addrinfo structure that contains information that
directs the function's operation. This information can provide options or limit the returned information to a specific socket type,
address family or protocol. The netdb.h header file defines the addrinfo structure. This is an optional parameter. Points to a linked
list of one or more addrinfo structures.
DESCRIPTION
The getaddrinfo() routine can perform the following: Takes the service location (node name) and returns all addresses that are supported
for this name and specified parameters. Takes the service name and returns all ports that are supported for this service and specified
parameters. Allows the user to manipulate values returned by the routine.
The information is returned as a pointer to a linked list of one or more structures of type addrinfo. Its members specify data obtained
from either the local /etc/ipnodes file, local /etc/hosts file, or one of the files distributed by DNS/BIND or NIS. To determine which
file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file. The netdb.h header file defines the
addrinfo structure.
If using DNS/BIND, the information is obtained from a name server specified in the /etc/resolv.conf file.
Clients typically specify both the nodename and servname parameters. Servers typically specify only the servname parameter.
If you specify the hints parameter, all addrinfo structure members other than the following members must be zero or a NULL pointer: Con-
trols the processing behavior of getaddrinfo. See the "ai_flags Member Values" section for a complete description of the flags. Specifies
to return addresses for use with a specific protocol family. If you specify a value of AF_UNSPEC, the routine returns addresses for all
protocol families that can be used with nodename or servname.
If the value is not AF_UNSPEC and ai_protocol is not zero, the routine returns addresses for use only with the specified protocol
family and protocol.
If the application handles only IPv4, set this member of the hints structure to PF_INET. Specifies a socket type for the given ser-
vice. If you specify a value of 0, you will accept any socket type. This resolves the service name for all socket types and
returns all successful results. Specifies a network protocol. If you specify a value of 0, you will accept any protocol. If the
application handles only TCP, set this member to IPPROTO_TCP.
If the hints parameter is a NULL pointer, this is identical to passing an addrinfo structure that has been initialized to zero and the
ai_family member set to AF_UNSPEC.
ai_flags Member Values
The flags and their meanings, if set, that are defined for the ai_flags member of the addrinfo structure are as follows: [Tru64 UNIX] If
the ai_family value is AF_INET, this is ignored.
If the ai_family value is AF_INET6, searches for AAAA records. If found, returns IPv6 records. If no AAAA records are found,
searches for A records. If found, returns IPv4-mapped IPv6 addresses. If no records are found, returns a NULL pointer. [Tru64
UNIX] If the ai_family value is AF_INET, this is ignored.
If the ai_family value is AF_INET6, searches for AAAA records. If found, returns IPv6 addresses. Then, searches for A records. If
found, returns IPv4-mapped IPv6 addresses. If no records are found, returns a NULL pointer. If the nodename parameter is not a
NULL pointer, the function searches for the specified node's canonical name.
Upon successful completion, the ai_canonname member of the first addrinfo structure in the linked list points to a null-terminated
string containing the canonical name of the specified nodename.
If the canonical name is not available or if AI_CANONNAME is not set, the ai_canonname member refers to the nodename parameter or a
string with the same contents. The ai_flags field contents are undefined. Converts a numeric host address string to an address.
The nodename parameter must be a numeric host address string. No host name resolution is performed. Converts a numeric service
port string to a port number. The servname parameter must be a numeric port string. No service name resolution is performed.
Returns a socket address structure that your application can use in a call to bind(). If the nodename parameter is a NULL pointer,
the IP address portion of the socket address structure is set to INADDR_ANY (for an IPv4 address) or IN6ADDR_ANY_INIT (for an IPv6
address).
If not set, returns a socket address structure that your application can use to call connect() (for a connection-oriented protocol)
or either connect(), sendto(), or sendmsg() (for a connectionless protocol). If the nodename parameter is a NULL pointer, the IP
address portion of the socket address structure is set to the loopback address.
You can use the flags in any combination to achieve finer control of the translation process. The AI_ADDRCONFIG flag is typically used in
combination with other flags to modify the search based on the source address or addresses configured on the system. The following list
describes how the AI_ADDRCONFIG flags works by itself. If an IPv4 source address is configured, searches for A records.
If an IPv6 source address is configured, searches for AAAA records.
Most applications will want to use the combination of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their search. To simplify this for
the programmer, the AI_DEFAULT symbol, which is a logical OR of AI_ADDRCONFIG and AI_V4MAPPED, is defined. The following list describes how
AI_DEFAULT directs the search.
[Tru64 UNIX] If the ai_family value is AF_INET, searches for A records only if an IPv4 source address is configured on the system. If
found, returns IPv4 addresses. If no A records are found, returns a NULL pointer.
If the ai_family value is AF_INET6, searches for AAAA records only if an IPv6 source address is configured on the system. If found,
returns IPv6 addresses. If no AAAA records are found and if an IPv4 address is configured on the system, searches for A records.
If found, returns IPv4-mapped IPv6 addresses. If no records are found, returns a NULL pointer.
These flags are defined in <netdb.h>.
addrinfo Structure Processing
Upon successful return, getaddrinfo returns a pointer to a linked list of one or more addrinfo structures. The application can process
each addrinfo structure in the list by following the ai_next pointer, until a NULL pointer is encountered. In each returned addrinfo
structure, the ai_family, ai_socktype, and ai_protocol members are the corresponding arguments for a call to the socket() function. The
ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.
RETURN VALUES
Upon successful completion, the getaddrinfo() function returns 0 (zero). Upon failure, it returns a non-zero value.
ERRORS
If the getaddrinfo() function fails, it returns one of the following values. Use the gai_strerror(3) command to print error messages based
on these return codes: The nodename parameter could not be resolved this time. Try the request again. The value of the flags parameter is
invalid. A non-recoverable error occurred. The address family (ai_family in the hints structure) was not recognized, or the address
length was invalid. A memory allocation failure occurred. The node name cannot be resolved with the supplied parameters.
You did not pass either the nodename or servname parameter. You must pass at least one. The service passed is unknown for the spe-
cific socket type. The intended socket is unknown. A system error occurred; errno is set to the error value.
FILES
The Internet network hostname database. Each record in the file occupies a single line and has three fields consisting of the host address,
official hostname, and aliases. The resolver configuration file. The database service selection configuration file.
RELATED INFORMATION
Functions: connect(3), freeaddrinfo(3), gai_strerror(3), gethostbyname(3), getnameinfo(3), getservbyname(3), socket(3).
Files: hostname(5), resolv.conf(4), svc.conf(4).
Networks: bind_intro(7), nis_intro(7).
Standards: standards(5). delim off
getaddrinfo(3)