svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
getaddrinfo(3c)
getaddrinfo(3C) Standard C Library Functions getaddrinfo(3C)
NAME
getaddrinfo - translate between node name and address
SYNOPSIS
#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo(const char *restrict nodename,
const char *restrict servname,
const struct addrinfo *restrict hints,
struct addrinfo **restrict res);
DESCRIPTION
The getaddrinfo() function translates the name of a service location
(for example, a host name) and/or a service name and returns a set of
socket addresses and associated information to be used in creating a
socket with which to address the specified service. The getaddrinfo()
function performs the node name to address translation in a protocol-
independent manner.
The nodename and servname arguments are pointers 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 specified. In the normal server scenario, only the servname is
specified.
The format of a valid name depends on the address family or families.
If a specific family is not given and the name could be interpreted as
valid within multiple supported families, the implementation attempts
to resolve the name in all supported families and, in absence of er‐
rors, one or more results are returned.
If nodename is not null, the requested service location is named by
nodename; otherwise, the requested service location is local to the
caller.
If the nodename argument is not null, it can be a descriptive name or
an address string. If the specified address family is AF_INET,
AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
the specified address family is AF_INET or AF_UNSPEC, address strings
using Internet standard dot notation as specified in inet_addr(3C) are
valid.
If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
text forms described in inet_ntop(3C) are valid. The nodename can also
be an IPv6 zone-id in the form:
address%zone-id
where the address is the literal IPv6 link-local address or host name
of the destination, and 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
net0.
If servname is null, the call returns network-level addresses for the
specified nodename. If servname is not null, it is a null-terminated
character string identifying the requested service. This string can be
either a descriptive name or a numeric representation suitable for use
with the address family or families. If the specified address family is
AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
string specifying a decimal port number.
The caller can optionally pass an addrinfo structure, pointed to by the
hints argument, to provide hints concerning 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 pro‐
tocol family. A value of 0 for ai_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 caller
handles only TCP and not UDP, then the ai_socktype member of the hints
structure should be set to SOCK_STREAM when getaddrinfo() is called. If
the caller handles only IPv4 and not IPv6, 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 initialized to 0
with ai_family set to PF_UNSPEC.
Upon success, a pointer to a linked list of one or more addrinfo struc‐
tures is returned through the final argument. The caller can process
each addrinfo structure in this list by following the ai_next pointer,
until a null pointer is encountered. In each returned addrinfo struc‐
ture the three members ai_family, ai_socktype, and ai_protocol are the
corresponding arguments for a call to the socket(3C) function. In each
addrinfo structure the ai_addr member points to a filled-in socket ad‐
dress 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 struc‐
ture, the caller plans to use the returned socket address structure in
a call to bind(3C). In this case, if the nodename argument is a null
pointer, the IP address portion of the socket address structure will be
set to INADDR_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 structure will be ready for
a call to connect(3C) (for a connection-oriented protocol) or either
connect(3C), sendto(3C), or sendmsg(3C) (for a connectionless proto‐
col). If the nodename argument is a null pointer, the IP address por‐
tion of the socket address structure will be set to the loopback ad‐
dress.
If the AI_CANONNAME bit is set in the ai_flags member of the hints
structure, then upon successful return the ai_canonname member of the
first addrinfo structure in the linked list will point to a null-termi‐
nated string containing 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 ad‐
dress string. Otherwise an error of EAI_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_NON‐
AME] 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 exam‐
ple, if no AAAA records are found when using DNS, a query is made for A
records. Any found records 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 getad‐
drinfo() returns all matching IPv6 and IPv4 addresses. For example,
when using the DNS, queries are made for both AAAA records and A
records, and getaddrinfo() returns the combined results of both
queries. Any IPv4 addresses found are returned as IPv4-mapped IPv6 ad‐
dresses.
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 ad‐
dresses 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 at least one IPv4 address configured
(other than the IPv4 loopback).
The ai_socktype member to which argument hints points specifies the
socket type for the service, as defined in socket(3C). If a specific
socket type is not given (for example, a value of 0) and the service
name could be interpreted as valid with multiple supported socket
types, the implementation attempts to resolve the service name for all
supported socket types and, in the absence of errors, all possible re‐
sults are returned. A non-zero socket type value limits the returned
information to values with the specified socket type.
If the ai_family member to which hints points has the value AF_UNSPEC,
addresses are returned for use with any address family that can be used
with the specified nodename and/or servname. Otherwise, addresses are
returned for use only with the specified address family. If ai_family
is not AF_UNSPEC and ai_protocol is not 0, then addresses are returned
for use only with the specified address family and protocol; the value
of ai_protocol is interpreted as in a call to the socket() function
with the corresponding values of ai_family and ai_protocol.
All of the information returned by getaddrinfo() is dynamically allo‐
cated: the addrinfo structures as well as the socket address structures
and canonical node name strings pointed to by the addrinfo structures.
The freeaddrinfo(3C) function is called to return this memory 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 ai_next pointer is
encountered.
To aid applications in printing error messages based on the EAI_* codes
returned by getaddrinfo(), the gai_strerror(3C) function 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.
RETURN VALUES
A 0 return value for getaddrinfo() indicates successful completion; a
non-zero return value indicates failure. The possible values for the
failures are listed in the ERRORS section.
Upon successful return of getaddrinfo(), the location to which res
points refers to a linked list of addrinfo structures, each of which
specifies a socket address and information for use in creating a socket
with which to use that socket address. The list includes at least one
addrinfo structure. The ai_next member of each structure contains a
pointer to the next structure on the list, or a null pointer if it is
the last structure on the list. Each structure on the list includes
values for use with a call to the socket function, and a socket address
for use with the connect function or, if the AI_PASSIVE flag was speci‐
fied, for use with the bind(3C) function. The ai_family, ai_socktype,
and ai_protocol members are usable as the arguments to the socket()
function to create a socket suitable for use with the returned address.
The ai_addr and ai_addrlen members are usable as the arguments to the
connect() or bind() functions with such a socket, according to the
AI_PASSIVE flag.
If nodename is not null, and if requested by the AI_CANONNAME flag, the
ai_canonname member of the first returned addrinfo structure points to
a null-terminated string containing the canonical name corresponding to
the input nodename. If the canonical name is not available, then
ai_canonname refers to the nodename argument or a string with the same
contents. The contents of the ai_flags member of the returned struc‐
tures are undefined.
All members in socket address structures returned by getaddrinfo() that
are not filled in through an explicit argument (for example, sin6_flow‐
info) are set to 0, making it easier to compare socket address struc‐
tures.
Address Ordering
AF_INET6 addresses returned by the fourth argument of getaddrinfo() are
ordered according to the algorithm described in RFC 3484, Default Ad‐
dress Selection for Internet Protocol version 6 (IPv6). The addresses
are ordered using a list of pair-wise comparison rules which are ap‐
plied 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 address ordering list of
pair-wise comparison rules follow below:
tab() box; lw(2.75i) |lw(2.75i) Avoid unusable destinations.T{ Prefer a
destination that is reachable through the IP routing table. T} _ Pre‐
fer matching scope.T{ Prefer a destination whose scope is equal to the
scope of its source address. See inet6(4P) for the definition of scope
used by this rule. T} _ Avoid link-local source.T{ Avoid selecting a
link-local source address when the destination address is not a link-
local address. T} _ Avoid deprecated addresses.T{ Prefer a destination
that is not deprecated (IFF_DEPRECATED). T} _ T{ Prefer matching la‐
bel. This rule uses labels that are obtained through the IPv6 default
address selection policy table. See ipaddrsel(8) for a description of
the default contents of the table and how the table is configured.
T}T{ Prefer a destination whose label is equal to the label of its
source address. T} _ T{ Prefer higher precedence. This rule uses
precedence values that are obtained through the IPv6 default address
selection policy table. See ipaddrsel(8) for a description of the de‐
fault contents of the table and how the table is configured. T}T{ Pre‐
fer the destination whose precedence is higher than the other destina‐
tion. T} _ Prefer native transport.T{ Prefer a destination if the in‐
terface that is used for sending packets to that destination is not an
IP over IP tunnel. T} _ T{ Prefer smaller scope. See inet6(4P) for the
definition of this rule. T}T{ Prefer the destination whose scope is
smaller than the other destination. T} _ Use longest matching pre‐
fix.T{ When the two destinations belong to the same address family,
prefer the destination that has the longer matching prefix with its
source address. T}
ERRORS
The following names are the error values returned by getaddrinfo() and
are defined in <netdb.h>:
EAI_ADDRFAMILY Address family for nodename is not supported.
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 oc‐
curred.
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.
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.
USAGE
If the caller handles only TCP and not UDP, for example, then the
ai_protocol member of the hints structure should be set to IPPROTO_TCP
when getaddrinfo() is called.
If the caller handles only IPv4 and not IPv6, then the ai_family member
of the hints structure should be set to AF_INET when getaddrinfo() is
called.
FILES
/etc/netconfig network configuration database
/etc/default/nss configuration file for the name service switch
ATTRIBUTES
See attributes(7) for description of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe _ Stan‐
dardSee standards(7).
SEE ALSO
bind(3C), connect(3C), freeaddrinfo(3C), gai_strerror(3C), gethostby‐
name(3C), getipnodebyname(3C), getnameinfo(3C), getservbyname(3C),
htonl(3C), inet(3C), inet_addr(3C), inet_ntop(3C), sendmsg(3C),
sendto(3C), socket(3C), netdb.h(3HEAD), inet6(4P), hosts(5), nss(5),
nsswitch.conf(5), attributes(7), standards(7), ipaddrsel(8)
Draves, R. RFC 3484, Default Address Selection for Internet Protocol
version 6 (IPv6). Network Working Group. February 2003.
https://tools.ietf.org/html/rfc3484
Gilligan, R. RFC 3493, Basic Socket Interface Extensions for IPv6. Net‐
work Working Group. February 2003. https://tools.ietf.org/html/rfc3493
NOTES
IPv4-mapped addresses are not recommended.
HISTORY
The getaddrinfo() function was added to Oracle Solaris in the Solaris 8
release.
Oracle Solaris 11.4 6 Oct 2022 getaddrinfo(3C)