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

extension.  add examples (good enough? >deraadt)

1 files changed, 74 insertions, 3 deletions

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.