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 @@
-.\"     $OpenBSD: getaddrinfo.3,v 1.4 2000/01/06 22:00:17 deraadt Exp $
+.\"     $OpenBSD: getaddrinfo.3,v 1.5 2000/01/17 08:16:58 itojun Exp $
+.\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.
 .\"
@@ -31,16 +32,18 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
-.\"     $Id: getaddrinfo.3,v 1.4 2000/01/06 22:00:17 deraadt Exp $
+.\"     KAME Id: getaddrinfo.3,v 1.8 2000/01/17 08:13:03 itojun Exp
 .\"
 .Dd May 25, 1995
 .Dt GETADDRINFO 3
 .Os
+.\"
 .Sh NAME
 .Nm getaddrinfo ,
 .Nm freeaddrinfo ,
 .Nm gai_strerror
 .Nd nodename-to-address translation in protocol-independent manner
+.\"
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
@@ -52,6 +55,7 @@
 .Fn freeaddrinfo "struct addrinfo *ai"
 .Ft "char *"
 .Fn gai_strerror "int ecode"
+.\"
 .Sh DESCRIPTION
 The
 .Fn getaddrinfo
@@ -281,12 +285,143 @@ If the argument is not one of the
 .Dv EAI_xxx
 values, the function still returns a pointer to a string whose contents
 indicate an unknown error.
+.\"
+.Sh EXTENSION
+The implementation allows experimental numeric IPv6 address notation with
+scope identifier.
+By appending atmark and scope identifier to addresses, you can fill
+.Li sin6_scope_id
+field for addresses.
+This would make management of scoped address easier,
+and allows cut-and-paste input of scoped address.
+.Pp
+At this moment the code supports only link-local addresses with the format.
+Scope identifier is hardcoded to name of hardware interface associated
+with the link.
+.Po
+such as
+.Li ne0
+.Pc .
+Example would be like
+.Dq Li fe80::1@ne0 ,
+which means
+.Do
+.Li fe80::1
+on the link associated with
+.Li ne0
+interface
+.Dc .
+.Pp
+The implementation is still very experimental and non-standard.
+The current implementation assumes one-by-one relationship between
+interface and link, which is not necessarily true from the specification.
+.\"
+.Sh EXAMPLES
+The following code tries to connect to
+.Dq Li www.kame.net
+service
+.Dq Li http .
+via stream socket.
+It loops through all the addresses available, regardless from address family.
+If the destination resolves to IPv4 address, it will use
+.Dv AF_INET
+socket.
+Similarly, if it resolves to IPv6,
+.Dv AF_INET6
+socket is used.
+Observe that there is no hardcoded reference to particular address family.
+The code works even if
+.Nm getaddrinfo
+returns addresses that are not IPv4/v6.
+.Bd -literal -offset indent
+struct addrinfo hints, *res, *res0;
+int error;
+int s;
+const char *cause = NULL;
+
+memset(&hints, 0, sizeof(hints));
+hints.ai_family = PF_UNSPEC;
+hints.ai_socktype = SOCK_STREAM;
+error = getaddrinfo("www.kame.net", "http", &hints, &res0);
+if (error) {
+        err1(1, "%s", gai_strerror(error));
+        /*NOTREACHED*/
+}
+s = -1;
+for (res = res0; res; res = res->ai_next) {
+        s = socket(res->ai_family, res->ai_socktype,
+                res->ai_protocol);
+        if (s < 0) {
+                cause = "socket";
+                continue;
+        }
+
+        if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
+                cause = "connect";
+                close(s);
+                s = -1;
+                continue;
+        }
+
+        break;  /* okay we got one */
+}
+if (s < 0) {
+        err(1, cause);
+        /*NOTREACHED*/
+}
+freeaddrinfo(res0);
+.Ed
+.Pp
+The following example tries to open wildcard listening socket onto service
+.Dq Li http ,
+for all the address families available.
+.Bd -literal -offset indent
+struct addrinfo hints, *res, *res0;
+int error;
+int s[MAXSOCK];
+int nsock;
+const char *cause = NULL;
+
+memset(&hints, 0, sizeof(hints));
+hints.ai_family = PF_UNSPEC;
+hints.ai_socktype = SOCK_STREAM;
+hints.ai_flags = AI_PASSIVE;
+error = getaddrinfo(NULL, "http", &hints, &res0);
+if (error) {
+        err1(1, "%s", gai_strerror(error));
+        /*NOTREACHED*/
+}
+nsock = 0;
+for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
+        s[nsock] = socket(res->ai_family, res->ai_socktype,
+                res->ai_protocol);
+        if (s[nsock] < 0) {
+                cause = "socket";
+                continue;
+        }
+
+        if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
+                cause = "connect";
+                close(s[nsock]);
+                continue;
+        }
+
+        nsock++;
+}
+if (nsock == 0) {
+        err(1, cause);
+        /*NOTREACHED*/
+}
+freeaddrinfo(res0);
+.Ed
+.\"
 .Sh FILES
 .Bl -tag -width /etc/resolv.conf -compact
 .It Pa /etc/hosts
 .It Pa /etc/host.conf
 .It Pa /etc/resolv.conf
 .El
+.\"
 .Sh DIAGNOSTICS
 Error return status from
 .Fn getaddrinfo
@@ -339,6 +474,7 @@ If the argument is not one of the
 .Dv EAI_xxx
 values, the function still returns a pointer to a string whose contents
 indicate an unknown error.
+.\"
 .Sh SEE ALSO
 .Xr getnameinfo 3 ,
 .Xr gethostbyname 3 ,
@@ -348,8 +484,27 @@ indicate an unknown error.
 .Xr hostname 7 ,
 .Xr named 8
 .Pp
-R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
-``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
+.Rs
+.%A R. Gilligan
+.%A S. Thomson
+.%A J. Bound
+.%A W. Stevens
+.%T Basic Socket Interface Extensions for IPv6
+.%R RFC2553
+.%D March 1999
+.Re
+.Rs
+.%A Tatsuya Jinmei
+.%A Atsushi Onoe
+.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%R internet draft
+.%N draft-ietf-ipngwg-scopedaddr-format-00.txt
+.%O work in progress material
+.Re
+.\"
+.Sh HISTORY
+The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
+.\"
 .Sh STANDARDS
 The
 .Fn getaddrinfo
@@ -357,5 +512,6 @@ function is defined IEEE POSIX 1003.1g draft specification,
 and documented in
 .Dq Basic Socket Interface Extensions for IPv6
 .Pq RFC2533 .
+.\"
 .Sh BUGS
 The text was shamelessly copied from RFC2553.