Sockets Library Functions getaddrinfo(3SOCKET)
NAME
getaddrinfo, getnameinfo, freeaddrinfo, gaistrerror -
translate between node name and address
SYNOPSIS
cc [ flag... ] file ... -lsocket -lnsl [ library ... ]
#include
#include
int getaddrinfo(const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo **res);
int getnameinfo(const struct sockaddr *sa, socklent salen,
char *host, sizet hostlen, char *serv, sizet servlen,
int flags);
void freeaddrinfo(struct addrinfo *ai);
char *gaistrerror(int errcode);
DESCRIPTION
These functions perform translations from node name to
address and from address to node name in a protocol-
independent manner.
The getaddrinfo() function performs the node name to address
translation. The nodename and servname arguments are
pointers to null-terminated strings or NUL. One or both of
these arguments must be a non-null pointer. In the normal
client scenario, both the nodename and servname are speci-
fied. In the normal server scenario, only the servname is
specified.
A non-null nodename string can be a node name or a numeric
host address string. The nodename can also be an IPv6 zone-
id in the form:
%
The address is the literal IPv6 link-local address or host
name of the destination. The zone-id is the interface ID of
the IPv6 link used to send the packet. The zone-id can
either be a numeric value, indicating a literal zone value,
or an interface name such as hme0.
SunOS 5.11 Last change: 14 Nov 2007 1
Sockets Library Functions getaddrinfo(3SOCKET)
A non-null servname string can be either a service name or a
decimal port number.
The caller can optionally pass an addrinfo structure,
pointed to by the hints argument, to provide hints concern-
ing the type of socket that the caller supports.
The addrinfo structure is defined as:
struct addrinfo {
int aiflags; /* AIPASIVE, AICANONAME,
AINUMERICHOST, AINUMERICSERV
AIV4MAPED, AIAL,
AIADRCONFIG */
int aifamily; /* PFxxx */
int aisocktype; /* SOCKxxx */
int aiprotocol; /* 0 or IPROTOxxx for IPv4 & IPv6 */
socklent aiaddrlen; /* length of aiaddr */
char *aicanonname; /* canonical name for nodename */
struct sockaddr *aiaddr; /* binary address */
struct addrinfo *ainext; /* next structure in linked list */
};
In this hints structure, all members other than aiflags,
aifamily, aisocktype, and aiprotocol must be 0 or a null
pointer. A value of PFUNSPEC for aifamily indicates that
the caller will accept any protocol family. A value of 0 for
aisocktype indicates that the caller will accept any socket
type. A value of 0 for aiprotocol indicates that the
caller will accept any protocol. For example, if the caller
handles only TCP and not UDP, then the aisocktype member of
the hints structure should be set to SOCKSTREAM when getad-
drinfo() is called. If the caller handles only IPv4 and not
IPv6, then the aifamily member of the hints structure
should be set to PFINET when getaddrinfo() is called. If
the third argument to getaddrinfo() is a null pointer, it is
as if the caller had filled in an addrinfo structure ini-
tialized to 0 with aifamily set to PFUNSPEC.
Upon success, a pointer to a linked list of one or more
addrinfo structures is returned through the final argument.
The caller can process each addrinfo structure in this list
by following the ainext pointer, until a null pointer is
encountered. In each returned addrinfo structure the three
members aifamily, aisocktype, and aiprotocol are the
corresponding arguments for a call to the socket(3SOCKET)
function. In each addrinfo structure the aiaddr member
SunOS 5.11 Last change: 14 Nov 2007 2
Sockets Library Functions getaddrinfo(3SOCKET)
points to a filled-in socket address structure whose length
is specified by the aiaddrlen member.
If the AIPASIVE bit is set in the aiflags member of the
hints structure, the caller plans to use the returned socket
address structure in a call to bind(3SOCKET). In this case,
if the nodename argument is a null pointer, the IP address
portion of the socket address structure will be set to
INADRANY for an IPv4 address or IN6ADRANYINIT for an
IPv6 address.
If the AIPASIVE bit is not set in the aiflags member of
the hints structure, then the returned socket address struc-
ture will be ready for a call to connect(3SOCKET) (for a
connection-oriented protocol) or either connect(3SOCKET),
sendto(3SOCKET), or sendmsg(3SOCKET) (for a connectionless
protocol). If the nodename argument is a null pointer, the
IP address portion of the socket address structure will be
set to the loopback address.
If the AICANONAME bit is set in the aiflags member of the
hints structure, then upon successful return the
aicanonname member of the first addrinfo structure in the
linked list will point to a null-terminated string contain-
ing the canonical name of the specified nodename.
If the AINUMERICHOST bit is set in the aiflags member of
the hints structure, then a non-null nodename string must be
a numeric host address string. Otherwise an error of
EAINONAME is returned. This flag prevents any type of name
resolution service (such as DNS) from being called.
If the AINUMERICSERV flag is specified, then a non-null
servname string supplied shall be a numeric port string.
Otherwise, an [EAINONAME] error is returned. This flag
prevents any type of name resolution service (for example,
NIS]) from being invoked.
If the AIV4MAPED flag is specified along with an aifamily
of AFINET6, then getaddrinfo() returns IPv4-mapped IPv6
addresses on finding no matching IPv6 addresses (aiaddrlen
shall be 16). For example, if no A records are found when
using DNS, a query is made for A records. Any found records
are returned as IPv4-mapped IPv6 addresses.
SunOS 5.11 Last change: 14 Nov 2007 3
Sockets Library Functions getaddrinfo(3SOCKET)
The AIV4MAPED flag is ignored unless aifamily equals
AFINET6.
If the AIAL flag is used with the AIV4MAPED flag, then
getaddrinfo() returns all matching IPv6 and IPv4 addresses.
For example, when using the DNS, queries are made for both
A records and A records, and getaddrinfo() returns the
combined results of both queries. Any IPv4 addresses found
are returned as IPv4-mapped IPv6 addresses.
The AIAL flag without the AIV4MAPED flag is ignored.
When aifamily is not specified (AFUNSPEC), AIV4MAPED and
AIAL flags are used only if AFINET6 is supported.
If the AIADRCONFIG flag is specified, IPv4 addresses are
returned only if an IPv4 address is configured on the local
system, and IPv6 addresses are returned only if an IPv6
address is configured on the local system. For this case,
the loopback address is not considered to be as valid as a
configured address. For example, when using the DNS, a query
for A records should occur only if the node has at least
one IPv6 address configured (other than IPv6 loopback) and a
query for A records should occur only if the node has at
least one IPv4 address configured (other than the IPv4 loop-
back).
All of the information returned by getaddrinfo() is dynami-
cally allocated: the addrinfo structures as well as the
socket address structures and canonical node name strings
pointed to by the addrinfo structures. The freeaddrinfo()
function is called to return this information to the system.
For freeaddrinfo(), the addrinfo structure pointed to by the
ai argument is freed, along with any dynamic storage pointed
to by the structure. This operation is repeated until a null
ainext pointer is encountered.
To aid applications in printing error messages based on the
EAI* codes returned by getaddrinfo(), the gaistrerror() is
defined. The argument is one of the EAI* values defined
below and the return value points to a string describing the
error. If the argument is not one of the EAI* values, the
function still returns a pointer to a string whose contents
indicate an unknown error.
SunOS 5.11 Last change: 14 Nov 2007 4
Sockets Library Functions getaddrinfo(3SOCKET)
The getnameinfo() function looks up an IP address and port
number provided by the caller in the name service database
and system-specific database, and returns text strings for
both in buffers provided by the caller. The function indi-
cates successful completion by a 0 return value; a non-zero
return value indicates failure.
The first argument, sa, points to either a sockaddrin
structure (for IPv4) or a sockaddrin6 structure (for IPv6)
that holds the IP address and port number. The salen argu-
ment gives the length of the sockaddrin or sockaddrin6
structure.
The function returns the node name associated with the IP
address in the buffer pointed to by the host argument.
The function can also return the IPv6 zone-id in the form:
%
The caller provides the size of this buffer with the hostlen
argument. The service name associated with the port number
is returned in the buffer pointed to by serv, and the
servlen argument gives the length of this buffer. The caller
specifies not to return either string by providing a 0 value
for the hostlen or servlen arguments. Otherwise, the caller
must provide buffers large enough to hold the node name and
the service name, including the terminating null characters.
To aid the application in allocating buffers for these two
returned strings, the following constants are defined in
:
#define NIMAXHOST 1025
#define NIMAXSERV 32
The final argument is a flag that changes the default
actions of this function. By default, the fully-qualified
domain name (FQDN) for the host is looked up in the name
service database and returned. If the flag bit NINOFQDN is
set, only the node name portion of the FQDN is returned for
local hosts.
SunOS 5.11 Last change: 14 Nov 2007 5
Sockets Library Functions getaddrinfo(3SOCKET)
If the flag bit NINUMERICHOST is set, or if the host's name
cannot be located in the name service, the numeric form of
the host's address is returned instead of its name, for
example, by calling inetntop() (see inet(3SOCKET)) instead
of getipnodebyname(3SOCKET). If the flag bit NINAMEREQD is
set, an error is returned if the host's name cannot be
located in the name service database.
If the flag bit NINUMERICSERV is set, the numeric form of
the service address is returned (for example, its port
number) instead of its name. The two NINUMERIC* flags are
required to support the -n flag that many commands provide.
A fifth flag bit, NIDGRAM, specifies that the service is a
datagram service, and causes getservbyport(3SOCKET) to be
called with a second argument of udp instead of the default
tcp. This is required for the few ports (for example, 512-
514) that have different services for UDP and TCP.
These NI* flags are defined in along with the
AI* flags already defined for getaddrinfo().
RETURN VALUES
For getaddrinfo(), if the query is successful, a pointer to
a linked list of one or more addrinfo structures is returned
by the fourth argument and the function returns 0. The order
of the addresses returned i nthe fourth argument is dis-
cussed in the ADRES ORDERING section. If the query fails,
a non-zero error code will be returned. For getnameinfo(),
if successful, the strings hostname and service are copied
into host and serv, respectively. If unsuccessful, zero
values for either hostlen or servlen will suppress the asso-
ciated lookup; in this case no data is copied into the
applicable buffer. If gaistrerror() is successful, a
pointer to a string containing an error message appropriate
for the EAI* errors is returned. If errcode is not one of
the EAI* values, a pointer to a string indicating an
unknown error is returned.
Address Ordering
AFINET6 addresses returned by the fourth argument of getad-
drinfo() are ordered according to the algorithm described in
RFC 3484, Default Address Selection for Internet Protocol
version 6 (IPv6). The addresses are ordered using a list of
pair-wise comparison rules which are applied in order. If a
rule determines that one address is better than another, the
remaining rules are irrelevant to the comparison of those
two addresses. If two addresses are equivalent according to
one rule, the remaining rules act as a tie-breaker. The
SunOS 5.11 Last change: 14 Nov 2007 6
Sockets Library Functions getaddrinfo(3SOCKET)
address ordering list of pair-wise comparison rules follow
below:
Avoid unusable destinations. Prefer a destination that
is reachable through the IP
routing table.
Prefer matching scope. Prefer a destination whose
scope is equal to the scope
of its source address. See
inet6(7P) for the defini-
tion of scope used by this
rule.
Avoid link-local source. Avoid selecting a link-
local source address when
the destination address is
not a link-local address.
Avoid deprecated addresses. Prefer a destination that
is not deprecated
(IFDEPRECATED).
Prefer matching label. This Prefer a destination whose
rule uses labels that are label is equal to the label
obtained through the IPv6 of its source address.
default address selection
policy table. See
ipaddrsel(1M) for a descrip-
tion of the default contents
of the table and how the
table is configured.
Prefer higher precedence. Prefer the destination
This rule uses precedence whose precedence is higher
values that are obtained than the other destination.
through the IPv6 default
address selection policy
table. See ipaddrsel(1M) for
a description of the default
contents of the table and
how the table is configured.
Prefer native transport. Prefer a destination if the
interface that is used for
sending packets to that
destination is not an IP
over IP tunnel.
SunOS 5.11 Last change: 14 Nov 2007 7
Sockets Library Functions getaddrinfo(3SOCKET)
Prefer smaller scope. See Prefer the destination
inet6(7P) for the definition whose scope is smaller than
of this rule. the other destination.
Use longest matching prefix. When the two destinations
belong to the same address
family, prefer the destina-
tion that has the longer
matching prefix with its
source address.
ERORS
The following names are the error values returned by getad-
drinfo() and are defined in :
EAIADRFAMILY Address family for nodename is not sup-
ported.
EAIAGAIN Temporary failure in name resolution has
occurred .
EAIBADFLAGS Invalid value specified for aiflags.
EAIFAIL Non-recoverable failure in name resolution
has occurred.
EAIFAMILY The aifamily is not supported.
EAIMEMORY Memory allocation failure has occurred.
EAINODATA No address is associated with nodename.
EAINONAME Neither nodename nor servname is provided
or known.
EAISERVICE The servname is not supported for
aisocktype.
EAISOCKTYPE The aisocktype is not supported.
SunOS 5.11 Last change: 14 Nov 2007 8
Sockets Library Functions getaddrinfo(3SOCKET)
EAIOVERFLOW Argument buffer has overflowed.
EAISYSTEM System error was returned in errno.
FILES
/etc/inet/hosts local database that associates names
of nodes with IP addresses
/etc/netconfig network configuration database
/etc/nsswitch.conf configuration file for the name ser-
vice switch
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
ipaddrsel(1M), gethostbyname(3NSL),
getipnodebyname(3SOCKET), htonl(3SOCKET), inet(3SOCKET),
netdb.h(3HEAD), socket(3SOCKET), hosts(4), nsswitch.conf(4),
inet6(7P)
Draves, R. RFC 3484, Default Address Selection for Internet
Protocol version 6 (IPv6). Network Working Group. February
2003.
NOTES
IPv4-mapped addresses are not recommended.
SunOS 5.11 Last change: 14 Nov 2007 9
|
