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