sync with latest KAME version. now includes description on scoped addr

extension.  add examples (good enough? >deraadt)

2 files changed, 234 insertions, 7 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.
diff --git a/src/lib/libc/net/getnameinfo.3 b/src/lib/libc/net/getnameinfo.3
index 98e4c2e866..2dd1bce4d6 100644
--- a/src/lib/libc/net/getnameinfo.3
+++ b/src/lib/libc/net/getnameinfo.3
@@ -1,3 +1,5 @@
+.\"     $OpenBSD: getnameinfo.3,v 1.4 2000/01/17 08:16:58 itojun Exp $
+.\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.
 .\"
@@ -30,14 +32,16 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
-.\"     $Id: getnameinfo.3,v 1.3 2000/01/06 22:00:18 deraadt Exp $
+.\"     KAME Id: getnameinfo.3,v 1.7 2000/01/17 08:13:04 itojun Exp
 .\"
 .Dd May 25, 1995
 .Dt GETNAMEINFO 3
 .Os
+.\"
 .Sh NAME
 .Nm getnameinfo
 .Nd address-to-nodename translation in protocol-independent manner
+.\"
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
@@ -45,6 +49,7 @@
 .Ft int
 .Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
 "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
+.\"
 .Sh DESCRIPTION
 The
 .Fn getnameinfo
@@ -170,15 +175,61 @@ These
 .Dv NI_xxx
 flags are defined in
 .Aq Pa netdb.h .
+.\"
+.Sh EXTENSION
+The implementation allows experimental numeric IPv6 address notation with
+scope identifier.
+IPv6 link-local address will appear as string like
+.Dq Li fe80::1@ne0 ,
+if
+.Dv NI_WITHSCOPEID
+bit is enabled in
+.Ar flags
+argument.
+Refer to
+.Xr getaddrinfo 3
+for the notation.
+.\"
+.Sh EXAMPLES
+The following code tries to get numeric hostname, and service name,
+for given socket address.
+Observe that there is no hardcoded reference to particular address family.
+.Bd -literal -offset indent
+struct sockaddr *sa;    /* input */
+char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
+
+if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
+                sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
+        errx(1, "could not get numeric hostname");
+        /*NOTREACHED*/
+}
+printf("host=%s, serv=%s\\n", hbuf, sbuf);
+.Ed
+.Pp
+The following version checks if the socket address has reverse address mapping.
+.Bd -literal -offset indent
+struct sockaddr *sa;    /* input */
+char hbuf[NI_MAXHOST];
+
+if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
+                NI_NAMEREQD)) {
+        errx(1, "could not resolve hostname");
+        /*NOTREACHED*/
+}
+printf("host=%s\\n", hbuf);
+.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
 The function indicates successful completion by a zero return value;
 a non-zero return value indicates failure.
+.\"
 .Sh SEE ALSO
 .Xr getaddrinfo 3 ,
 .Xr gethostbyaddr 3 ,
@@ -188,8 +239,27 @@ a non-zero return value indicates failure.
 .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
@@ -197,5 +267,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.