diff options
author | itojun <> | 2000-01-17 08:16:58 +0000 |
---|---|---|
committer | itojun <> | 2000-01-17 08:16:58 +0000 |
commit | 2bfc7e66c2e632f418c7896053db7d24d893e473 (patch) | |
tree | 0c113eaa5f183d2778cbc68b9cd6f926d528eae6 /src/lib/libc/net/getaddrinfo.3 | |
parent | 10703049627aeae9e576798dac91d9f903cf661b (diff) | |
download | openbsd-2bfc7e66c2e632f418c7896053db7d24d893e473.tar.gz openbsd-2bfc7e66c2e632f418c7896053db7d24d893e473.tar.bz2 openbsd-2bfc7e66c2e632f418c7896053db7d24d893e473.zip |
sync with latest KAME version. now includes description on scoped addr
extension. add examples (good enough? >deraadt)
Diffstat (limited to 'src/lib/libc/net/getaddrinfo.3')
-rw-r--r-- | src/lib/libc/net/getaddrinfo.3 | 164 |
1 files changed, 160 insertions, 4 deletions
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3 index a3855a7c55..35a8ae0d38 100644 --- a/src/lib/libc/net/getaddrinfo.3 +++ b/src/lib/libc/net/getaddrinfo.3 | |||
@@ -1,4 +1,5 @@ | |||
1 | .\" $OpenBSD: getaddrinfo.3,v 1.4 2000/01/06 22:00:17 deraadt Exp $ | 1 | .\" $OpenBSD: getaddrinfo.3,v 1.5 2000/01/17 08:16:58 itojun Exp $ |
2 | .\" | ||
2 | .\" Copyright (c) 1983, 1987, 1991, 1993 | 3 | .\" Copyright (c) 1983, 1987, 1991, 1993 |
3 | .\" The Regents of the University of California. All rights reserved. | 4 | .\" The Regents of the University of California. All rights reserved. |
4 | .\" | 5 | .\" |
@@ -31,16 +32,18 @@ | |||
31 | .\" SUCH DAMAGE. | 32 | .\" SUCH DAMAGE. |
32 | .\" | 33 | .\" |
33 | .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 | 34 | .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 |
34 | .\" $Id: getaddrinfo.3,v 1.4 2000/01/06 22:00:17 deraadt Exp $ | 35 | .\" KAME Id: getaddrinfo.3,v 1.8 2000/01/17 08:13:03 itojun Exp |
35 | .\" | 36 | .\" |
36 | .Dd May 25, 1995 | 37 | .Dd May 25, 1995 |
37 | .Dt GETADDRINFO 3 | 38 | .Dt GETADDRINFO 3 |
38 | .Os | 39 | .Os |
40 | .\" | ||
39 | .Sh NAME | 41 | .Sh NAME |
40 | .Nm getaddrinfo , | 42 | .Nm getaddrinfo , |
41 | .Nm freeaddrinfo , | 43 | .Nm freeaddrinfo , |
42 | .Nm gai_strerror | 44 | .Nm gai_strerror |
43 | .Nd nodename-to-address translation in protocol-independent manner | 45 | .Nd nodename-to-address translation in protocol-independent manner |
46 | .\" | ||
44 | .Sh SYNOPSIS | 47 | .Sh SYNOPSIS |
45 | .Fd #include <sys/types.h> | 48 | .Fd #include <sys/types.h> |
46 | .Fd #include <sys/socket.h> | 49 | .Fd #include <sys/socket.h> |
@@ -52,6 +55,7 @@ | |||
52 | .Fn freeaddrinfo "struct addrinfo *ai" | 55 | .Fn freeaddrinfo "struct addrinfo *ai" |
53 | .Ft "char *" | 56 | .Ft "char *" |
54 | .Fn gai_strerror "int ecode" | 57 | .Fn gai_strerror "int ecode" |
58 | .\" | ||
55 | .Sh DESCRIPTION | 59 | .Sh DESCRIPTION |
56 | The | 60 | The |
57 | .Fn getaddrinfo | 61 | .Fn getaddrinfo |
@@ -281,12 +285,143 @@ If the argument is not one of the | |||
281 | .Dv EAI_xxx | 285 | .Dv EAI_xxx |
282 | values, the function still returns a pointer to a string whose contents | 286 | values, the function still returns a pointer to a string whose contents |
283 | indicate an unknown error. | 287 | indicate an unknown error. |
288 | .\" | ||
289 | .Sh EXTENSION | ||
290 | The implementation allows experimental numeric IPv6 address notation with | ||
291 | scope identifier. | ||
292 | By appending atmark and scope identifier to addresses, you can fill | ||
293 | .Li sin6_scope_id | ||
294 | field for addresses. | ||
295 | This would make management of scoped address easier, | ||
296 | and allows cut-and-paste input of scoped address. | ||
297 | .Pp | ||
298 | At this moment the code supports only link-local addresses with the format. | ||
299 | Scope identifier is hardcoded to name of hardware interface associated | ||
300 | with the link. | ||
301 | .Po | ||
302 | such as | ||
303 | .Li ne0 | ||
304 | .Pc . | ||
305 | Example would be like | ||
306 | .Dq Li fe80::1@ne0 , | ||
307 | which means | ||
308 | .Do | ||
309 | .Li fe80::1 | ||
310 | on the link associated with | ||
311 | .Li ne0 | ||
312 | interface | ||
313 | .Dc . | ||
314 | .Pp | ||
315 | The implementation is still very experimental and non-standard. | ||
316 | The current implementation assumes one-by-one relationship between | ||
317 | interface and link, which is not necessarily true from the specification. | ||
318 | .\" | ||
319 | .Sh EXAMPLES | ||
320 | The following code tries to connect to | ||
321 | .Dq Li www.kame.net | ||
322 | service | ||
323 | .Dq Li http . | ||
324 | via stream socket. | ||
325 | It loops through all the addresses available, regardless from address family. | ||
326 | If the destination resolves to IPv4 address, it will use | ||
327 | .Dv AF_INET | ||
328 | socket. | ||
329 | Similarly, if it resolves to IPv6, | ||
330 | .Dv AF_INET6 | ||
331 | socket is used. | ||
332 | Observe that there is no hardcoded reference to particular address family. | ||
333 | The code works even if | ||
334 | .Nm getaddrinfo | ||
335 | returns addresses that are not IPv4/v6. | ||
336 | .Bd -literal -offset indent | ||
337 | struct addrinfo hints, *res, *res0; | ||
338 | int error; | ||
339 | int s; | ||
340 | const char *cause = NULL; | ||
341 | |||
342 | memset(&hints, 0, sizeof(hints)); | ||
343 | hints.ai_family = PF_UNSPEC; | ||
344 | hints.ai_socktype = SOCK_STREAM; | ||
345 | error = getaddrinfo("www.kame.net", "http", &hints, &res0); | ||
346 | if (error) { | ||
347 | err1(1, "%s", gai_strerror(error)); | ||
348 | /*NOTREACHED*/ | ||
349 | } | ||
350 | s = -1; | ||
351 | for (res = res0; res; res = res->ai_next) { | ||
352 | s = socket(res->ai_family, res->ai_socktype, | ||
353 | res->ai_protocol); | ||
354 | if (s < 0) { | ||
355 | cause = "socket"; | ||
356 | continue; | ||
357 | } | ||
358 | |||
359 | if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { | ||
360 | cause = "connect"; | ||
361 | close(s); | ||
362 | s = -1; | ||
363 | continue; | ||
364 | } | ||
365 | |||
366 | break; /* okay we got one */ | ||
367 | } | ||
368 | if (s < 0) { | ||
369 | err(1, cause); | ||
370 | /*NOTREACHED*/ | ||
371 | } | ||
372 | freeaddrinfo(res0); | ||
373 | .Ed | ||
374 | .Pp | ||
375 | The following example tries to open wildcard listening socket onto service | ||
376 | .Dq Li http , | ||
377 | for all the address families available. | ||
378 | .Bd -literal -offset indent | ||
379 | struct addrinfo hints, *res, *res0; | ||
380 | int error; | ||
381 | int s[MAXSOCK]; | ||
382 | int nsock; | ||
383 | const char *cause = NULL; | ||
384 | |||
385 | memset(&hints, 0, sizeof(hints)); | ||
386 | hints.ai_family = PF_UNSPEC; | ||
387 | hints.ai_socktype = SOCK_STREAM; | ||
388 | hints.ai_flags = AI_PASSIVE; | ||
389 | error = getaddrinfo(NULL, "http", &hints, &res0); | ||
390 | if (error) { | ||
391 | err1(1, "%s", gai_strerror(error)); | ||
392 | /*NOTREACHED*/ | ||
393 | } | ||
394 | nsock = 0; | ||
395 | for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { | ||
396 | s[nsock] = socket(res->ai_family, res->ai_socktype, | ||
397 | res->ai_protocol); | ||
398 | if (s[nsock] < 0) { | ||
399 | cause = "socket"; | ||
400 | continue; | ||
401 | } | ||
402 | |||
403 | if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { | ||
404 | cause = "connect"; | ||
405 | close(s[nsock]); | ||
406 | continue; | ||
407 | } | ||
408 | |||
409 | nsock++; | ||
410 | } | ||
411 | if (nsock == 0) { | ||
412 | err(1, cause); | ||
413 | /*NOTREACHED*/ | ||
414 | } | ||
415 | freeaddrinfo(res0); | ||
416 | .Ed | ||
417 | .\" | ||
284 | .Sh FILES | 418 | .Sh FILES |
285 | .Bl -tag -width /etc/resolv.conf -compact | 419 | .Bl -tag -width /etc/resolv.conf -compact |
286 | .It Pa /etc/hosts | 420 | .It Pa /etc/hosts |
287 | .It Pa /etc/host.conf | 421 | .It Pa /etc/host.conf |
288 | .It Pa /etc/resolv.conf | 422 | .It Pa /etc/resolv.conf |
289 | .El | 423 | .El |
424 | .\" | ||
290 | .Sh DIAGNOSTICS | 425 | .Sh DIAGNOSTICS |
291 | Error return status from | 426 | Error return status from |
292 | .Fn getaddrinfo | 427 | .Fn getaddrinfo |
@@ -339,6 +474,7 @@ If the argument is not one of the | |||
339 | .Dv EAI_xxx | 474 | .Dv EAI_xxx |
340 | values, the function still returns a pointer to a string whose contents | 475 | values, the function still returns a pointer to a string whose contents |
341 | indicate an unknown error. | 476 | indicate an unknown error. |
477 | .\" | ||
342 | .Sh SEE ALSO | 478 | .Sh SEE ALSO |
343 | .Xr getnameinfo 3 , | 479 | .Xr getnameinfo 3 , |
344 | .Xr gethostbyname 3 , | 480 | .Xr gethostbyname 3 , |
@@ -348,8 +484,27 @@ indicate an unknown error. | |||
348 | .Xr hostname 7 , | 484 | .Xr hostname 7 , |
349 | .Xr named 8 | 485 | .Xr named 8 |
350 | .Pp | 486 | .Pp |
351 | R. Gilligan, S. Thomson, J. Bound, and W. Stevens, | 487 | .Rs |
352 | ``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999. | 488 | .%A R. Gilligan |
489 | .%A S. Thomson | ||
490 | .%A J. Bound | ||
491 | .%A W. Stevens | ||
492 | .%T Basic Socket Interface Extensions for IPv6 | ||
493 | .%R RFC2553 | ||
494 | .%D March 1999 | ||
495 | .Re | ||
496 | .Rs | ||
497 | .%A Tatsuya Jinmei | ||
498 | .%A Atsushi Onoe | ||
499 | .%T "An Extension of Format for IPv6 Scoped Addresses" | ||
500 | .%R internet draft | ||
501 | .%N draft-ietf-ipngwg-scopedaddr-format-00.txt | ||
502 | .%O work in progress material | ||
503 | .Re | ||
504 | .\" | ||
505 | .Sh HISTORY | ||
506 | The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. | ||
507 | .\" | ||
353 | .Sh STANDARDS | 508 | .Sh STANDARDS |
354 | The | 509 | The |
355 | .Fn getaddrinfo | 510 | .Fn getaddrinfo |
@@ -357,5 +512,6 @@ function is defined IEEE POSIX 1003.1g draft specification, | |||
357 | and documented in | 512 | and documented in |
358 | .Dq Basic Socket Interface Extensions for IPv6 | 513 | .Dq Basic Socket Interface Extensions for IPv6 |
359 | .Pq RFC2533 . | 514 | .Pq RFC2533 . |
515 | .\" | ||
360 | .Sh BUGS | 516 | .Sh BUGS |
361 | The text was shamelessly copied from RFC2553. | 517 | The text was shamelessly copied from RFC2553. |