[src/trunk]: src replace with written-from-scratch manpage. (fixes ISOC copyr...

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f83f632a6e2b
branches:  trunk
changeset: 572733:f83f632a6e2b
user:      itojun <itojun%NetBSD.org@localhost>
date:      Tue Jan 11 06:01:41 2005 +0000

description:
replace with written-from-scratch manpage. (fixes ISOC copyright issue)

diffstat:

 lib/libc/net/Makefile.inc  |     6 +-
 lib/libc/net/getaddrinfo.3 |   695 +++++++++----------------
 share/man/man4/icmp6.4     |   357 ++++++------
 share/man/man4/ip6.4       |  1179 +++++++++++++++++++++----------------------
 4 files changed, 1018 insertions(+), 1219 deletions(-)

diffs (truncated from 2554 to 300 lines):

diff -r b9c85d9c0574 -r f83f632a6e2b lib/libc/net/Makefile.inc
--- a/lib/libc/net/Makefile.inc Tue Jan 11 05:42:17 2005 +0000
+++ b/lib/libc/net/Makefile.inc Tue Jan 11 06:01:41 2005 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.67 2005/01/10 02:58:58 lukem Exp $
+#      $NetBSD: Makefile.inc,v 1.68 2005/01/11 06:01:41 itojun Exp $
 #      @(#)Makefile.inc        8.2 (Berkeley) 9/5/93
 
 # net sources
@@ -82,9 +82,9 @@
        resolver.3 res_search.3
 
 # IPv6
-MAN+=  getaddrinfo.3 getnameinfo.3 if_indextoname.3 \
+MAN+=  gai_strerror.3 getaddrinfo.3 getnameinfo.3 if_indextoname.3 \
        inet6_option_space.3 inet6_rthdr_space.3
-MLINKS+=getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 gai_strerror.3 \
+MLINKS+=getaddrinfo.3 freeaddrinfo.3 \
        getifaddrs.3 freeifaddrs.3 \
        if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
        if_indextoname.3 if_freenameindex.3 \
diff -r b9c85d9c0574 -r f83f632a6e2b lib/libc/net/getaddrinfo.3
--- a/lib/libc/net/getaddrinfo.3        Tue Jan 11 05:42:17 2005 +0000
+++ b/lib/libc/net/getaddrinfo.3        Tue Jan 11 06:01:41 2005 +0000
@@ -1,212 +1,154 @@
-.\"    $NetBSD: getaddrinfo.3,v 1.38 2004/12/20 18:30:26 christos Exp $
-.\"    $KAME: getaddrinfo.3,v 1.32 2003/04/30 06:06:42 itojun Exp $
+.\"    $NetBSD: getaddrinfo.3,v 1.39 2005/01/11 06:01:41 itojun Exp $
+.\"    $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
+.\"    $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
 .\"
-.\" Copyright (c) 1983, 1987, 1991, 1993
-.\"    The Regents of the University of California.  All rights reserved.
+.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001  Internet Software Consortium.
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of the University nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\"     From: @(#)gethostbyname.3      8.4 (Berkeley) 5/25/95
-.\"
-.Dd April 14, 2004
+.Dd December 20, 2004
 .Dt GETADDRINFO 3
 .Os
-.\"
 .Sh NAME
 .Nm getaddrinfo ,
-.Nm freeaddrinfo ,
-.Nm gai_strerror
-.Nd nodename-to-address translation in protocol-independent manner
-.\"
-.Sh LIBRARY
-.Lb libc
-.\"
+.Nm freeaddrinfo
+.Nd socket address structure to host and service name
 .Sh SYNOPSIS
-.In netdb.h
+.Fd #include <sys/types.h>
+.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 *hostname" "const char *servname" \
+    "const struct addrinfo *hints" "struct addrinfo **res"
 .Ft void
 .Fn freeaddrinfo "struct addrinfo *ai"
-.Ft "char *"
-.Fn gai_strerror "int ecode"
-.\"
 .Sh DESCRIPTION
 The
 .Fn getaddrinfo
-function is defined for protocol-independent nodename-to-address translation.
-It performs the functionality of
+function is used to get a list of
+.Tn IP
+addresses and port numbers for host
+.Fa hostname
+and service
+.Fa servname .
+It is a replacement for and provides more flexibility than the
 .Xr gethostbyname 3
 and
-.Xr getservbyname 3 ,
-but in a more sophisticated manner.
+.Xr getservbyname 3
+functions.
 .Pp
 The
-.Li addrinfo
-structure is defined as a result of including the
-.Aq Pa netdb.h
-header:
-.Bd -literal -offset
+.Fa hostname
+and
+.Fa servname
+arguments are either pointers to NUL-terminated strings or the null pointer.
+An acceptable value for
+.Fa hostname
+is either a valid host name or a numeric host address string consisting
+of a dotted decimal IPv4 address or an IPv6 address.
+The
+.Fa servname
+is either a decimal port number or a service name listed in
+.Xr services 5 .
+At least one of
+.Fa hostname
+and
+.Fa servname
+must be non-null.
+.Pp
+.Fa hints
+is an optional pointer to a
+.Li struct addrinfo ,
+as defined by
+.Aq Pa netdb.h :
+.Bd -literal
 struct addrinfo {
-     int       ai_flags;     /* AI_xxx */
-     int       ai_family;    /* PF_xxx */
-     int       ai_socktype;  /* SOCK_xxx */
-     int       ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
-     socklen_t ai_addrlen;   /* length of ai_addr */
-     char *    ai_canonname; /* canonical name for nodename */
-     struct sockaddr  *ai_addr; /* binary address */
-     struct addrinfo  *ai_next; /* next structure in linked list */
+       int ai_flags;           /* input flags */
+       int ai_family;          /* protocol family for socket */
+       int ai_socktype;        /* socket type */
+       int ai_protocol;        /* protocol for socket */
+       socklen_t ai_addrlen;   /* length of socket-address */
+       struct sockaddr *ai_addr; /* socket-address for socket */
+       char *ai_canonname;     /* canonical name for service location */
+       struct addrinfo *ai_next; /* pointer to next in list */
 };
 .Ed
 .Pp
-The
-.Fa nodename
-and
-.Fa servname
-arguments are pointers to null-terminated strings or
-.Dv NULL .
-One or both of these two arguments must be a
-.Pf non Dv -NULL
-pointer.
-In the normal client scenario, both the
-.Fa nodename
-and
-.Fa servname
-are specified.
-In the normal server scenario, only the
-.Fa servname
-is specified.
-A
-.Pf non Dv -NULL
-.Fa nodename
-string can be either a node name or a numeric host address string
-.Po
-i.e., a dotted-decimal IPv4 address or an IPv6 hex address
-.Pc .
-A
-.Pf non Dv -NULL
-.Fa servname
-string can be either a service name or a decimal port number.
-.Pp
-The caller can optionally pass an
-.Li addrinfo
-structure, pointed to by the third argument,
-to provide hints concerning the type of socket that the caller supports.
-In this
-.Fa hints
-structure all members other than
-.Fa ai_flags ,
-.Fa ai_family ,
-.Fa ai_socktype ,
-and
-.Fa ai_protocol
-must be zero or a
-.Dv NULL
-pointer.
-A value of
-.Dv PF_UNSPEC
-for
+This structure can be used to provide hints concerning the type of socket
+that the caller supports or wishes to use.
+The caller can supply the following structure elements in
+.Fa hints :
+.Bl -tag -width "ai_socktypeXX"
+.It Fa ai_family
+The protocol family that should be used.
+When
 .Fa ai_family
-means the caller will accept any protocol family.
-A value of 0 for
+is set to
+.Dv PF_UNSPEC ,
+it means the caller will accept any protocol family supported by the
+operating system.
+.It Fa ai_socktype
+Denotes the type of socket that is wanted:
+.Dv SOCK_STREAM ,
+.Dv SOCK_DGRAM ,
+or
+.Dv SOCK_RAW .
+When
 .Fa ai_socktype
-means the caller will accept any socket type.
-A value of 0 for
+is zero the caller will accept any socket type.
+.It Fa ai_protocol
+Indicates which transport protocol is desired,
+.Dv IPPROTO_UDP
+or
+.Dv IPPROTO_TCP .
+If
 .Fa ai_protocol
-means the caller will accept any protocol.
-For example, if the caller handles only TCP and not UDP, then the
-.Fa ai_socktype
-member of the hints structure should be set to
-.Dv SOCK_STREAM
-when
+is zero the caller will accept any protocol.
+.It Fa ai_flags
+.Fa ai_flags
+is formed by
+.Tn OR Ns 'ing
+the following values:
+.Bl -tag -width "AI_CANONNAMEXX"
+.It Dv AI_CANONNAME
+If the
+.Dv AI_CANONNAME
+bit is set, a successful call to
 .Fn getaddrinfo
-is called.
-If the caller handles only IPv4 and not IPv6, then the
-.Fa ai_family
-member of the
-.Fa hints
-structure should be set to
-.Dv PF_INET
-when
-.Fn getaddrinfo
-is called.
-If the third argument to
-.Fn getaddrinfo
-is a
-.Dv NULL
-pointer, this is the same as if the caller had filled in an
+will return a NUL-terminated string containing the canonical name
+of the specified hostname in the
+.Fa ai_canonname
+element of the first
 .Li addrinfo
-structure initialized to zero with
-.Fa ai_family
-set to
-.Dv PF_UNSPEC .
-.Pp
-Upon successful return a pointer to a linked list of one or more
-.Li addrinfo
-structures is returned through the final argument.
-The caller can process each
-.Li addrinfo