 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getaddrinfo(3)
NAME
getaddrinfo - 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 supports POSIX.1g Draft 6.6.
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
nodename
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.
servname
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.
hints
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.
res 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:
ai_flags
Controls the processing behavior of getaddrinfo(). See the "ai_flags
Member Values" section for a complete description of the options.
ai_family
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.
ai_socktype
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.
ai_protocol
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:
AI_V4MAPPED
[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.
AI_ALL | AI_V4MAPPED
[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.
AI_CANONNAME
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.
AI_NUMERICHOST
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.
AI_NUMERICSERV
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.
AI_PASSIVE
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.
AI_ADDRCONFIG
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.
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:
[EAI_AGAIN]
The nodename parameter could not be resolved this time. Try the
request again.
[EAI_BADFLAGS]
The value of the flags parameter is invalid.
[EAI_FAIL]
A non-recoverable error occurred.
[EAI_FAMILY]
The address family (ai_family in the hints structure) was not
recognized, or the address length was invalid.
[EAI_MEMORY]
A memory allocation failure occurred.
[EAI_NONAME]
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.
[EAI_SERVICE]
The service passed is unknown for the specific socket type.
[EAI_SOCKTYPE]
The intended socket is unknown.
[EAI_SYSTEM]
A system error occurred; errno is set to the error value.
FILES
/etc/hosts
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.
/etc/ipnodes
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.
/etc/resolv.conf
The resolver configuration file.
/etc/svc.conf
The database service selection configuration file.
SEE ALSO
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|