Sockets Library Functions getaddrinfo(3SOCKET)
NAME
getaddrinfo, getnameinfo, freeaddrinfo, gai_strerror -
translate between node name and addressSYNOPSIS
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, socklen_t salen,
char *host, size_t hostlen, char *serv, size_t servlen,
int flags); void freeaddrinfo(struct addrinfo *ai);char *gai_strerror(int errcode);
DESCRIPTION
These functions perform translations from node name toaddress 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 arepointers to null-terminated strings or NULL. 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: 10 Dec 2009 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 ai_flags; /* AI_PASSIVE, AI_CANONNAME,
AI_NUMERICHOST, AI_NUMERICSERV
AI_V4MAPPED, AI_ALL,
AI_ADDRCONFIG */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 & IPv6 */
socklen_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};In this hints structure, all members other than ai_flags,
ai_family, ai_socktype, and ai_protocol must be 0 or a null
pointer. A value of PF_UNSPEC for ai_family indicates that
the caller will accept any protocol family. A value of 0 forai_socktype indicates that the caller will accept any socket
type. A value of 0 for ai_protocol indicates that the
caller will accept any protocol. For example, if the callerhandles only TCP and not UDP, then the ai_socktype member of
the hints structure should be set to SOCK_STREAM when getad-
drinfo() is called. If the caller handles only IPv4 and notIPv6, then the ai_family member of the hints structure
should be set to PF_INET 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 ai_family set to PF_UNSPEC.
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 listby following the ai_next pointer, until a null pointer is
encountered. In each returned addrinfo structure the threemembers ai_family, ai_socktype, and ai_protocol are the
corresponding arguments for a call to the socket(3SOCKET)function. In each addrinfo structure the ai_addr member
SunOS 5.11 Last change: 10 Dec 2009 2
Sockets Library Functions getaddrinfo(3SOCKET)
points to a filled-in socket address structure whose length
is specified by the ai_addrlen member.
If the AI_PASSIVE bit is set in the ai_flags 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 toINADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an
IPv6 address.If the AI_PASSIVE bit is not set in the ai_flags member of
the hints structure, then the returned socket address struc-
ture will be ready for a call to connect(3SOCKET) (for aconnection-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 AI_CANONNAME bit is set in the ai_flags member of the
hints structure, then upon successful return theai_canonname 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. A numeric host address string is not a name, and thus does not have a canonical name form; no address to host name translation is performed.If the AI_NUMERICHOST bit is set in the ai_flags member of
the hints structure, then a non-null nodename string must be
a numeric host address string. Otherwise an error ofEAI_NONAME is returned. This flag prevents any type of name
resolution service (such as DNS) from being called.If the AI_NUMERICSERV flag is specified, then a non-null
servname string supplied will be a numeric port string.Otherwise, an [EAI_NONAME] error is returned. This flag
prevents any type of name resolution service (for example, NIS) from being invoked.If the AI_V4MAPPED flag is specified along with an ai_family
of AF_INET6, then getaddrinfo() returns IPv4-mapped IPv6
addresses on finding no matching IPv6 addresses (ai_addrlen
shall be 16). For example, if no AAAA records are found when using DNS, a query is made for A records. Any found recordsSunOS 5.11 Last change: 10 Dec 2009 3
Sockets Library Functions getaddrinfo(3SOCKET)
are returned as IPv4-mapped IPv6 addresses.
The AI_V4MAPPED flag is ignored unless ai_family equals
AF_INET6.
If the AI_ALL flag is used with the AI_V4MAPPED flag, then
getaddrinfo() returns all matching IPv6 and IPv4 addresses.
For example, when using the DNS, queries are made for bothAAAA records and A records, and getaddrinfo() returns the
combined results of both queries. Any IPv4 addresses foundare returned as IPv4-mapped IPv6 addresses.
The AI_ALL flag without the AI_V4MAPPED flag is ignored.
When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and
AI_ALL flags are used only if AF_INET6 is supported.
If the AI_ADDRCONFIG 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 AAAA 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 atleast 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 nullai_next pointer is encountered.
To aid applications in printing error messages based on theEAI_* codes returned by getaddrinfo(), the gai_strerror() is
defined. The argument is one of the EAI_* values defined
below and the return value points to a string describing theerror. If the argument is not one of the EAI_* values, the
function still returns a pointer to a string whose contentsSunOS 5.11 Last change: 10 Dec 2009 4
Sockets Library Functions getaddrinfo(3SOCKET)
indicate an unknown error. The getnameinfo() function looks up an IP address and port number provided by the caller in the name service databaseand 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 sockaddr_in
structure (for IPv4) or a sockaddr_in6 structure (for IPv6)
that holds the IP address and port number. The salen argu-
ment gives the length of the sockaddr_in or sockaddr_in6
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 NI_MAXHOST 1025
#define NI_MAXSERV 32
The final argument is a flag that changes the defaultactions of this function. By default, the fully-qualified
domain name (FQDN) for the host is looked up in the nameservice database and returned. If the flag bit NI_NOFQDN is
set, only the node name portion of the FQDN is returned forSunOS 5.11 Last change: 10 Dec 2009 5
Sockets Library Functions getaddrinfo(3SOCKET)
local hosts.If the flag bit NI_NUMERICHOST 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, forexample, by calling inet_ntop() (see inet(3SOCKET)) instead
of getipnodebyname(3SOCKET). If the flag bit NI_NAMEREQD is
set, an error is returned if the host's name cannot be located in the name service database.If the flag bit NI_NUMERICSERV is set, the numeric form of
the service address is returned (for example, its portnumber) instead of its name. The two NI_NUMERIC* flags are
required to support the -n flag that many commands provide.
A fifth flag bit, NI_DGRAM, specifies that the service is a
datagram service, and causes getservbyport(3SOCKET) to be called with a second argument of udp instead of the defaulttcp. 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 orderof the addresses returned i nthe fourth argument is dis-
cussed in the ADDRESS 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, zerovalues for either hostlen or servlen will suppress the asso-
ciated lookup; in this case no data is copied into theapplicable buffer. If gai_strerror() is successful, a
pointer to a string containing an error message appropriatefor 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 OrderingAF_INET6 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 ofpair-wise comparison rules which are applied in order. If a
rule determines that one address is better than another, theSunOS 5.11 Last change: 10 Dec 2009 6
Sockets Library Functions getaddrinfo(3SOCKET)
remaining rules are irrelevant to the comparison of those two addresses. If two addresses are equivalent according toone rule, the remaining rules act as a tie-breaker. The
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. Seeinet6(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 isnot a link-local address.
____________________________________________________________
Avoid deprecated addresses. Prefer a destination that is not deprecated(IFF_DEPRECATED).
____________________________________________________________
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. Seeipaddrsel(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.____________________________________________________________
SunOS 5.11 Last change: 10 Dec 2009 7
Sockets Library Functions getaddrinfo(3SOCKET)
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.____________________________________________________________
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. ||_____________________________|_____________________________|
ERRORS
The following names are the error values returned by getad-
drinfo() and are defined in: EAI_ADDRFAMILY Address family for nodename is not sup-
ported.EAI_AGAIN Temporary failure in name resolution has
occurred .EAI_BADFLAGS Invalid value specified for ai_flags.
EAI_FAIL Non-recoverable failure in name resolution
has occurred.EAI_FAMILY The ai_family is not supported.
EAI_MEMORY Memory allocation failure has occurred.
EAI_NODATA No address is associated with nodename.
EAI_NONAME Neither nodename nor servname is provided
or known.SunOS 5.11 Last change: 10 Dec 2009 8
Sockets Library Functions getaddrinfo(3SOCKET)
EAI_SERVICE The servname is not supported for
ai_socktype.
EAI_SOCKTYPE The ai_socktype is not supported.
EAI_OVERFLOW Argument buffer has overflowed.
EAI_SYSTEM 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 switchATTRIBUTES
See attributes(5) for description of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
ipaddrsel(1M), gethostbyname(3NSL), getipnodebyname(3SOCKET), htonl(3SOCKET), inet(3SOCKET), netdb.h(3HEAD), socket(3SOCKET), hosts(4), nsswitch.conf(4), attributes(5), standards(5), inet6(7P) Draves, R. RFC 3484, Default Address Selection for Internet Protocol version 6 (IPv6). Network Working Group. February 2003.SunOS 5.11 Last change: 10 Dec 2009 9
Sockets Library Functions getaddrinfo(3SOCKET)
NOTESIPv4-mapped addresses are not recommended.
SunOS 5.11 Last change: 10 Dec 2009 10