summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getaddrinfo.3
diff options
context:
space:
mode:
authoritojun <>2000-01-17 08:16:58 +0000
committeritojun <>2000-01-17 08:16:58 +0000
commit2bfc7e66c2e632f418c7896053db7d24d893e473 (patch)
tree0c113eaa5f183d2778cbc68b9cd6f926d528eae6 /src/lib/libc/net/getaddrinfo.3
parent10703049627aeae9e576798dac91d9f903cf661b (diff)
downloadopenbsd-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.3164
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
56The 60The
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
282values, the function still returns a pointer to a string whose contents 286values, the function still returns a pointer to a string whose contents
283indicate an unknown error. 287indicate an unknown error.
288.\"
289.Sh EXTENSION
290The implementation allows experimental numeric IPv6 address notation with
291scope identifier.
292By appending atmark and scope identifier to addresses, you can fill
293.Li sin6_scope_id
294field for addresses.
295This would make management of scoped address easier,
296and allows cut-and-paste input of scoped address.
297.Pp
298At this moment the code supports only link-local addresses with the format.
299Scope identifier is hardcoded to name of hardware interface associated
300with the link.
301.Po
302such as
303.Li ne0
304.Pc .
305Example would be like
306.Dq Li fe80::1@ne0 ,
307which means
308.Do
309.Li fe80::1
310on the link associated with
311.Li ne0
312interface
313.Dc .
314.Pp
315The implementation is still very experimental and non-standard.
316The current implementation assumes one-by-one relationship between
317interface and link, which is not necessarily true from the specification.
318.\"
319.Sh EXAMPLES
320The following code tries to connect to
321.Dq Li www.kame.net
322service
323.Dq Li http .
324via stream socket.
325It loops through all the addresses available, regardless from address family.
326If the destination resolves to IPv4 address, it will use
327.Dv AF_INET
328socket.
329Similarly, if it resolves to IPv6,
330.Dv AF_INET6
331socket is used.
332Observe that there is no hardcoded reference to particular address family.
333The code works even if
334.Nm getaddrinfo
335returns addresses that are not IPv4/v6.
336.Bd -literal -offset indent
337struct addrinfo hints, *res, *res0;
338int error;
339int s;
340const char *cause = NULL;
341
342memset(&hints, 0, sizeof(hints));
343hints.ai_family = PF_UNSPEC;
344hints.ai_socktype = SOCK_STREAM;
345error = getaddrinfo("www.kame.net", "http", &hints, &res0);
346if (error) {
347 err1(1, "%s", gai_strerror(error));
348 /*NOTREACHED*/
349}
350s = -1;
351for (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}
368if (s < 0) {
369 err(1, cause);
370 /*NOTREACHED*/
371}
372freeaddrinfo(res0);
373.Ed
374.Pp
375The following example tries to open wildcard listening socket onto service
376.Dq Li http ,
377for all the address families available.
378.Bd -literal -offset indent
379struct addrinfo hints, *res, *res0;
380int error;
381int s[MAXSOCK];
382int nsock;
383const char *cause = NULL;
384
385memset(&hints, 0, sizeof(hints));
386hints.ai_family = PF_UNSPEC;
387hints.ai_socktype = SOCK_STREAM;
388hints.ai_flags = AI_PASSIVE;
389error = getaddrinfo(NULL, "http", &hints, &res0);
390if (error) {
391 err1(1, "%s", gai_strerror(error));
392 /*NOTREACHED*/
393}
394nsock = 0;
395for (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}
411if (nsock == 0) {
412 err(1, cause);
413 /*NOTREACHED*/
414}
415freeaddrinfo(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
291Error return status from 426Error 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
340values, the function still returns a pointer to a string whose contents 475values, the function still returns a pointer to a string whose contents
341indicate an unknown error. 476indicate 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
351R. 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
506The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
507.\"
353.Sh STANDARDS 508.Sh STANDARDS
354The 509The
355.Fn getaddrinfo 510.Fn getaddrinfo
@@ -357,5 +512,6 @@ function is defined IEEE POSIX 1003.1g draft specification,
357and documented in 512and 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
361The text was shamelessly copied from RFC2553. 517The text was shamelessly copied from RFC2553.