getaddrinfo - Get address information for a network node
and service
#include <netdb.h>
int getaddrinfo(
const char *nodename,
const char *servname,
const struct addrinfo *hints,
struct addrinfo **res );
Standard C Library (libc)
The getaddrinfo function is compliant with POSIX.1g Draft
6.6. However, 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.
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 location
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 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. 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.
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: Controls the processing behavior of getaddrinfo().
See the "ai_flags Member Values" section for a
complete description of the options. 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 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 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_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 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 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 combination, 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 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.
Upon successful completion, the getaddrinfo() function
returns 0 (zero). Upon failure, it returns a non-zero
value.
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.
The IPv4 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 IPv6 and IPv4 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.
Functions: connect(2), freeaddrinfo(3), gai_strerror(3),
gethostbyname(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)
[ Back ] |
