1getaddrinfo(3SOCKET) Sockets Library Functions getaddrinfo(3SOCKET)
2
6 getaddrinfo, getnameinfo, freeaddrinfo, gai_strerror - translate
7 between node name and address
8
10 cc [ flag... ] file ... -lsocket -lnsl [ library ... ]
11 #include <sys/socket.h>
12 #include <netdb.h>
13 int getaddrinfo(const char *nodename, const char *servname,
15 const struct addrinfo *hints, struct addrinfo **res);
16 int getnameinfo(const struct sockaddr *sa, socklen_t salen,
19 char *host, size_t hostlen, char *serv, size_t servlen,
20 int flags);
21 void freeaddrinfo(struct addrinfo *ai);
24 char *gai_strerror(int errcode);
27
30 These functions perform translations from node name to address and from
31 address to node name in a protocol-independent manner.
32 The getaddrinfo() function performs the node name to address transla‐
35 tion. The nodename and servname arguments are pointers to null-termi‐
36 nated strings or NULL. One or both of these arguments must be a non-
37 null pointer. In the normal client scenario, both the nodename and
38 servname are specified. In the normal server scenario, only the serv‐
39 name is specified.
40 A non-null nodename string can be a node name or a numeric host address
43 string. The nodename can also be an IPv6 zone-id in the form:
44 <address>%<zone-id>
46 The address is the literal IPv6 link-local address or host name of the
50 destination. The zone-id is the interface ID of the IPv6 link used to
51 send the packet. The zone-id can either be a numeric value, indicating
52 a literal zone value, or an interface name such as hme0.
53 A non-null servname string can be either a service name or a decimal
56 port number.
57 The caller can optionally pass an addrinfo structure, pointed to by the
60 hints argument, to provide hints concerning the type of socket that the
61 caller supports.
62 The addrinfo structure is defined as:
65 struct addrinfo {
67 int ai_flags; /* AI_PASSIVE, AI_CANONNAME,
68 AI_NUMERICHOST, AI_NUMERICSERV
69 AI_V4MAPPED, AI_ALL,
70 AI_ADDRCONFIG */
71 int ai_family; /* PF_xxx */
72 int ai_socktype; /* SOCK_xxx */
73 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 & IPv6 */
74 socklen_t ai_addrlen; /* length of ai_addr */
75 char *ai_canonname; /* canonical name for nodename */
76 struct sockaddr *ai_addr; /* binary address */
77 struct addrinfo *ai_next; /* next structure in linked list */
78 };
79 In this hints structure, all members other than ai_flags, ai_family,
83 ai_socktype, and ai_protocol must be 0 or a null pointer. A value of
84 PF_UNSPEC for ai_family indicates that the caller will accept any pro‐
85 tocol family. A value of 0 for ai_socktype indicates that the caller
86 will accept any socket type. A value of 0 for ai_protocol indicates
87 that the caller will accept any protocol. For example, if the caller
88 handles only TCP and not UDP, then the ai_socktype member of the hints
89 structure should be set to SOCK_STREAM when getaddrinfo() is called. If
90 the caller handles only IPv4 and not IPv6, then the ai_family member of
91 the hints structure should be set to PF_INET when getaddrinfo() is
92 called. If the third argument to getaddrinfo() is a null pointer, it is
93 as if the caller had filled in an addrinfo structure initialized to 0
94 with ai_family set to PF_UNSPEC.
95 Upon success, a pointer to a linked list of one or more addrinfo struc‐
98 tures is returned through the final argument. The caller can process
99 each addrinfo structure in this list by following the ai_next pointer,
100 until a null pointer is encountered. In each returned addrinfo struc‐
101 ture the three members ai_family, ai_socktype, and ai_protocol are the
102 corresponding arguments for a call to the socket(3SOCKET) function. In
103 each addrinfo structure the ai_addr member points to a filled-in socket
104 address structure whose length is specified by the ai_addrlen member.
105 If the AI_PASSIVE bit is set in the ai_flags member of the hints struc‐
108 ture, the caller plans to use the returned socket address structure in
109 a call to bind(3SOCKET). In this case, if the nodename argument is a
110 null pointer, the IP address portion of the socket address structure
111 will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for
112 an IPv6 address.
113 If the AI_PASSIVE bit is not set in the ai_flags member of the hints
116 structure, then the returned socket address structure will be ready for
117 a call to connect(3SOCKET) (for a connection-oriented protocol) or
118 either connect(3SOCKET), sendto(3SOCKET), or sendmsg(3SOCKET) (for a
119 connectionless protocol). If the nodename argument is a null pointer,
120 the IP address portion of the socket address structure will be set to
121 the loopback address.
122 If the AI_CANONNAME bit is set in the ai_flags member of the hints
125 structure, then upon successful return the ai_canonname member of the
126 first addrinfo structure in the linked list will point to a null-termi‐
127 nated string containing the canonical name of the specified nodename. A
128 numeric host address string is not a name, and thus does not have a
129 canonical name form; no address to host name translation is performed.
130 If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
133 structure, then a non-null nodename string must be a numeric host
134 address string. Otherwise an error of EAI_NONAME is returned. This flag
135 prevents any type of name resolution service (such as DNS) from being
136 called.
137 If the AI_NUMERICSERV flag is specified, then a non-null servname
140 string supplied will be a numeric port string. Otherwise, an [EAI_NO‐
141 NAME] error is returned. This flag prevents any type of name resolution
142 service (for example, NIS+) from being invoked.
143 If the AI_V4MAPPED flag is specified along with an ai_family of
146 AF_INET6, then getaddrinfo() returns IPv4-mapped IPv6 addresses on
147 finding no matching IPv6 addresses (ai_addrlen shall be 16). For exam‐
148 ple, if no AAAA records are found when using DNS, a query is made for A
149 records. Any found records are returned as IPv4-mapped IPv6 addresses.
150 The AI_V4MAPPED flag is ignored unless ai_family equals AF_INET6.
153 If the AI_ALL flag is used with the AI_V4MAPPED flag, then getad‐
156 drinfo() returns all matching IPv6 and IPv4 addresses. For example,
157 when using the DNS, queries are made for both AAAA records and A
158 records, and getaddrinfo() returns the combined results of both
159 queries. Any IPv4 addresses found are returned as IPv4-mapped IPv6
160 addresses.
161 The AI_ALL flag without the AI_V4MAPPED flag is ignored.
164 When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and AI_ALL
167 flags are used only if AF_INET6 is supported.
168 If the AI_ADDRCONFIG flag is specified, IPv4 addresses are returned
171 only if an IPv4 address is configured on the local system, and IPv6
172 addresses are returned only if an IPv6 address is configured on the
173 local system. For this case, the loopback address is not considered to
174 be as valid as a configured address. For example, when using the DNS, a
175 query for AAAA records should occur only if the node has at least one
176 IPv6 address configured (other than IPv6 loopback) and a query for A
177 records should occur only if the node has at least one IPv4 address
178 configured (other than the IPv4 loopback).
179 All of the information returned by getaddrinfo() is dynamically allo‐
182 cated: the addrinfo structures as well as the socket address structures
183 and canonical node name strings pointed to by the addrinfo structures.
184 The freeaddrinfo() function is called to return this information to the
185 system. For freeaddrinfo(), the addrinfo structure pointed to by the ai
186 argument is freed, along with any dynamic storage pointed to by the
187 structure. This operation is repeated until a null ai_next pointer is
188 encountered.
189 To aid applications in printing error messages based on the EAI_* codes
192 returned by getaddrinfo(), the gai_strerror() is defined. The argument
193 is one of the EAI_* values defined below and the return value points to
194 a string describing the error. If the argument is not one of the EAI_*
195 values, the function still returns a pointer to a string whose contents
196 indicate an unknown error.
197 The getnameinfo() function looks up an IP address and port number pro‐
200 vided by the caller in the name service database and system-specific
201 database, and returns text strings for both in buffers provided by the
202 caller. The function indicates successful completion by a 0 return
203 value; a non-zero return value indicates failure.
204 The first argument, sa, points to either a sockaddr_in structure (for
207 IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address
208 and port number. The salen argument gives the length of the sockaddr_in
209 or sockaddr_in6 structure.
210 The function returns the node name associated with the IP address in
213 the buffer pointed to by the host argument.
214 The function can also return the IPv6 zone-id in the form:
217 <address>%<zone-id>
219 The caller provides the size of this buffer with the hostlen argument.
223 The service name associated with the port number is returned in the
224 buffer pointed to by serv, and the servlen argument gives the length of
225 this buffer. The caller specifies not to return either string by pro‐
226 viding a 0 value for the hostlen or servlen arguments. Otherwise, the
227 caller must provide buffers large enough to hold the node name and the
228 service name, including the terminating null characters.
229 To aid the application in allocating buffers for these two returned
232 strings, the following constants are defined in <netdb.h>:
233 #define NI_MAXHOST 1025
235 #define NI_MAXSERV 32
236 The final argument is a flag that changes the default actions of this
240 function. By default, the fully-qualified domain name (FQDN) for the
241 host is looked up in the name service database and returned. If the
242 flag bit NI_NOFQDN is set, only the node name portion of the FQDN is
243 returned for local hosts.
244 If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be
247 located in the name service, the numeric form of the host's address is
248 returned instead of its name, for example, by calling inet_ntop() (see
249 inet(3SOCKET)) instead of getipnodebyname(3SOCKET). If the flag bit
250 NI_NAMEREQD is set, an error is returned if the host's name cannot be
251 located in the name service database.
252 If the flag bit NI_NUMERICSERV is set, the numeric form of the service
255 address is returned (for example, its port number) instead of its name.
256 The two NI_NUMERIC* flags are required to support the -n flag that many
257 commands provide.
258 A fifth flag bit, NI_DGRAM, specifies that the service is a datagram
261 service, and causes getservbyport(3SOCKET) to be called with a second
262 argument of udp instead of the default tcp. This is required for the
263 few ports (for example, 512-514) that have different services for UDP
264 and TCP.
265 These NI_* flags are defined in <netdb.h> along with the AI_* flags
268 already defined for getaddrinfo().
269
271 For getaddrinfo(), if the query is successful, a pointer to a linked
272 list of one or more addrinfo structures is returned by the fourth argu‐
273 ment and the function returns 0. The order of the addresses returned i
274 nthe fourth argument is discussed in the ADDRESS ORDERING section. If
275 the query fails, a non-zero error code will be returned. For getname‐
276 info(), if successful, the strings hostname and service are copied into
277 host and serv, respectively. If unsuccessful, zero values for either
278 hostlen or servlen will suppress the associated lookup; in this case no
279 data is copied into the applicable buffer. If gai_strerror() is suc‐
280 cessful, a pointer to a string containing an error message appropriate
281 for the EAI_* errors is returned. If errcode is not one of the EAI_*
282 values, a pointer to a string indicating an unknown error is returned.
283 Address Ordering
285 AF_INET6 addresses returned by the fourth argument of getaddrinfo() are
286 ordered according to the algorithm described in RFC 3484, Default
287 Address Selection for Internet Protocol version 6 (IPv6). The addresses
288 are ordered using a list of pair-wise comparison rules which are
289 applied in order. If a rule determines that one address is better than
290 another, the remaining rules are irrelevant to the comparison of those
291 two addresses. If two addresses are equivalent according to one rule,
292 the remaining rules act as a tie-breaker. The address ordering list of
293 pair-wise comparison rules follow below:
294 ┌─────────────────────────────┬─────────────────────────────┐
299 │Avoid unusable destinations. │ Prefer a destination that │
300 │ │ is reachable through the IP │
301 │ │ routing table. │
302 ├─────────────────────────────┼─────────────────────────────┤
303 │Prefer matching scope. │ Prefer a destination whose │
304 │ │ scope is equal to the scope │
305 │ │ of its source address. See │
306 │ │ inet6(7P) for the defini‐ │
307 │ │ tion of scope used by this │
308 │ │ rule. │
309 ├─────────────────────────────┼─────────────────────────────┤
310 │Avoid link-local source. │ Avoid selecting a link- │
311 │ │ local source address when │
312 │ │ the destination address is │
313 │ │ not a link-local address. │
314 ├─────────────────────────────┼─────────────────────────────┤
315 │Avoid deprecated addresses. │ Prefer a destination that │
316 │ │ is not deprecated (IFF_DEP‐ │
317 │ │ RECATED). │
318 ├─────────────────────────────┼─────────────────────────────┤
319 │Prefer matching label. This │ Prefer a destination whose │
320 │rule uses labels that are │ label is equal to the label │
321 │obtained through the IPv6 │ of its source address. │
322 │default address selection │ │
323 │policy table. See ipad‐ │ │
324 │drsel(1M) for a description │ │
325 │of the default contents of │ │
326 │the table and how the table │ │
327 │is configured. │ │
328 ├─────────────────────────────┼─────────────────────────────┤
329 │Prefer higher precedence. │ Prefer the destination │
330 │This rule uses precedence │ whose precedence is higher │
331 │values that are obtained │ than the other destination. │
332 │through the IPv6 default │ │
333 │address selection policy ta‐ │ │
334 │ble. See ipaddrsel(1M) for a │ │
335 │description of the default │ │
336 │contents of the table and │ │
337 │how the table is configured. │ │
338 ├─────────────────────────────┼─────────────────────────────┤
339 │Prefer native transport. │ Prefer a destination if the │
340 │ │ interface that is used for │
341 │ │ sending packets to that │
342 │ │ destination is not an IP │
343 │ │ over IP tunnel. │
344 ├─────────────────────────────┼─────────────────────────────┤
345 │Prefer smaller scope. See │ Prefer the destination │
346 │inet6(7P) for the definition │ whose scope is smaller than │
347 │of this rule. │ the other destination. │
348 ├─────────────────────────────┼─────────────────────────────┤
349 │Use longest matching prefix. │ When the two destinations │
350 │ │ belong to the same address │
351 │ │ family, prefer the destina‐ │
352 │ │ tion that has the longer │
353 │ │ matching prefix with its │
354 │ │ source address. │
355 └─────────────────────────────┴─────────────────────────────┘
356
358 The following names are the error values returned by getaddrinfo() and
359 are defined in <netdb.h>:
360 EAI_ADDRFAMILY Address family for nodename is not supported.
362 EAI_AGAIN Temporary failure in name resolution has occurred .
365 EAI_BADFLAGS Invalid value specified for ai_flags.
368 EAI_FAIL Non-recoverable failure in name resolution has
371 occurred.
372 EAI_FAMILY The ai_family is not supported.
375 EAI_MEMORY Memory allocation failure has occurred.
378 EAI_NODATA No address is associated with nodename.
381 EAI_NONAME Neither nodename nor servname is provided or known.
384 EAI_SERVICE The servname is not supported for ai_socktype.
387 EAI_SOCKTYPE The ai_socktype is not supported.
390 EAI_OVERFLOW Argument buffer has overflowed.
393 EAI_SYSTEM System error was returned in errno.
396
399 /etc/inet/hosts local database that associates names of nodes
400 with IP addresses
401 /etc/netconfig network configuration database
404 /etc/nsswitch.conf configuration file for the name service switch
407
410 See attributes(5) for description of the following attributes:
411 ┌─────────────────────────────┬─────────────────────────────┐
416 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
417 ├─────────────────────────────┼─────────────────────────────┤
418 │Interface Stability │Committed │
419 ├─────────────────────────────┼─────────────────────────────┤
420 │MT-Level │MT-Safe │
421 ├─────────────────────────────┼─────────────────────────────┤
422 │Standard │See standards(5). │
423 └─────────────────────────────┴─────────────────────────────┘
424
426 ipaddrsel(1M), gethostbyname(3NSL), getipnodebyname(3SOCKET),
427 htonl(3SOCKET), inet(3SOCKET), netdb.h(3HEAD), socket(3SOCKET),
428 hosts(4), nsswitch.conf(4), attributes(5), standards(5), inet6(7P)
429 Draves, R. RFC 3484, Default Address Selection for Internet Protocol
432 version 6 (IPv6). Network Working Group. February 2003.
433
435 IPv4-mapped addresses are not recommended.
436SunOS 5.11 8 May 2009 getaddrinfo(3SOCKET)