[src/trunk]: src/lib/libc/net written-from-scratch manpage (fixes ISOC copyri...

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

details:   https://anonhg.NetBSD.org/src/rev/8f9bbb91f730
branches:  trunk
changeset: 572737:8f9bbb91f730
user:      itojun <itojun%NetBSD.org@localhost>
date:      Tue Jan 11 07:26:57 2005 +0000

description:
written-from-scratch manpage (fixes ISOC copyright violation)

diffstat:

 lib/libc/net/gai_strerror.3 |   94 +++++++++++
 lib/libc/net/getnameinfo.3  |  360 +++++++++++++++++--------------------------
 2 files changed, 235 insertions(+), 219 deletions(-)

diffs (truncated from 579 to 300 lines):

diff -r 9fff2c750fe6 -r 8f9bbb91f730 lib/libc/net/gai_strerror.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/net/gai_strerror.3       Tue Jan 11 07:26:57 2005 +0000
@@ -0,0 +1,94 @@
+.\"    $NetBSD: gai_strerror.3,v 1.1 2005/01/11 07:26:57 itojun Exp $
+.\"    $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $
+.\"    $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $
+.\"
+.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001  Internet Software Consortium.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.Dd December 20, 2004
+.Dt GAI_STRERROR 3
+.Os
+.Sh NAME
+.Nm gai_strerror
+.Nd get error message string from EAI_xxx error code
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Fd #include <netdb.h>
+.Ft "const char *"
+.Fn gai_strerror "int ecode"
+.Sh DESCRIPTION
+The
+.Fn gai_strerror
+function returns an error message string corresponding to the error code
+returned by
+.Xr getaddrinfo 3
+or
+.Xr getnameinfo 3 .
+.Pp
+The following error codes and their meaning are defined in
+.Aq Pa netdb.h :
+.Pp
+.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact
+.It Dv EAI_ADDRFAMILY
+address family for
+.Fa hostname
+not supported
+.It Dv EAI_AGAIN
+temporary failure in name resolution
+.It Dv EAI_BADFLAGS
+invalid value for
+.Fa ai_flags
+.It Dv EAI_BADHINTS
+invalid value for
+.Fa hints
+.It Dv EAI_FAIL
+non-recoverable failure in name resolution
+.It Dv EAI_FAMILY
+.Fa ai_family
+not supported.
+.It Dv EAI_MEMORY
+memory allocation failure
+.It Dv EAI_NODATA
+no address associated with
+.Fa hostname
+.It Dv EAI_NONAME
+.Fa hostname
+or
+.Fa servname
+not provided, or not known
+.It Dv EAI_PROTOCOL
+resolved protocol is unknown
+.It Dv EAI_SERVICE
+.Fa servname
+not supported for
+.Fa ai_socktype
+.It Dv EAI_SOCKTYPE
+.Fa ai_socktype
+not supported
+.It Dv EAI_SYSTEM
+system error returned in
+.Va errno
+.El
+.Sh RETURN VALUES
+.Fn gai_strerror
+returns a pointer to the error message string corresponding to
+.Fa ecode .
+If
+.Fa ecode
+is out of range, an implementation-specific error message string is returned.
+.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr getnameinfo 3
diff -r 9fff2c750fe6 -r 8f9bbb91f730 lib/libc/net/getnameinfo.3
--- a/lib/libc/net/getnameinfo.3        Tue Jan 11 07:23:49 2005 +0000
+++ b/lib/libc/net/getnameinfo.3        Tue Jan 11 07:26:57 2005 +0000
@@ -1,258 +1,174 @@
-.\"    $NetBSD: getnameinfo.3,v 1.32 2004/12/20 18:30:26 christos Exp $
-.\"    $KAME: getnameinfo.3,v 1.27 2003/04/30 06:06:42 itojun Exp $
+.\"    $NetBSD: getnameinfo.3,v 1.33 2005/01/11 07:26:57 itojun Exp $
+.\"    $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
+.\"    $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc 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 August 28, 2003
+.Dd December 20, 2004
 .Dt GETNAMEINFO 3
 .Os
-.\"
 .Sh NAME
 .Nm getnameinfo
-.Nd address-to-nodename translation in protocol-independent manner
-.\"
-.Sh LIBRARY
-.Lb libc
-.\"
+.Nd socket address structure to hostname 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 getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
-"char *host" "socklen_t hostlen" "char *serv" "socklen_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
 .Fn getnameinfo
-function is defined for protocol-independent address-to-nodename translation.
-Its functionality is a reverse conversion of
-.Xr getaddrinfo 3 ,
-and implements similar functionality to
+function is used to convert a
+.Li sockaddr
+structure to a pair of host name and service strings.
+It is a replacement for and provides more flexibility than the
 .Xr gethostbyaddr 3
 and
 .Xr getservbyport 3
-in a more sophisticated manner.
-.Pp
-This function looks up an IP address and port number provided by the
-caller in the DNS and system-specific database, and returns text
-strings for both in buffers provided by the caller.
-The function indicates successful completion by a zero return value;
-a non-zero return value indicates failure.
+functions and is the converse of the
+.Xr getaddrinfo 3
+function.
 .Pp
-The first argument,
-.Fa sa ,
-points to either a
-.Li sockaddr_in
-structure (for IPv4) or a
-.Li sockaddr_in6
-structure (for IPv6) that holds the IP address and port number.
 The
-.Fa salen
-argument gives the length of the
+.Li sockaddr
+structure
+.Fa sa
+should point to either a
 .Li sockaddr_in
 or
 .Li sockaddr_in6
-structure.
-.Pp
-The function returns the nodename associated with the IP address in
-the buffer pointed to by the
-.Fa host
-argument.
-The caller provides the size of this buffer via the
-.Fa hostlen
-argument.
-The service name associated with the port number is returned in the buffer
-pointed to by
-.Fa serv ,
-and the
-.Fa servlen
-argument gives the length of this buffer.
-The caller specifies not to return either string by providing a zero
-value for the
-.Fa hostlen
-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.
-.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
-.Aq Pa netdb.h :
-.Bd -literal -offset
-#define NI_MAXHOST  1025
-#define NI_MAXSERV    32
-.Ed
+structure (for IPv4 or IPv6 respectively) that is
+.Fa salen
+bytes long.
 .Pp
-The first value is actually defined as the constant
-.Dv MAXDNAME
-in recent versions of BIND's
-.Aq Pa arpa/nameser.h
-header
-.Po
-older versions of BIND define this constant to be 256
-.Pc
-and the second is a guess based on the services listed in the current
-Assigned Numbers RFC.
-.Pp
-The final argument is a
-.Fa flag
-that changes the default actions of this function.
-By default the fully-qualified domain name (FQDN) for the host is
-looked up in the DNS and returned.
-If the flag bit
-.Dv NI_NOFQDN
-is set, only the nodename portion of the FQDN is returned for local hosts.
+The host and service names associated with
+.Fa sa
+are stored in
+.Fa host
+and
+.Fa serv
+which have length parameters
+.Fa hostlen
+and
+.Fa servlen .
+The maximum value for
+.Fa hostlen
+is
+.Dv NI_MAXHOST
+and
+the maximum value for
+.Fa servlen
+is
+.Dv NI_MAXSERV ,
+as defined by
+.Aq Pa netdb.h .
+If a length parameter is zero, no string will be stored.
+Otherwise, enough space must be provided to store the
+host name or service string plus a byte for the NUL terminator.
 .Pp
-If the
-.Fa flag
-bit