sync with more recent kame tree.

- correct scoped notation separator (s/@/%/)
- include example and more references

1 files changed, 95 insertions, 18 deletions

diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3
index 84b98cb..0b47857 100644
--- a/lib/libc/net/getnameinfo.3
+++ b/lib/libc/net/getnameinfo.3
@@ -1,3 +1,6 @@
+.\"	$FreeBSD$
+.\"	$KAME: getnameinfo.3,v 1.16 2000/07/05 08:22:04 itojun Exp $
+.\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -30,8 +33,6 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3	8.4 (Berkeley) 5/25/95
-.\"     $Id: getnameinfo.3,v 1.2 1999/10/07 04:46:27 itojun Exp $
-.\"	$FreeBSD$
 .\"
 .Dd May 25, 1995
 .Dt GETNAMEINFO 3
@@ -48,7 +49,8 @@
 .Fd #include <sys/socket.h>
 .Fd #include <netdb.h>
 .Ft int
-.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
+.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
+"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
 .\"
 .Sh DESCRIPTION
 The
@@ -70,16 +72,16 @@ a non-zero return value indicates failure.
 The first argument,
 .Fa sa ,
 points to either a
-.Fa sockaddr_in
+.Li sockaddr_in
 structure (for IPv4) or a
-.Fa sockaddr_in6
+.Li sockaddr_in6
 structure (for IPv6) that holds the IP address and port number.
 The
 .Fa salen
 argument gives the length of the
-.Fa sockaddr_in
+.Li sockaddr_in
 or
-.Fa sockaddr_in6
+.Li sockaddr_in6
 structure.
 .Pp
 The function returns the nodename associated with the IP address in
@@ -102,22 +104,22 @@ or
 .Fa servlen
 arguments.
 Otherwise, the caller must provide buffers large enough to hold the
-nodename and the  service name, including the terminating null characters.
+nodename and the service name, including the terminating null characters.
 .Pp
 Unfortunately most systems do not provide constants that specify the
 maximum size of either a fully-qualified domain name or a service name.
 Therefore to aid the application in allocating buffers for these two
 returned strings the following constants are defined in
-.Li <netdb.h> :
+.Aq Pa netdb.h :
 .Bd -literal -offset
-#define	NI_MAXHOST  1025
-#define	NI_MAXSERV    32
+#define NI_MAXHOST  1025
+#define NI_MAXSERV    32
 .Ed
 .Pp
 The first value is actually defined as the constant
 .Dv MAXDNAME
 in recent versions of BIND's
-.Li <arpa/nameser.h>
+.Aq Pa arpa/nameser.h
 header
 .Po
 older versions of BIND define this constant to be 256
@@ -160,27 +162,30 @@ instead of its name.
 The two
 .Dv NI_NUMERICxxx
 flags are required to support the
-.Li "-n"
+.Fl n
 flag that many commands provide.
 .Pp
 A fifth flag bit,
 .Dv NI_DGRAM ,
 specifies that the service is a datagram service, and causes
 .Fn getservbyport
-to be called with a second argument of "udp" instead of its default of "tcp".
+to be called with a second argument of
+.Dq udp
+instead of its default of
+.Dq tcp .
 This is required for the few ports (512-514)
 that have different services for UDP and TCP.
 .Pp
 These
 .Dv NI_xxx
 flags are defined in
-.Li <netdb.h> .
+.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 ,
+.Dq Li fe80::1%ne0 ,
 if
 .Dv NI_WITHSCOPEID
 bit is enabled in
@@ -190,6 +195,35 @@ 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
@@ -200,6 +234,29 @@ for the notation.
 .Sh DIAGNOSTICS
 The function indicates successful completion by a zero return value;
 a non-zero return value indicates failure.
+Error codes are as below:
+.Bl -tag -width Er
+.It Bq Er EAI_AGAIN
+The name could not be resolved at this time.
+Future attempts may succeed.
+.It Bq Er EAI_BADFLAGS
+The flags had an invalid value.
+.It Bq Er EAI_FAIL
+A non-recoverable error occurred.
+.It Bq Er EAI_FAMILY
+The address family was not recognized or the address length was invalid
+for the specified family.
+.It Bq Er EAI_MEMORY
+There was a memory allocation failure.
+.It Bq Er EAI_NONAME
+The name does not resolve for the supplied parameters.
+.Dv NI_NAMEREQD
+is set and the host's name cannot be located,
+or both nodename and servname were null.
+.It Bq Er EAI_SYSTEM
+A system error occurred.
+The error code can be found in errno.
+.El
 .\"
 .Sh SEE ALSO
 .Xr getaddrinfo 3 ,
@@ -219,6 +276,20 @@ a non-zero return value indicates failure.
 .%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-02.txt
+.%O work in progress material
+.Re
+.Rs
+.%A Craig Metz
+.%T Protocol Independence Using the Sockets API
+.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
+.%D June 2000
+.Re
 .\"
 .Sh HISTORY
 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
@@ -227,8 +298,14 @@ The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 The
 .Fn getaddrinfo
 function is defined IEEE POSIX 1003.1g draft specification,
-and documented in ``Basic Socket Interface Extensions for IPv6''
-.Pq RFC2533 .
+and documented in
+.Dq Basic Socket Interface Extensions for IPv6
+.Pq RFC2553 .
 .\"
 .Sh BUGS
 The text was shamelessly copied from RFC2553.
+.Pp
+The type of the 2nd argument should be
+.Li socklen_t
+for RFC2553 conformance.
+The current code is based on pre-RFC2553 specification.