sync with more recent kame tree.

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

2 files changed, 254 insertions, 45 deletions

diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3
index fd4b6d1..2e608cd 100644
--- a/lib/libc/net/getaddrinfo.3
+++ b/lib/libc/net/getaddrinfo.3
@@ -1,4 +1,7 @@
 .\" Copyright (c) 1983, 1987, 1991, 1993
+.\"	$FreeBSD$
+.\"	$KAME: getaddrinfo.3,v 1.16 2000/07/05 08:18:42 itojun Exp $
+.\"
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -30,15 +33,13 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3	8.4 (Berkeley) 5/25/95
-.\"     $Id: getaddrinfo.3,v 1.3 1999/10/07 08:22:04 jinmei Exp $
-.\"	$FreeBSD$
 .\"
 .Dd May 25, 1995
 .Dt GETADDRINFO 3
 .Os KAME
 .\"
 .Sh NAME
-.Nm getaddrinfo
+.Nm getaddrinfo ,
 .Nm freeaddrinfo ,
 .Nm gai_strerror
 .Nd nodename-to-address translation in protocol-independent manner
@@ -50,7 +51,8 @@
 .Fd #include <sys/socket.h>
 .Fd #include <netdb.h>
 .Ft int
-.Fn getaddrinfo "const char *nodename" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res"
+.Fn getaddrinfo "const char *nodename" "const char *servname" \
+"const struct addrinfo *hints" "struct addrinfo **res"
 .Ft void
 .Fn freeaddrinfo "struct addrinfo *ai"
 .Ft "char *"
@@ -60,14 +62,16 @@
 The
 .Fn getaddrinfo
 function is defined for protocol-independent nodename-to-address translation.
-It performs functionality of
+It performs the functionality of
 .Xr gethostbyname 3
 and
 .Xr getservbyname 3 ,
-in more sophisticated manner.
+but in a more sophisticated manner.
 .Pp
-The addrinfo structure is defined as a result of including the
-.Li <netdb.h>
+The
+.Li addrinfo
+structure is defined as a result of including the
+.Aq Pa netdb.h
 header:
 .Bd -literal -offset
 struct addrinfo {                                                  *
@@ -161,7 +165,8 @@ pointer, this is the same as if the caller had filled in an
 .Li addrinfo
 structure initialized to zero with
 .Fa ai_family
-set to PF_UNSPEC.
+set to
+.Dv PF_UNSPEC .
 .Pp
 Upon successful return a pointer to a linked list of one or more
 .Li addrinfo
@@ -224,7 +229,8 @@ call to
 .Pq for a connection-oriented protocol
 or either
 .Fn connect ,
-.Fn sendto , or
+.Fn sendto ,
+or
 .Fn sendmsg
 .Pq for a connectionless protocol .
 In this case, if the
@@ -269,7 +275,7 @@ All of the information returned by
 is dynamically allocated:
 the
 .Li addrinfo
-structures, and the socket address structures and canonical node name
+structures, the socket address structures, and canonical node name
 strings pointed to by the addrinfo structures.
 To return this information to the system the function
 .Fn freeaddrinfo
@@ -316,7 +322,7 @@ such as
 .Li ne0
 .Pc .
 Example would be like
-.Dq Li fe80::1@ne0 ,
+.Dq Li fe80::1%ne0 ,
 which means
 .Do
 .Li fe80::1
@@ -329,6 +335,105 @@ 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
@@ -341,32 +446,44 @@ Error return status from
 .Fn getaddrinfo
 is zero on success and non-zero on errors.
 Non-zero error codes are defined in
-.Li <netdb.h> ,
+.Aq Pa netdb.h ,
 and as follows:
 .Pp
 .Bl -tag -width EAI_ADDRFAMILY -compact
 .It Dv EAI_ADDRFAMILY
-address family for nodename not supported
+Address family for
+.Fa nodename
+not supported.
 .It Dv EAI_AGAIN
-temporary failure in name resolution
+Temporary failure in name resolution.
 .It Dv EAI_BADFLAGS
-invalid value for ai_flags
+Invalid value for
+.Fa ai_flags .
 .It Dv EAI_FAIL
-non-recoverable failure in name resolution
+Non-recoverable failure in name resolution.
 .It Dv EAI_FAMILY
-ai_family not supported
+.Fa ai_family
+not supported.
 .It Dv EAI_MEMORY
-memory allocation failure
+Memory allocation failure.
 .It Dv EAI_NODATA
-no address associated with nodename
+No address associated with
+.Fa nodename .
 .It Dv EAI_NONAME
-nodename nor servname provided, or not known
+.Fa nodename
+nor
+.Fa servname
+provided, or not known.
 .It Dv EAI_SERVICE
-servname not supported for ai_socktype
+.Fa servname
+not supported for
+.Fa ai_socktype .
 .It Dv EAI_SOCKTYPE
-ai_socktype not supported
+.Fa ai_socktype
+not supported.
 .It Dv EAI_SYSTEM
-system error returned in errno
+System error returned in
+.Va errno .
 .El
 .Pp
 If called with proper argument,
@@ -384,7 +501,7 @@ indicate an unknown error.
 .Xr hosts 5 ,
 .Xr services 5 ,
 .Xr hostname 7 ,
-.Xr named 8 .
+.Xr named 8
 .Pp
 .Rs
 .%A R. Gilligan
@@ -395,6 +512,20 @@ indicate an unknown error.
 .%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.
@@ -403,8 +534,9 @@ 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.
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.