]>
Commit | Line | Data |
---|---|---|
a3edd71d MK |
1 | .\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com> | |
3 | .\" A few pieces of an earlier version remain: | |
4 | .\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com> | |
fea681da | 5 | .\" |
5fbde956 | 6 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
7 | .\" |
8 | .\" References: RFC 2553 | |
8d18d6ed | 9 | .\" |
c13182ef | 10 | .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, |
8d18d6ed | 11 | .\" and AI_NUMERICSERV. |
a3edd71d MK |
12 | .\" 2006-11-25, Ulrich Drepper <drepper@redhat.com> |
13 | .\" Add text describing Internationalized Domain Name extensions. | |
35bf3cc8 | 14 | .\" 2007-06-08, mtk: added example programs |
0af804ac MK |
15 | .\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other |
16 | .\" minor rewrites. | |
a3edd71d | 17 | .\" 2008-06-18, mtk: many parts rewritten |
00269a5a PB |
18 | .\" 2008-12-04, Petr Baudis <pasky@suse.cz> |
19 | .\" Describe results ordering and reference /etc/gai.conf. | |
bea08fec | 20 | .\" |
273f6680 MK |
21 | .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support |
22 | .\" and is SCTP support now also there? | |
8d18d6ed | 23 | .\" |
6e00b7a8 | 24 | .TH GETADDRINFO 3 2021-08-27 "GNU" "Linux Programmer's Manual" |
fea681da | 25 | .SH NAME |
a3edd71d MK |
26 | getaddrinfo, freeaddrinfo, gai_strerror \- network address and |
27 | service translation | |
cfba38f4 AC |
28 | .SH LIBRARY |
29 | Standard C library | |
30 | .RI ( libc ", " \-lc ) | |
fea681da MK |
31 | .SH SYNOPSIS |
32 | .nf | |
33 | .B #include <sys/types.h> | |
34 | .B #include <sys/socket.h> | |
35 | .B #include <netdb.h> | |
68e4db0a | 36 | .PP |
85421471 AC |
37 | .BI "int getaddrinfo(const char *restrict " node , |
38 | .BI " const char *restrict " service , | |
39 | .BI " const struct addrinfo *restrict " hints , | |
40 | .BI " struct addrinfo **restrict " res ); | |
68e4db0a | 41 | .PP |
85421471 | 42 | .BI "void freeaddrinfo(struct addrinfo *" res ); |
68e4db0a | 43 | .PP |
85421471 | 44 | .BI "const char *gai_strerror(int " errcode ); |
fea681da | 45 | .fi |
68e4db0a | 46 | .PP |
d39ad78f | 47 | .RS -4 |
0f200f07 MK |
48 | Feature Test Macro Requirements for glibc (see |
49 | .BR feature_test_macros (7)): | |
d39ad78f | 50 | .RE |
68e4db0a | 51 | .PP |
0f200f07 MK |
52 | .BR getaddrinfo (), |
53 | .BR freeaddrinfo (), | |
54 | .BR gai_strerror (): | |
9d2adbae | 55 | .nf |
51a6f93d MK |
56 | Since glibc 2.22: |
57 | _POSIX_C_SOURCE >= 200112L | |
58 | Glibc 2.21 and earlier: | |
59 | _POSIX_C_SOURCE | |
9d2adbae | 60 | .fi |
fea681da | 61 | .SH DESCRIPTION |
0af804ac MK |
62 | Given |
63 | .I node | |
64 | and | |
65 | .IR service , | |
a3edd71d | 66 | which identify an Internet host and a service, |
0af804ac | 67 | .BR getaddrinfo () |
a3edd71d MK |
68 | returns one or more |
69 | .I addrinfo | |
70 | structures, each of which contains an Internet address | |
71 | that can be specified in a call to | |
0af804ac | 72 | .BR bind (2) |
a3edd71d MK |
73 | or |
74 | .BR connect (2). | |
fea681da | 75 | The |
2777b1ca | 76 | .BR getaddrinfo () |
fea681da | 77 | function combines the functionality provided by the |
823ecd0c MK |
78 | .\" .BR getipnodebyname (3), |
79 | .\" .BR getipnodebyaddr (3), | |
1be94306 | 80 | .BR gethostbyname (3) |
fea681da | 81 | and |
1d8d141a | 82 | .BR getservbyname (3) |
0af804ac | 83 | functions into a single interface, but unlike the latter functions, |
2777b1ca | 84 | .BR getaddrinfo () |
a3edd71d | 85 | is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. |
fea681da MK |
86 | .PP |
87 | The | |
8478ee02 | 88 | .I addrinfo |
a3edd71d MK |
89 | structure used by |
90 | .BR getaddrinfo () | |
91 | contains the following fields: | |
51f5698d | 92 | .PP |
3ad4ddcd | 93 | .in +4n |
b8302363 | 94 | .EX |
89f9f5b2 MK |
95 | struct addrinfo { |
96 | int ai_flags; | |
97 | int ai_family; | |
98 | int ai_socktype; | |
99 | int ai_protocol; | |
a05228ea | 100 | socklen_t ai_addrlen; |
89f9f5b2 MK |
101 | struct sockaddr *ai_addr; |
102 | char *ai_canonname; | |
103 | struct addrinfo *ai_next; | |
104 | }; | |
b8302363 | 105 | .EE |
e646a1ba | 106 | .in |
fea681da | 107 | .PP |
fea681da | 108 | The |
fea681da | 109 | .I hints |
a3edd71d | 110 | argument points to an |
0af804ac MK |
111 | .I addrinfo |
112 | structure that specifies criteria for selecting the socket address | |
113 | structures returned in the list pointed to by | |
114 | .IR res . | |
a3edd71d MK |
115 | If |
116 | .I hints | |
117 | is not NULL it points to an | |
8478ee02 | 118 | .I addrinfo |
a3edd71d | 119 | structure whose |
fea681da MK |
120 | .IR ai_family , |
121 | .IR ai_socktype , | |
122 | and | |
123 | .I ai_protocol | |
a3edd71d MK |
124 | specify criteria that limit the set of socket addresses returned by |
125 | .BR getaddrinfo (), | |
126 | as follows: | |
0019177e | 127 | .TP |
fea681da | 128 | .I ai_family |
a3edd71d MK |
129 | This field specifies the desired address family for the returned addresses. |
130 | Valid values for this field include | |
1ae6b2c7 | 131 | .B AF_INET |
a3edd71d MK |
132 | and |
133 | .BR AF_INET6 . | |
134 | The value | |
135 | .B AF_UNSPEC | |
136 | indicates that | |
137 | .BR getaddrinfo () | |
138 | should return socket addresses for any address family | |
139 | (either IPv4 or IPv6, for example) that can be used with | |
140 | .I node | |
141 | and | |
142 | .IR service . | |
143 | .TP | |
fea681da | 144 | .I ai_socktype |
a3edd71d | 145 | This field specifies the preferred socket type, for example |
1ae6b2c7 | 146 | .B SOCK_STREAM |
fea681da | 147 | or |
a3edd71d MK |
148 | .BR SOCK_DGRAM . |
149 | Specifying 0 in this field indicates that socket addresses of any type | |
150 | can be returned by | |
151 | .BR getaddrinfo (). | |
152 | .TP | |
fea681da | 153 | .I ai_protocol |
a3edd71d MK |
154 | This field specifies the protocol for the returned socket addresses. |
155 | Specifying 0 in this field indicates that socket addresses with | |
156 | any protocol can be returned by | |
157 | .BR getaddrinfo (). | |
158 | .TP | |
fea681da | 159 | .I ai_flags |
a3edd71d | 160 | This field specifies additional options, described below. |
414ed40c | 161 | Multiple flags are specified by bitwise OR-ing them together. |
a3edd71d MK |
162 | .PP |
163 | All the other fields in the structure pointed to by | |
fea681da | 164 | .I hints |
b437fdd9 | 165 | must contain either 0 or a null pointer, as appropriate. |
bf68db18 | 166 | .PP |
0af804ac MK |
167 | Specifying |
168 | .I hints | |
169 | as NULL is equivalent to setting | |
170 | .I ai_socktype | |
171 | and | |
172 | .I ai_protocol | |
173 | to 0; | |
174 | .I ai_family | |
175 | to | |
176 | .BR AF_UNSPEC ; | |
177 | and | |
178 | .I ai_flags | |
179 | to | |
180 | .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" . | |
bf68db18 MK |
181 | (POSIX specifies different defaults for |
182 | .IR ai_flags ; | |
183 | see NOTES.) | |
fea681da MK |
184 | .I node |
185 | specifies either a numerical network address | |
a3edd71d MK |
186 | (for IPv4, numbers-and-dots notation as supported by |
187 | .BR inet_aton (3); | |
188 | for IPv6, hexadecimal string format as supported by | |
189 | .BR inet_pton (3)), | |
fea681da | 190 | or a network hostname, whose network addresses are looked up and resolved. |
8d18d6ed MK |
191 | If |
192 | .I hints.ai_flags | |
193 | contains the | |
fea681da | 194 | .B AI_NUMERICHOST |
4c3fac10 | 195 | flag, then |
fea681da | 196 | .I node |
a3edd71d | 197 | must be a numerical network address. |
fea681da MK |
198 | The |
199 | .B AI_NUMERICHOST | |
200 | flag suppresses any potentially lengthy network host address lookups. | |
201 | .PP | |
a3edd71d MK |
202 | If the |
203 | .B AI_PASSIVE | |
204 | flag is specified in | |
205 | .IR hints.ai_flags , | |
206 | and | |
207 | .I node | |
208 | is NULL, | |
209 | then the returned socket addresses will be suitable for | |
210 | .BR bind (2)ing | |
211 | a socket that will | |
212 | .BR accept (2) | |
213 | connections. | |
214 | The returned socket address will contain the "wildcard address" | |
215 | .RB ( INADDR_ANY | |
216 | for IPv4 addresses, | |
1ae6b2c7 | 217 | .B IN6ADDR_ANY_INIT |
a3edd71d MK |
218 | for IPv6 address). |
219 | The wildcard address is used by applications (typically servers) | |
40da0793 | 220 | that intend to accept connections on any of the host's network addresses. |
a3edd71d MK |
221 | If |
222 | .I node | |
223 | is not NULL, then the | |
20f81e4b | 224 | .B AI_PASSIVE |
a3edd71d MK |
225 | flag is ignored. |
226 | .PP | |
227 | If the | |
228 | .B AI_PASSIVE | |
229 | flag is not set in | |
230 | .IR hints.ai_flags , | |
231 | then the returned socket addresses will be suitable for use with | |
232 | .BR connect (2), | |
233 | .BR sendto (2), | |
234 | or | |
235 | .BR sendmsg (2). | |
236 | If | |
237 | .I node | |
238 | is NULL, | |
239 | then the network address will be set to the loopback interface address | |
240 | .RB ( INADDR_LOOPBACK | |
241 | for IPv4 addresses, | |
1ae6b2c7 | 242 | .B IN6ADDR_LOOPBACK_INIT |
a3edd71d MK |
243 | for IPv6 address); |
244 | this is used by applications that intend to communicate | |
245 | with peers running on the same host. | |
246 | .PP | |
247 | .I service | |
248 | sets the port in each returned address structure. | |
249 | If this argument is a service name (see | |
250 | .BR services (5)), | |
251 | it is translated to the corresponding port number. | |
252 | This argument can also be specified as a decimal number, | |
253 | which is simply converted to binary. | |
254 | If | |
255 | .I service | |
256 | is NULL, then the port number of the returned socket addresses | |
257 | will be left uninitialized. | |
258 | If | |
259 | .B AI_NUMERICSERV | |
260 | is specified in | |
261 | .I hints.ai_flags | |
262 | and | |
263 | .I service | |
264 | is not NULL, then | |
265 | .I service | |
266 | must point to a string containing a numeric port number. | |
267 | This flag is used to inhibit the invocation of a name resolution service | |
268 | in cases where it is known not to be required. | |
269 | .PP | |
270 | Either | |
271 | .I node | |
272 | or | |
273 | .IR service , | |
274 | but not both, may be NULL. | |
275 | .PP | |
fea681da | 276 | The |
2777b1ca | 277 | .BR getaddrinfo () |
a3edd71d | 278 | function allocates and initializes a linked list of |
8478ee02 | 279 | .I addrinfo |
a3edd71d MK |
280 | structures, one for each network address that matches |
281 | .I node | |
282 | and | |
283 | .IR service , | |
284 | subject to any restrictions imposed by | |
285 | .IR hints , | |
286 | and returns a pointer to the start of the list in | |
3cf81850 | 287 | .IR res . |
a3edd71d MK |
288 | The items in the linked list are linked by the |
289 | .I ai_next | |
290 | field. | |
847e0d88 | 291 | .PP |
a3edd71d MK |
292 | There are several reasons why |
293 | the linked list may have more than one | |
c13182ef | 294 | .I addrinfo |
ae03dc66 | 295 | structure, including: the network host is multihomed, accessible |
43f72e1b | 296 | over multiple protocols (e.g., both |
1ae6b2c7 | 297 | .B AF_INET |
00269a5a PB |
298 | and |
299 | .BR AF_INET6 ); | |
300 | or the same service is available from multiple socket types (one | |
a3edd71d MK |
301 | .B SOCK_STREAM |
302 | address and another | |
303 | .B SOCK_DGRAM | |
304 | address, for example). | |
00269a5a PB |
305 | Normally, the application should try |
306 | using the addresses in the order in which they are returned. | |
307 | The sorting function used within | |
308 | .BR getaddrinfo () | |
309 | is defined in RFC\ 3484; the order can be tweaked for a particular | |
310 | system by editing | |
1ae6b2c7 | 311 | .I /etc/gai.conf |
00269a5a | 312 | (available since glibc 2.5). |
a3edd71d MK |
313 | .PP |
314 | If | |
8d18d6ed | 315 | .I hints.ai_flags |
fea681da MK |
316 | includes the |
317 | .B AI_CANONNAME | |
a3edd71d MK |
318 | flag, then the |
319 | .I ai_canonname | |
320 | field of the first of the | |
321 | .I addrinfo | |
322 | structures in the returned list is set to point to the | |
323 | official name of the host. | |
c13182ef | 324 | .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo |
8194de33 | 325 | .\" structure was set pointing to the canonical name; that was |
c13182ef | 326 | .\" more than POSIX.1-2001 specified, or other implementations provided. |
8194de33 | 327 | .\" MTK, Aug 05 |
847e0d88 | 328 | .PP |
a3edd71d MK |
329 | The remaining fields of each returned |
330 | .I addrinfo | |
331 | structure are initialized as follows: | |
332 | .IP * 2 | |
333 | The | |
9d68eac8 | 334 | .IR ai_family , |
fea681da MK |
335 | .IR ai_socktype , |
336 | and | |
337 | .I ai_protocol | |
a3edd71d MK |
338 | fields return the socket creation parameters (i.e., these fields have |
339 | the same meaning as the corresponding arguments of | |
0af804ac | 340 | .BR socket (2)). |
a3edd71d MK |
341 | For example, |
342 | .I ai_family | |
343 | might return | |
344 | .B AF_INET | |
345 | or | |
346 | .BR AF_INET6 ; | |
347 | .I ai_socktype | |
348 | might return | |
349 | .B SOCK_DGRAM | |
350 | or | |
351 | .BR SOCK_STREAM ; | |
352 | and | |
353 | .I ai_protocol | |
354 | returns the protocol for the socket. | |
355 | .IP * | |
fea681da MK |
356 | A pointer to the socket address is placed in the |
357 | .I ai_addr | |
a3edd71d | 358 | field, and the length of the socket address, in bytes, |
fea681da MK |
359 | is placed in the |
360 | .I ai_addrlen | |
a3edd71d | 361 | field. |
fea681da | 362 | .PP |
8d18d6ed MK |
363 | If |
364 | .I hints.ai_flags | |
365 | includes the | |
366 | .B AI_ADDRCONFIG | |
367 | flag, then IPv4 addresses are returned in the list pointed to by | |
19f56c70 | 368 | .I res |
c13182ef | 369 | only if the local system has at least one |
33a0ccb2 MK |
370 | IPv4 address configured, and IPv6 addresses are returned |
371 | only if the local system has at least one IPv6 address configured. | |
712b0341 JMV |
372 | The loopback address is not considered for this case as valid |
373 | as a configured address. | |
2534ef15 MK |
374 | This flag is useful on, for example, |
375 | IPv4-only systems, to ensure that | |
376 | .BR getaddrinfo () | |
377 | does not return IPv6 socket addresses that would always fail in | |
378 | .BR connect (2) | |
379 | or | |
380 | .BR bind (2). | |
8d18d6ed MK |
381 | .PP |
382 | If | |
290e89bd | 383 | .I hints.ai_flags |
8d18d6ed MK |
384 | specifies the |
385 | .B AI_V4MAPPED | |
386 | flag, and | |
387 | .I hints.ai_family | |
388 | was specified as | |
389 | .BR AF_INET6 , | |
390 | and no matching IPv6 addresses could be found, | |
391 | then return IPv4-mapped IPv6 addresses in the list pointed to by | |
19f56c70 | 392 | .IR res . |
8d18d6ed MK |
393 | If both |
394 | .B AI_V4MAPPED | |
395 | and | |
396 | .B AI_ALL | |
397 | are specified in | |
af4a01eb | 398 | .IR hints.ai_flags , |
c13182ef | 399 | then return both IPv6 and IPv4-mapped IPv6 addresses |
8d18d6ed | 400 | in the list pointed to by |
19f56c70 | 401 | .IR res . |
8d18d6ed MK |
402 | .B AI_ALL |
403 | is ignored if | |
404 | .B AI_V4MAPPED | |
405 | is not also specified. | |
406 | .PP | |
fea681da | 407 | The |
2777b1ca | 408 | .BR freeaddrinfo () |
fea681da | 409 | function frees the memory that was allocated |
8194de33 | 410 | for the dynamically allocated linked list |
fea681da | 411 | .IR res . |
73d8cece | 412 | .SS Extensions to getaddrinfo() for Internationalized Domain Names |
22135cad | 413 | Starting with glibc 2.3.4, |
c13182ef MK |
414 | .BR getaddrinfo () |
415 | has been extended to selectively allow the incoming and outgoing | |
ddaec46d | 416 | hostnames to be transparently converted to and from the |
22135cad MK |
417 | Internationalized Domain Name (IDN) format (see RFC 3490, |
418 | .IR "Internationalizing Domain Names in Applications (IDNA)" ). | |
419 | Four new flags are defined: | |
420 | .TP | |
421 | .B AI_IDN | |
422 | If this flag is specified, then the node name given in | |
423 | .I node | |
424 | is converted to IDN format if necessary. | |
425 | The source encoding is that of the current locale. | |
847e0d88 | 426 | .IP |
c13182ef MK |
427 | If the input name contains non-ASCII characters, then the IDN encoding |
428 | is used. | |
22135cad | 429 | Those parts of the node name (delimited by dots) that contain |
c13182ef | 430 | non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) |
22135cad MK |
431 | before being passed to the name resolution functions. |
432 | .\" Implementation Detail: | |
433 | .\" To minimize effects on system performance the implementation might | |
434 | .\" want to check whether the input string contains any non-ASCII | |
435 | .\" characters. If there are none the IDN step can be skipped completely. | |
436 | .\" On systems which allow not-ASCII safe encodings for a locale this | |
437 | .\" might be a problem. | |
438 | .TP | |
439 | .B AI_CANONIDN | |
c13182ef MK |
440 | After a successful name lookup, and if the |
441 | .B AI_CANONNAME | |
22135cad MK |
442 | flag was specified, |
443 | .BR getaddrinfo () | |
444 | will return the canonical name of the | |
c13182ef MK |
445 | node corresponding to the |
446 | .I addrinfo | |
22135cad MK |
447 | structure value passed back. |
448 | The return value is an exact copy of the value returned by the name | |
449 | resolution function. | |
847e0d88 | 450 | .IP |
c13182ef | 451 | If the name is encoded using ACE, then it will contain the |
94e9d9fe | 452 | .I xn\-\- |
c13182ef MK |
453 | prefix for one or more components of the name. |
454 | To convert these components into a readable form the | |
455 | .B AI_CANONIDN | |
456 | flag can be passed in addition to | |
457 | .BR AI_CANONNAME . | |
22135cad MK |
458 | The resulting string is encoded using the current locale's encoding. |
459 | .\" | |
460 | .\"Implementation Detail: | |
94e9d9fe | 461 | .\"If no component of the returned name starts with xn\-\- the IDN |
22135cad MK |
462 | .\"step can be skipped, therefore avoiding unnecessary slowdowns. |
463 | .TP | |
464 | .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES | |
c13182ef | 465 | Setting these flags will enable the |
22135cad | 466 | IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and |
c13182ef | 467 | IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 |
ddaec46d | 468 | conforming hostname) |
22135cad | 469 | flags respectively to be used in the IDNA handling. |
47297adb | 470 | .SH RETURN VALUE |
d5da3c8d | 471 | .\" FIXME glibc defines the following additional errors, some which |
c13182ef | 472 | .\" can probably be returned by getaddrinfo(); they need to |
22135cad | 473 | .\" be documented. |
3747c614 MK |
474 | .\" #ifdef __USE_GNU |
475 | .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ | |
476 | .\" #define EAI_CANCELED -101 /* Request canceled. */ | |
477 | .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ | |
478 | .\" #define EAI_ALLDONE -103 /* All requests done. */ | |
479 | .\" #define EAI_INTR -104 /* Interrupted by a signal. */ | |
480 | .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ | |
481 | .\" #endif | |
2777b1ca | 482 | .BR getaddrinfo () |
c7094399 | 483 | returns 0 if it succeeds, or one of the following nonzero error codes: |
fea681da | 484 | .TP |
a0aa388d | 485 | .B EAI_ADDRFAMILY |
a3edd71d | 486 | .\" Not in SUSv3 |
a0aa388d MK |
487 | The specified network host does not have any network addresses in the |
488 | requested address family. | |
fea681da | 489 | .TP |
a0aa388d MK |
490 | .B EAI_AGAIN |
491 | The name server returned a temporary failure indication. | |
492 | Try again later. | |
fea681da MK |
493 | .TP |
494 | .B EAI_BADFLAGS | |
a87c4a1d MK |
495 | .I hints.ai_flags |
496 | contains invalid flags; or, | |
497 | .I hints.ai_flags | |
498 | included | |
499 | .B AI_CANONNAME | |
500 | and | |
501 | .I name | |
502 | was NULL. | |
fea681da | 503 | .TP |
a0aa388d MK |
504 | .B EAI_FAIL |
505 | The name server returned a permanent failure indication. | |
506 | .TP | |
507 | .B EAI_FAMILY | |
a3edd71d | 508 | The requested address family is not supported. |
a0aa388d MK |
509 | .TP |
510 | .B EAI_MEMORY | |
511 | Out of memory. | |
512 | .TP | |
513 | .B EAI_NODATA | |
a3edd71d | 514 | .\" Not in SUSv3 |
a0aa388d MK |
515 | The specified network host exists, but does not have any |
516 | network addresses defined. | |
517 | .TP | |
fea681da MK |
518 | .B EAI_NONAME |
519 | The | |
520 | .I node | |
521 | or | |
522 | .I service | |
8d18d6ed | 523 | is not known; or both |
fea681da MK |
524 | .I node |
525 | and | |
526 | .I service | |
8d18d6ed MK |
527 | are NULL; or |
528 | .B AI_NUMERICSERV | |
529 | was specified in | |
530 | .I hints.ai_flags | |
c13182ef | 531 | and |
8d18d6ed MK |
532 | .I service |
533 | was not a numeric port-number string. | |
fea681da MK |
534 | .TP |
535 | .B EAI_SERVICE | |
536 | The requested service is not available for the requested socket type. | |
537 | It may be available through another socket type. | |
a87c4a1d MK |
538 | For example, this error could occur if |
539 | .I service | |
33a0ccb2 | 540 | was "shell" (a service available only on stream sockets), and either |
a87c4a1d MK |
541 | .I hints.ai_protocol |
542 | was | |
543 | .BR IPPROTO_UDP , | |
544 | or | |
545 | .I hints.ai_socktype | |
546 | was | |
547 | .BR SOCK_DGRAM ; | |
548 | or the error could occur if | |
549 | .I service | |
550 | was not NULL, and | |
551 | .I hints.ai_socktype | |
552 | was | |
1ae6b2c7 | 553 | .B SOCK_RAW |
a87c4a1d | 554 | (a socket type that does not support the concept of services). |
fea681da | 555 | .TP |
a0aa388d | 556 | .B EAI_SOCKTYPE |
a3edd71d | 557 | The requested socket type is not supported. |
a87c4a1d MK |
558 | This could occur, for example, if |
559 | .I hints.ai_socktype | |
560 | and | |
561 | .I hints.ai_protocol | |
c5571b61 | 562 | are inconsistent (e.g., |
1ae6b2c7 | 563 | .B SOCK_DGRAM |
a87c4a1d MK |
564 | and |
565 | .BR IPPROTO_TCP , | |
add478c1 | 566 | respectively). |
fea681da MK |
567 | .TP |
568 | .B EAI_SYSTEM | |
fb745639 | 569 | Other system error; |
fea681da | 570 | .I errno |
fb745639 | 571 | is set to indicate the error. |
fea681da MK |
572 | .PP |
573 | The | |
2777b1ca | 574 | .BR gai_strerror () |
fea681da MK |
575 | function translates these error codes to a human readable string, |
576 | suitable for error reporting. | |
47297adb | 577 | .SH FILES |
00269a5a | 578 | .I /etc/gai.conf |
bb89d1ef ZL |
579 | .SH ATTRIBUTES |
580 | For an explanation of the terms used in this section, see | |
581 | .BR attributes (7). | |
c466875e MK |
582 | .ad l |
583 | .nh | |
bb89d1ef ZL |
584 | .TS |
585 | allbox; | |
c466875e | 586 | lbx lb lb |
bb89d1ef ZL |
587 | l l l. |
588 | Interface Attribute Value | |
589 | T{ | |
590 | .BR getaddrinfo () | |
591 | T} Thread safety MT-Safe env locale | |
592 | T{ | |
593 | .BR freeaddrinfo (), | |
594 | .BR gai_strerror () | |
595 | T} Thread safety MT-Safe | |
596 | .TE | |
c466875e MK |
597 | .hy |
598 | .ad | |
847e0d88 | 599 | .sp 1 |
47297adb | 600 | .SH CONFORMING TO |
d7abdfb6 | 601 | POSIX.1-2001, POSIX.1-2008. |
fea681da | 602 | The |
63aa9df0 | 603 | .BR getaddrinfo () |
331da7c3 | 604 | function is documented in RFC\ 2553. |
47297adb | 605 | .SH NOTES |
c783f237 MK |
606 | .BR getaddrinfo () |
607 | supports the | |
608 | .IB address % scope-id | |
609 | notation for specifying the IPv6 scope-ID. | |
847e0d88 | 610 | .PP |
8d18d6ed | 611 | .BR AI_ADDRCONFIG , |
d63f46e1 | 612 | .BR AI_ALL , |
8d18d6ed | 613 | and |
0daa9e92 | 614 | .B AI_V4MAPPED |
8d18d6ed | 615 | are available since glibc 2.3.3. |
0daa9e92 | 616 | .B AI_NUMERICSERV |
8d18d6ed | 617 | is available since glibc 2.3.4. |
847e0d88 | 618 | .PP |
d7abdfb6 MK |
619 | According to POSIX.1, specifying |
620 | .\" POSIX.1-2001, POSIX.1-2008 | |
f9d5775f MK |
621 | .I hints |
622 | as NULL should cause | |
623 | .I ai_flags | |
624 | to be assumed as 0. | |
625 | The GNU C library instead assumes a value of | |
1ae6b2c7 | 626 | .B (AI_V4MAPPED\~|\~AI_ADDRCONFIG) |
f9d5775f MK |
627 | for this case, |
628 | since this value is considered an improvement on the specification. | |
a14af333 | 629 | .SH EXAMPLES |
88a180b7 MK |
630 | .\" getnameinfo.3 refers to this example |
631 | .\" socket.2 refers to this example | |
632 | .\" bind.2 refers to this example | |
633 | .\" connect.2 refers to this example | |
634 | .\" recvfrom.2 refers to this example | |
635 | .\" sendto.2 refers to this example | |
35bf3cc8 MK |
636 | The following programs demonstrate the use of |
637 | .BR getaddrinfo (), | |
638 | .BR gai_strerror (), | |
639 | .BR freeaddrinfo (), | |
640 | and | |
641 | .BR getnameinfo (3). | |
642 | The programs are an echo server and client for UDP datagrams. | |
213bea67 | 643 | .SS Server program |
d84d0300 | 644 | \& |
207050fa | 645 | .EX |
988db661 | 646 | #include <sys/types.h> |
35bf3cc8 | 647 | #include <stdio.h> |
988db661 MK |
648 | #include <stdlib.h> |
649 | #include <unistd.h> | |
650 | #include <string.h> | |
651 | #include <sys/socket.h> | |
35bf3cc8 MK |
652 | #include <netdb.h> |
653 | ||
654 | #define BUF_SIZE 500 | |
655 | ||
656 | int | |
657 | main(int argc, char *argv[]) | |
658 | { | |
659 | struct addrinfo hints; | |
660 | struct addrinfo *result, *rp; | |
661 | int sfd, s; | |
662 | struct sockaddr_storage peer_addr; | |
663 | socklen_t peer_addr_len; | |
664 | ssize_t nread; | |
665 | char buf[BUF_SIZE]; | |
666 | ||
667 | if (argc != 2) { | |
d1a71985 | 668 | fprintf(stderr, "Usage: %s port\en", argv[0]); |
35bf3cc8 MK |
669 | exit(EXIT_FAILURE); |
670 | } | |
671 | ||
8e4dfb59 | 672 | memset(&hints, 0, sizeof(hints)); |
35bf3cc8 MK |
673 | hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ |
674 | hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ | |
675 | hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */ | |
676 | hints.ai_protocol = 0; /* Any protocol */ | |
59cef123 MK |
677 | hints.ai_canonname = NULL; |
678 | hints.ai_addr = NULL; | |
679 | hints.ai_next = NULL; | |
35bf3cc8 MK |
680 | |
681 | s = getaddrinfo(NULL, argv[1], &hints, &result); | |
682 | if (s != 0) { | |
d1a71985 | 683 | fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); |
35bf3cc8 MK |
684 | exit(EXIT_FAILURE); |
685 | } | |
686 | ||
687 | /* getaddrinfo() returns a list of address structures. | |
7a056410 | 688 | Try each address until we successfully bind(2). |
988db661 | 689 | If socket(2) (or bind(2)) fails, we (close the socket |
35bf3cc8 MK |
690 | and) try the next address. */ |
691 | ||
29059a65 | 692 | for (rp = result; rp != NULL; rp = rp\->ai_next) { |
988db661 | 693 | sfd = socket(rp\->ai_family, rp\->ai_socktype, |
29059a65 MK |
694 | rp\->ai_protocol); |
695 | if (sfd == \-1) | |
35bf3cc8 MK |
696 | continue; |
697 | ||
29059a65 | 698 | if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0) |
35bf3cc8 MK |
699 | break; /* Success */ |
700 | ||
701 | close(sfd); | |
702 | } | |
703 | ||
a23b0098 MH |
704 | freeaddrinfo(result); /* No longer needed */ |
705 | ||
35bf3cc8 | 706 | if (rp == NULL) { /* No address succeeded */ |
d1a71985 | 707 | fprintf(stderr, "Could not bind\en"); |
35bf3cc8 MK |
708 | exit(EXIT_FAILURE); |
709 | } | |
710 | ||
c6beb8a1 | 711 | /* Read datagrams and echo them back to sender. */ |
35bf3cc8 MK |
712 | |
713 | for (;;) { | |
facc3c56 | 714 | peer_addr_len = sizeof(peer_addr); |
988db661 | 715 | nread = recvfrom(sfd, buf, BUF_SIZE, 0, |
35bf3cc8 | 716 | (struct sockaddr *) &peer_addr, &peer_addr_len); |
29059a65 | 717 | if (nread == \-1) |
35bf3cc8 MK |
718 | continue; /* Ignore failed request */ |
719 | ||
720 | char host[NI_MAXHOST], service[NI_MAXSERV]; | |
988db661 MK |
721 | |
722 | s = getnameinfo((struct sockaddr *) &peer_addr, | |
35bf3cc8 MK |
723 | peer_addr_len, host, NI_MAXHOST, |
724 | service, NI_MAXSERV, NI_NUMERICSERV); | |
5df38b33 | 725 | if (s == 0) |
d1a71985 | 726 | printf("Received %zd bytes from %s:%s\en", |
8c5fcd21 | 727 | nread, host, service); |
35bf3cc8 | 728 | else |
d1a71985 | 729 | fprintf(stderr, "getnameinfo: %s\en", gai_strerror(s)); |
35bf3cc8 | 730 | |
988db661 | 731 | if (sendto(sfd, buf, nread, 0, |
35bf3cc8 | 732 | (struct sockaddr *) &peer_addr, |
988db661 | 733 | peer_addr_len) != nread) |
d1a71985 | 734 | fprintf(stderr, "Error sending response\en"); |
35bf3cc8 MK |
735 | } |
736 | } | |
207050fa | 737 | .EE |
213bea67 | 738 | .SS Client program |
1f79eca5 | 739 | \& |
207050fa | 740 | .EX |
988db661 | 741 | #include <sys/types.h> |
35bf3cc8 MK |
742 | #include <sys/socket.h> |
743 | #include <netdb.h> | |
744 | #include <stdio.h> | |
988db661 MK |
745 | #include <stdlib.h> |
746 | #include <unistd.h> | |
747 | #include <string.h> | |
35bf3cc8 MK |
748 | |
749 | #define BUF_SIZE 500 | |
750 | ||
751 | int | |
752 | main(int argc, char *argv[]) | |
753 | { | |
754 | struct addrinfo hints; | |
755 | struct addrinfo *result, *rp; | |
88893a77 | 756 | int sfd, s; |
35bf3cc8 MK |
757 | size_t len; |
758 | ssize_t nread; | |
759 | char buf[BUF_SIZE]; | |
760 | ||
761 | if (argc < 3) { | |
d1a71985 | 762 | fprintf(stderr, "Usage: %s host port msg...\en", argv[0]); |
35bf3cc8 MK |
763 | exit(EXIT_FAILURE); |
764 | } | |
765 | ||
c6beb8a1 | 766 | /* Obtain address(es) matching host/port. */ |
35bf3cc8 | 767 | |
8e4dfb59 | 768 | memset(&hints, 0, sizeof(hints)); |
35bf3cc8 MK |
769 | hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ |
770 | hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ | |
771 | hints.ai_flags = 0; | |
772 | hints.ai_protocol = 0; /* Any protocol */ | |
773 | ||
774 | s = getaddrinfo(argv[1], argv[2], &hints, &result); | |
775 | if (s != 0) { | |
d1a71985 | 776 | fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); |
35bf3cc8 MK |
777 | exit(EXIT_FAILURE); |
778 | } | |
779 | ||
780 | /* getaddrinfo() returns a list of address structures. | |
7a056410 MK |
781 | Try each address until we successfully connect(2). |
782 | If socket(2) (or connect(2)) fails, we (close the socket | |
35bf3cc8 MK |
783 | and) try the next address. */ |
784 | ||
29059a65 | 785 | for (rp = result; rp != NULL; rp = rp\->ai_next) { |
988db661 | 786 | sfd = socket(rp\->ai_family, rp\->ai_socktype, |
29059a65 MK |
787 | rp\->ai_protocol); |
788 | if (sfd == \-1) | |
35bf3cc8 | 789 | continue; |
988db661 | 790 | |
29059a65 | 791 | if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1) |
35bf3cc8 MK |
792 | break; /* Success */ |
793 | ||
794 | close(sfd); | |
795 | } | |
796 | ||
a23b0098 MH |
797 | freeaddrinfo(result); /* No longer needed */ |
798 | ||
35bf3cc8 | 799 | if (rp == NULL) { /* No address succeeded */ |
d1a71985 | 800 | fprintf(stderr, "Could not connect\en"); |
35bf3cc8 MK |
801 | exit(EXIT_FAILURE); |
802 | } | |
803 | ||
988db661 | 804 | /* Send remaining command\-line arguments as separate |
c6beb8a1 | 805 | datagrams, and read responses from server. */ |
35bf3cc8 | 806 | |
88893a77 | 807 | for (int j = 3; j < argc; j++) { |
988db661 | 808 | len = strlen(argv[j]) + 1; |
35bf3cc8 MK |
809 | /* +1 for terminating null byte */ |
810 | ||
1605ddac | 811 | if (len > BUF_SIZE) { |
988db661 | 812 | fprintf(stderr, |
d1a71985 | 813 | "Ignoring long message in argument %d\en", j); |
35bf3cc8 MK |
814 | continue; |
815 | } | |
816 | ||
817 | if (write(sfd, argv[j], len) != len) { | |
d1a71985 | 818 | fprintf(stderr, "partial/failed write\en"); |
35bf3cc8 MK |
819 | exit(EXIT_FAILURE); |
820 | } | |
988db661 | 821 | |
35bf3cc8 | 822 | nread = read(sfd, buf, BUF_SIZE); |
29059a65 | 823 | if (nread == \-1) { |
35bf3cc8 MK |
824 | perror("read"); |
825 | exit(EXIT_FAILURE); | |
826 | } | |
827 | ||
d1a71985 | 828 | printf("Received %zd bytes: %s\en", nread, buf); |
35bf3cc8 MK |
829 | } |
830 | ||
831 | exit(EXIT_SUCCESS); | |
832 | } | |
207050fa | 833 | .EE |
47297adb | 834 | .SH SEE ALSO |
823ecd0c | 835 | .\" .BR getipnodebyaddr (3), |
ac5e6a36 | 836 | .\" .BR getipnodebyname (3), |
b27b1153 | 837 | .BR getaddrinfo_a (3), |
a3edd71d | 838 | .BR gethostbyname (3), |
60435a75 | 839 | .BR getnameinfo (3), |
a3edd71d | 840 | .BR inet (3), |
625526ef | 841 | .BR gai.conf (5), |
a3edd71d MK |
842 | .BR hostname (7), |
843 | .BR ip (7) |