Takes a service location (nodename) or a service name (servname),
or both, and returns a pointer to a linked list of one or more
structures of type addrinfo.
Format
#include <socket.h>
#include <netdb.h>
int getaddrinfo ( const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo
**res );
1 – Arguments
nodename
Points to a network node name, alias, or numeric host address
(for example, an IPv4 dotted-decimal address or an IPv6
hexadecimal address). An IPv6 nonglobal address with an intended
scope zone may also be specified. This is a null-terminated
string or NULL. NULL means the service location is local to the
caller. The nodename and servname arguments must not both be
NULL.
servname
Points to a network service name or port number. This is a null-
terminated string or NULL; NULL returns network-level addresses
for the specified nodename. The nodename and servname arguments
must not both be NULL.
hints
Points to an addrinfo structure that contains information about
the type of socket, address family, or protocol the caller
supports. The NETDB.H header file defines the addrinfo structure.
If hints is a null pointer, the behavior is the same as if
addrinfo contained the value 0 for the ai_flags, ai_socktype
and ai_protocol members and AF_UNSPEC for the ai_family member.
res
Points to a linked list of one or more addrinfo structures.
2 – Description
This function takes a service location (nodename) or a service
name (servname), or both, and returns a pointer to a linked list
of one or more structures of type addrinfo. Its members specify
data obtained from the local hosts database TCPIP$ETC:IPNODES.DAT
file, the local TCPIP$HOSTS.DAT file, or one of the files
distributed by DNS/BIND.
The NETDB.H header file defines the addrinfo structure.
If the hints argument is non-NULL, all addrinfo structure members
other than the following members must be zero or a NULL pointer:
o ai_flags
Controls the processing behavior of getaddrinfo(). See Member
Values for a complete description of the flags.
o ai_family
Specifies to return addresses for use with a specific protocol
family.
- If you specify a value of AF_UNSPEC, getaddrinfo() returns
addresses for any protocol family that can be used with
nodename or servname.
- If the value is not AF_UNSPEC and ai_protocol is not zero,
getaddrinfo() 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.
o 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.
o 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.
Member Values describes the values for ai_flags members.
Table 4-1 ai_flags Member Values
Flag Value Description
AI_V4MAPPED If ai_family is AF_INET, the flag is ignored.
If ai_family is AF_INET6, getaddrinfo() searches
for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, returns IPv6
addresses; no search for A records is
performed.
o If no AAAA records are found, searches for A
records.
o If A records found, returns IPv4-mapped IPv6
addresses.
o If no A records found, returns a NULL
pointer.
AI_ALL| If ai_family is AF_INET, the flag is ignored.
AI_V4MAPPED
If the ai_family is AF_INET6, getaddrinfo()
searches for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, IPv6 addresses
will be included with the returned addresses.
o If A records are found, returns IPv4-mapped
IPv6 addresses and also any IPv6 addresses
that were found with the AAAA record search.
o If no A records found, returns a NULL
pointer.
AI_CANONNAME If the nodename argument is not NULL, 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
node name.
If the nodename argument is an address literal,
the ai_cannonname member will refer to the
nodename argument that has been converted to
its numeric binary form, in network byte order.
If the canonical name is not available, the ai_
canonname member refers to the nodename argument
or to a string with the same contents.
The ai_flags field contents are undefined.
AI_NUMERICHOST A non-NULL node name string must be a numeric
host address string.
Resolution of the service name is not performed.
AI_NUMERICSERV A non-NULL service name string must be a numeric
port string.
Resolution of the service name is not 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
argument is a NULL pointer, the IP address
portion of the socket address structure is set
to the loopback address.
AI_ADDRCONFIG Used in combination with other flags, modifies
the search based on the source address or
addresses configured on the system.
You can use the flags in any combination to achieve finer control
of the translation process. Many applications use the combination
of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their
search.
o If the value of ai_family is AF_INET, and an IPv4 source
address is configured on the system, getaddrinfo() searches
for A records only. If found, getaddrinfo() returns IPv4
addresses. If not, getaddrinfo() returns a NULL pointer.
o If the value of ai_family is AF_INET6 and an IPv6 source
address is configured on the system, getaddrinfo() searches
for AAAA records. If found, getaddrinfo() returns IPv6
addresses. If not, and if an IPv4 address is configured on
the system, getaddrinfo() searches for A records. If found,
getaddrinfo() returns IPv4-mapped IPv6 addresses. If not,
getaddrinfo() returns a NULL pointer.
These flags are defined in the NETDB.H header file.
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.
3 – Return Values
0 Indicates success
-1 Indicates an error
4 – 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 nonrecoverable 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 supplied. At least one of these must be
supplied.
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.