getaddrinfo(3)getaddrinfo(3)NAMEgetaddrinfo - Get address information for a network node and service
SYNOPSIS
#include <netdb.h>
int getaddrinfo(
const char *nodename,
const char *servname,
const struct addrinfo *hints,
struct addrinfo **res );
LIBRARY
Standard C Library (libc)
STANDARDS
The getaddrinfo function is compliant with POSIX.1g Draft 6.6. How‐
ever, you do not need to compile your application for POSIX in order to
access the function.
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,
in either global or scoped address format). This is a null-terminated
string or a NULL pointer. A NULL pointer means that the service loca‐
tion is local to the caller. You must specify 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 struc‐
ture 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. If you do not
want to direct the function's operation, you can specify a NULL
pointer. The netdb.h header file defines the addrinfo structure. See
the DESCRIPTION section for information on hints parameter processing.
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 spec‐
ified 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 Mem‐
ber Values" section for a complete description of the options. Speci‐
fies 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 proto‐
col 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 service. 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 pro‐
tocol. 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_fam‐
ily 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-termi‐
nated 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_options 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 resolu‐
tion is performed. Returns a socket address structure that your
application can use in a call to bind(). If the nodename param‐
eter 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 appli‐
cation can use to call connect() (for a connection-oriented pro‐
tocol) or either connect(), sendto(), or sendmsg() (for a con‐
nectionless 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 options in any combination to achieve finer control of
the translation process. The AI_ADDRCONFIG option is typically used in
combination with other options to modify the search based on the source
address or addresses configured on the system. The following list
describes how the AI_ADDRCONFIG options 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 options to control their search. If you use this combi‐
nation, the following occurs: 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 correspond‐
ing arguments for a call to the socket() function. The ai_addr member
points to a filled-in socket address structure whose length is speci‐
fied 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
specific socket type. The intended socket is unknown. A system
error occurred; errno is set to the error value.
FILES
The IPv4 network hostname database. Each record in the file occupies a
single line and has three fields consisting of the host address, offi‐
cial hostname, and aliases. The IPv6 and IPv4 network hostname data‐
base. 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 con‐
figuration file.
SEE ALSO
Functions: connect(2), freeaddrinfo(3), gai_strerror(3), gethostby‐
name(3), getnameinfo(3), getservbyname(3), socket(2).
Files: hostname(5), ipnodes(4), hosts(4), resolv.conf(4), svc.conf(4).
Networks: bind_intro(7), nis_intro(7).
Standards: standards(5).
Network Programmer's Guide
getaddrinfo(3)
