]>
Commit | Line | Data |
---|---|---|
5b2abdfb A |
1 | .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.17 2001/10/01 16:08:55 ru Exp $ |
2 | .\" $KAME: getaddrinfo.3,v 1.22 2000/08/09 21:16:17 itojun Exp $ | |
3 | .\" | |
4 | .\" Copyright (c) 1983, 1987, 1991, 1993 | |
5 | .\" The Regents of the University of California. All rights reserved. | |
6 | .\" | |
7 | .\" Redistribution and use in source and binary forms, with or without | |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
22 | .\" | |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
34 | .\" | |
35 | .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 | |
36 | .\" | |
37 | .Dd May 25, 1995 | |
38 | .Dt GETADDRINFO 3 | |
39 | .Os | |
40 | .\" | |
41 | .Sh NAME | |
42 | .Nm getaddrinfo , | |
43 | .Nm freeaddrinfo , | |
44 | .Nm gai_strerror | |
45 | .Nd nodename-to-address translation in protocol-independent manner | |
46 | .\" | |
47 | .Sh LIBRARY | |
48 | .Lb libc | |
49 | .Sh SYNOPSIS | |
50 | .In sys/types.h | |
51 | .In sys/socket.h | |
52 | .In netdb.h | |
53 | .Ft int | |
54 | .Fn getaddrinfo "const char *nodename" "const char *servname" \ | |
55 | "const struct addrinfo *hints" "struct addrinfo **res" | |
56 | .Ft void | |
57 | .Fn freeaddrinfo "struct addrinfo *ai" | |
58 | .Ft "char *" | |
59 | .Fn gai_strerror "int ecode" | |
60 | .\" | |
61 | .Sh DESCRIPTION | |
62 | The | |
63 | .Fn getaddrinfo | |
64 | function is defined for protocol-independent nodename-to-address translation. | |
65 | It performs the functionality of | |
66 | .Xr gethostbyname 3 | |
67 | and | |
68 | .Xr getservbyname 3 , | |
69 | but in a more sophisticated manner. | |
70 | .Pp | |
71 | The | |
72 | .Li addrinfo | |
73 | structure is defined as a result of including the | |
74 | .Aq Pa netdb.h | |
75 | header: | |
76 | .Bd -literal -offset | |
77 | struct addrinfo { | |
78 | int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ | |
79 | int ai_family; /* PF_xxx */ | |
80 | int ai_socktype; /* SOCK_xxx */ | |
81 | int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ | |
82 | size_t ai_addrlen; /* length of ai_addr */ | |
83 | char *ai_canonname; /* canonical name for nodename */ | |
84 | struct sockaddr *ai_addr; /* binary address */ | |
85 | struct addrinfo *ai_next; /* next structure in linked list */ | |
86 | }; | |
87 | .Ed | |
88 | .Pp | |
89 | The | |
90 | .Fa nodename | |
91 | and | |
92 | .Fa servname | |
93 | arguments are pointers to null-terminated strings or | |
94 | .Dv NULL . | |
95 | One or both of these two arguments must be a | |
96 | .Pf non Dv -NULL | |
97 | pointer. | |
98 | In the normal client scenario, both the | |
99 | .Fa nodename | |
100 | and | |
101 | .Fa servname | |
102 | are specified. | |
103 | In the normal server scenario, only the | |
104 | .Fa servname | |
105 | is specified. | |
106 | A | |
107 | .Pf non Dv -NULL | |
108 | .Fa nodename | |
109 | string can be either a node name or a numeric host address string | |
110 | (i.e., a dotted-decimal IPv4 address or an IPv6 hex address). | |
111 | A | |
112 | .Pf non Dv -NULL | |
113 | .Fa servname | |
114 | string can be either a service name or a decimal port number. | |
115 | .Pp | |
116 | The caller can optionally pass an | |
117 | .Li addrinfo | |
118 | structure, pointed to by the third argument, | |
119 | to provide hints concerning the type of socket that the caller supports. | |
120 | In this | |
121 | .Fa hints | |
122 | structure all members other than | |
123 | .Fa ai_flags , | |
124 | .Fa ai_family , | |
125 | .Fa ai_socktype , | |
126 | and | |
127 | .Fa ai_protocol | |
128 | must be zero or a | |
129 | .Dv NULL | |
130 | pointer. | |
131 | A value of | |
132 | .Dv PF_UNSPEC | |
133 | for | |
134 | .Fa ai_family | |
135 | means the caller will accept any protocol family. | |
136 | A value of 0 for | |
137 | .Fa ai_socktype | |
138 | means the caller will accept any socket type. | |
139 | A value of 0 for | |
140 | .Fa ai_protocol | |
141 | means the caller will accept any protocol. | |
142 | For example, if the caller handles only TCP and not UDP, then the | |
143 | .Fa ai_socktype | |
144 | member of the hints structure should be set to | |
145 | .Dv SOCK_STREAM | |
146 | when | |
147 | .Fn getaddrinfo | |
148 | is called. | |
149 | If the caller handles only IPv4 and not IPv6, then the | |
150 | .Fa ai_family | |
151 | member of the | |
152 | .Fa hints | |
153 | structure should be set to | |
154 | .Dv PF_INET | |
155 | when | |
156 | .Fn getaddrinfo | |
157 | is called. | |
158 | If the third argument to | |
159 | .Fn getaddrinfo | |
160 | is a | |
161 | .Dv NULL | |
162 | pointer, this is the same as if the caller had filled in an | |
163 | .Li addrinfo | |
164 | structure initialized to zero with | |
165 | .Fa ai_family | |
166 | set to | |
167 | .Dv PF_UNSPEC . | |
168 | .Pp | |
169 | Upon successful return a pointer to a linked list of one or more | |
170 | .Li addrinfo | |
171 | structures is returned through the final argument. | |
172 | The caller can process each | |
173 | .Li addrinfo | |
174 | structure in this list by following the | |
175 | .Fa ai_next | |
176 | pointer, until a | |
177 | .Dv NULL | |
178 | pointer is encountered. | |
179 | In each returned | |
180 | .Li addrinfo | |
181 | structure the three members | |
182 | .Fa ai_family , | |
183 | .Fa ai_socktype , | |
184 | and | |
185 | .Fa ai_protocol | |
186 | are the corresponding arguments for a call to the | |
187 | .Fn socket | |
188 | function. | |
189 | In each | |
190 | .Li addrinfo | |
191 | structure the | |
192 | .Fa ai_addr | |
193 | member points to a filled-in socket address structure whose length is | |
194 | specified by the | |
195 | .Fa ai_addrlen | |
196 | member. | |
197 | .Pp | |
198 | If the | |
199 | .Dv AI_PASSIVE | |
200 | bit is set in the | |
201 | .Fa ai_flags | |
202 | member of the | |
203 | .Fa hints | |
204 | structure, then the caller plans to use the returned socket address | |
205 | structure in a call to | |
206 | .Fn bind . | |
207 | In this case, if the | |
208 | .Fa nodename | |
209 | argument is a | |
210 | .Dv NULL | |
211 | pointer, then the IP address portion of the socket | |
212 | address structure will be set to | |
213 | .Dv INADDR_ANY | |
214 | for an IPv4 address or | |
215 | .Dv IN6ADDR_ANY_INIT | |
216 | for an IPv6 address. | |
217 | .Pp | |
218 | If the | |
219 | .Dv AI_PASSIVE | |
220 | bit is not set in the | |
221 | .Fa ai_flags | |
222 | member of the | |
223 | .Fa hints | |
224 | structure, then the returned socket address structure will be ready for a | |
225 | call to | |
226 | .Fn connect | |
227 | (for a connection-oriented protocol) | |
228 | or either | |
229 | .Fn connect , | |
230 | .Fn sendto , | |
231 | or | |
232 | .Fn sendmsg | |
233 | (for a connectionless protocol). | |
234 | In this case, if the | |
235 | .Fa nodename | |
236 | argument is a | |
237 | .Dv NULL | |
238 | pointer, then the IP address portion of the | |
239 | socket address structure will be set to the loopback address. | |
240 | .Pp | |
241 | If the | |
242 | .Dv AI_CANONNAME | |
243 | bit is set in the | |
244 | .Fa ai_flags | |
245 | member of the | |
246 | .Fa hints | |
247 | structure, then upon successful return the | |
248 | .Fa ai_canonname | |
249 | member of the first | |
250 | .Li addrinfo | |
251 | structure in the linked list will point to a null-terminated string | |
252 | containing the canonical name of the specified | |
253 | .Fa nodename . | |
254 | .Pp | |
255 | If the | |
256 | .Dv AI_NUMERICHOST | |
257 | bit is set in the | |
258 | .Fa ai_flags | |
259 | member of the | |
260 | .Fa hints | |
261 | structure, then a | |
262 | .Pf non Dv -NULL | |
263 | .Fa nodename | |
264 | string must be a numeric host address string. | |
265 | Otherwise an error of | |
266 | .Dv EAI_NONAME | |
267 | is returned. | |
268 | This flag prevents any type of name resolution service (e.g., the DNS) | |
269 | from being called. | |
270 | .Pp | |
271 | The arguments to | |
272 | .Fn getaddrinfo | |
273 | must be sufficiently consistent and unambiguous. | |
274 | Here are some problem cases you may encounter: | |
275 | .Bl -bullet | |
276 | .It | |
277 | .Fn getaddrinfo | |
278 | will fail if the members in the | |
279 | .Fa hints | |
280 | structure are not consistent. | |
281 | For example, for internet address families, | |
282 | .Fn getaddrinfo | |
283 | will fail if you specify | |
284 | .Dv SOCK_STREAM | |
285 | to | |
286 | .Fa ai_socktype | |
287 | while you specify | |
288 | .Dv IPPROTO_UDP | |
289 | to | |
290 | .Fa ai_protocol . | |
291 | .It | |
292 | If you specify a | |
293 | .Fa servname | |
294 | which is defined only for certain | |
295 | .Fa ai_socktype , | |
296 | .Fn getaddrinfo | |
297 | will fail because the arguments are not consistent. | |
298 | For example, | |
299 | .Fn getaddrinfo | |
300 | will return an error if you ask for | |
301 | .Dq Li tftp | |
302 | service on | |
303 | .Dv SOCK_STREAM . | |
304 | .It | |
305 | For internet address families, if you specify | |
306 | .Fa servname | |
307 | while you set | |
308 | .Fa ai_socktype | |
309 | to | |
310 | .Dv SOCK_RAW , | |
311 | .Fn getaddrinfo | |
312 | will fail, because service names are not defined for the internet | |
313 | .Dv SOCK_RAW | |
314 | space. | |
315 | .It | |
316 | If you specify numeric | |
317 | .Fa servname , | |
318 | while leaving | |
319 | .Fa ai_socktype | |
320 | and | |
321 | .Fa ai_protocol | |
322 | unspecified, | |
323 | .Fn getaddrinfo | |
324 | will fail. | |
325 | This is because the numeric | |
326 | .Fa servname | |
327 | does not identify any socket type, and | |
328 | .Fn getaddrinfo | |
329 | is not allowed to glob the argument in such case. | |
330 | .El | |
331 | .Pp | |
332 | All of the information returned by | |
333 | .Fn getaddrinfo | |
334 | is dynamically allocated: | |
335 | the | |
336 | .Li addrinfo | |
337 | structures, the socket address structures, and canonical node name | |
338 | strings pointed to by the addrinfo structures. | |
339 | To return this information to the system the function | |
340 | .Fn freeaddrinfo | |
341 | is called. | |
342 | The | |
343 | .Fa addrinfo | |
344 | structure pointed to by the | |
345 | .Fa ai argument | |
346 | is freed, along with any dynamic storage pointed to by the structure. | |
347 | This operation is repeated until a | |
348 | .Dv NULL | |
349 | .Fa ai_next | |
350 | pointer is encountered. | |
351 | .Pp | |
352 | To aid applications in printing error messages based on the | |
353 | .Dv EAI_xxx | |
354 | codes returned by | |
355 | .Fn getaddrinfo , | |
356 | .Fn gai_strerror | |
357 | is defined. | |
358 | The argument is one of the | |
359 | .Dv EAI_xxx | |
360 | values defined earlier and the return value points to a string describing | |
361 | the error. | |
362 | If the argument is not one of the | |
363 | .Dv EAI_xxx | |
364 | values, the function still returns a pointer to a string whose contents | |
365 | indicate an unknown error. | |
366 | .\" | |
367 | .Sh EXTENSIONS | |
368 | This implementation supports numeric IPv6 address notation with the | |
369 | experimental scope identifier. | |
370 | By appending a percent sign and scope identifier to the address, you | |
371 | can specify the value of the | |
372 | .Li sin6_scope_id | |
373 | field of the socket address. | |
374 | This makes management of scoped address easier, | |
375 | and allows cut-and-paste input of scoped addresses. | |
376 | .Pp | |
377 | At the moment the code supports only link-local addresses in this format. | |
378 | The scope identifier is hardcoded to name of hardware interface associated | |
379 | with the link, | |
380 | (such as | |
381 | .Li ne0 ) . | |
382 | For example, | |
383 | .Dq Li fe80::1%ne0 , | |
384 | which means | |
385 | .Do | |
386 | .Li fe80::1 | |
387 | on the link associated with the | |
388 | .Li ne0 | |
389 | interface | |
390 | .Dc . | |
391 | .Pp | |
392 | This implementation is still very experimental and non-standard. | |
393 | The current implementation assumes a one-to-one relationship between | |
394 | interfaces and links, which is not necessarily true according to the | |
395 | specification. | |
396 | .\" | |
397 | .Sh EXAMPLES | |
398 | The following code tries to connect to | |
399 | .Dq Li www.kame.net | |
400 | service | |
401 | .Dq Li http . | |
402 | via stream socket. | |
403 | It loops through all the addresses available, regardless of the address family. | |
404 | If the destination resolves to an IPv4 address, it will use an | |
405 | .Dv AF_INET | |
406 | socket. | |
407 | Similarly, if it resolves to IPv6, an | |
408 | .Dv AF_INET6 | |
409 | socket is used. | |
410 | Observe that there is no hardcoded reference to particular address family. | |
411 | The code works even if | |
412 | .Fn getaddrinfo | |
413 | returns addresses that are not IPv4/v6. | |
414 | .Bd -literal -offset indent | |
415 | struct addrinfo hints, *res, *res0; | |
416 | int error; | |
417 | int s; | |
418 | const char *cause = NULL; | |
419 | ||
420 | memset(&hints, 0, sizeof(hints)); | |
421 | hints.ai_family = PF_UNSPEC; | |
422 | hints.ai_socktype = SOCK_STREAM; | |
423 | error = getaddrinfo("www.kame.net", "http", &hints, &res0); | |
424 | if (error) { | |
425 | errx(1, "%s", gai_strerror(error)); | |
426 | /*NOTREACHED*/ | |
427 | } | |
428 | s = -1; | |
429 | cause = "no addresses"; | |
430 | errno = EADDRNOTAVAIL; | |
431 | for (res = res0; res; res = res->ai_next) { | |
432 | s = socket(res->ai_family, res->ai_socktype, | |
433 | res->ai_protocol); | |
434 | if (s < 0) { | |
435 | cause = "socket"; | |
436 | continue; | |
437 | } | |
438 | ||
439 | if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { | |
440 | cause = "connect"; | |
441 | close(s); | |
442 | s = -1; | |
443 | continue; | |
444 | } | |
445 | ||
446 | break; /* okay we got one */ | |
447 | } | |
448 | if (s < 0) { | |
449 | err(1, cause); | |
450 | /*NOTREACHED*/ | |
451 | } | |
452 | freeaddrinfo(res0); | |
453 | .Ed | |
454 | .Pp | |
455 | The following example tries to open a wildcard listening socket onto service | |
456 | .Dq Li http , | |
457 | for all the address families available. | |
458 | .Bd -literal -offset indent | |
459 | struct addrinfo hints, *res, *res0; | |
460 | int error; | |
461 | int s[MAXSOCK]; | |
462 | int nsock; | |
463 | const char *cause = NULL; | |
464 | ||
465 | memset(&hints, 0, sizeof(hints)); | |
466 | hints.ai_family = PF_UNSPEC; | |
467 | hints.ai_socktype = SOCK_STREAM; | |
468 | hints.ai_flags = AI_PASSIVE; | |
469 | error = getaddrinfo(NULL, "http", &hints, &res0); | |
470 | if (error) { | |
471 | errx(1, "%s", gai_strerror(error)); | |
472 | /*NOTREACHED*/ | |
473 | } | |
474 | nsock = 0; | |
475 | for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { | |
476 | s[nsock] = socket(res->ai_family, res->ai_socktype, | |
477 | res->ai_protocol); | |
478 | if (s[nsock] < 0) { | |
479 | cause = "socket"; | |
480 | continue; | |
481 | } | |
482 | ||
483 | if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { | |
484 | cause = "bind"; | |
485 | close(s[nsock]); | |
486 | continue; | |
487 | } | |
488 | ||
489 | if (listen(s[nsock], SOMAXCONN) < 0) { | |
490 | cause = "listen"; | |
491 | close(s[nsock]); | |
492 | continue; | |
493 | } | |
494 | ||
495 | nsock++; | |
496 | } | |
497 | if (nsock == 0) { | |
498 | err(1, cause); | |
499 | /*NOTREACHED*/ | |
500 | } | |
501 | freeaddrinfo(res0); | |
502 | .Ed | |
503 | .\" | |
504 | .Sh FILES | |
505 | .Bl -tag -width /etc/nsswitch.conf -compact | |
506 | .It Pa /etc/hosts | |
507 | .It Pa /etc/nsswitch.conf | |
508 | .It Pa /etc/resolv.conf | |
509 | .El | |
510 | .\" | |
511 | .Sh DIAGNOSTICS | |
512 | Error return status from | |
513 | .Fn getaddrinfo | |
514 | is zero on success and non-zero on errors. | |
515 | Non-zero error codes are defined in | |
516 | .Aq Pa netdb.h , | |
517 | and as follows: | |
518 | .Pp | |
519 | .Bl -tag -width EAI_ADDRFAMILY -compact | |
520 | .It Dv EAI_ADDRFAMILY | |
521 | Address family for | |
522 | .Fa nodename | |
523 | not supported. | |
524 | .It Dv EAI_AGAIN | |
525 | Temporary failure in name resolution. | |
526 | .It Dv EAI_BADFLAGS | |
527 | Invalid value for | |
528 | .Fa ai_flags . | |
529 | .It Dv EAI_FAIL | |
530 | Non-recoverable failure in name resolution. | |
531 | .It Dv EAI_FAMILY | |
532 | .Fa ai_family | |
533 | not supported. | |
534 | .It Dv EAI_MEMORY | |
535 | Memory allocation failure. | |
536 | .It Dv EAI_NODATA | |
537 | No address associated with | |
538 | .Fa nodename . | |
539 | .It Dv EAI_NONAME | |
540 | .Fa nodename | |
541 | nor | |
542 | .Fa servname | |
543 | provided, or not known. | |
544 | .It Dv EAI_SERVICE | |
545 | .Fa servname | |
546 | not supported for | |
547 | .Fa ai_socktype . | |
548 | .It Dv EAI_SOCKTYPE | |
549 | .Fa ai_socktype | |
550 | not supported. | |
551 | .It Dv EAI_SYSTEM | |
552 | System error returned in | |
553 | .Va errno . | |
554 | .It Dv EAI_BADHINTS | |
555 | Invalid value for | |
556 | .Fa hints . | |
557 | .It Dv EAI_PROTOCOL | |
558 | Resolved protocol is unknown. | |
559 | .It Dv EAI_MAX | |
560 | Unknown error. | |
561 | .El | |
562 | .Pp | |
563 | If called with an appropriate argument, | |
564 | .Fn gai_strerror | |
565 | returns a pointer to a string describing the given error code. | |
566 | If the argument is not one of the | |
567 | .Dv EAI_xxx | |
568 | values, the function still returns a pointer to a string whose contents | |
569 | indicate an unknown error. | |
570 | .\" | |
571 | .Sh SEE ALSO | |
572 | .Xr gethostbyname 3 , | |
573 | .Xr getnameinfo 3 , | |
574 | .Xr getservbyname 3 , | |
575 | .Xr hosts 5 , | |
576 | .Xr services 5 , | |
577 | .Xr hostname 7 , | |
578 | .Xr named 8 | |
579 | .Pp | |
580 | .Rs | |
581 | .%A R. Gilligan | |
582 | .%A S. Thomson | |
583 | .%A J. Bound | |
584 | .%A W. Stevens | |
585 | .%T Basic Socket Interface Extensions for IPv6 | |
586 | .%R RFC2553 | |
587 | .%D March 1999 | |
588 | .Re | |
589 | .Rs | |
590 | .%A Tatsuya Jinmei | |
591 | .%A Atsushi Onoe | |
592 | .%T "An Extension of Format for IPv6 Scoped Addresses" | |
593 | .%R internet draft | |
594 | .%N draft-ietf-ipngwg-scopedaddr-format-02.txt | |
595 | .%O work in progress material | |
596 | .Re | |
597 | .Rs | |
598 | .%A Craig Metz | |
599 | .%T Protocol Independence Using the Sockets API | |
600 | .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" | |
601 | .%D June 2000 | |
602 | .Re | |
603 | .\" | |
604 | .Sh HISTORY | |
605 | The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. | |
606 | .\" | |
607 | .Sh STANDARDS | |
608 | The | |
609 | .Fn getaddrinfo | |
610 | function is defined in | |
611 | .St -p1003.1g-2000 , | |
612 | and documented in | |
613 | .Dq Basic Socket Interface Extensions for IPv6 | |
614 | (RFC2553). | |
615 | .\" | |
616 | .Sh BUGS | |
617 | The current implementation is not thread-safe. | |
618 | .Pp | |
619 | The text was shamelessly copied from RFC2553. |