cleaner

1 files changed, 199 insertions, 0 deletions

diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3
new file mode 100644
index 00000000000..a1b3bdabb6d
--- /dev/null
+++ b/lib/libc/net/getnameinfo.3
@@ -0,0 +1,199 @@
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. 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.
+.\"
+.\" 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.
+.\"
+.\"     From: @(#)gethostbyname.3	8.4 (Berkeley) 5/25/95
+.\"     $Id: getnameinfo.3,v 1.1 1999/07/03 20:26:55 deraadt Exp $
+.\"
+.Dd May 25, 1995
+.Dt GETNAMEINFO 3
+.Os KAME
+.Sh NAME
+.Nm getnameinfo
+.Nd address-to-nodename translation in protocol-independent manner
+.Sh SYNOPSIS
+.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"
+.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 with
+.Xr gethostbyaddr 3 and
+.Xr getservbyport 3
+in 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.
+.Pp
+The first argument,
+.Fa sa ,
+points to either a
+.Fa sockaddr_in
+structure (for IPv4) or a
+.Fa 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
+or
+.Fa 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
+.Li <netdb.h> :
+.Bd -literal -offset
+#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>
+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.
+.Pp
+If the
+.Fa flag
+bit
+.Dv NI_NUMERICHOST
+is set, or if the host's name cannot be located in the DNS,
+the numeric form of the host's address is returned instead of its name
+.Po
+e.g., by calling
+.Fn inet_ntop
+instead of
+.Fn getnodebyaddr
+.Pc .
+If the
+.Fa flag
+bit
+.Dv NI_NAMEREQD
+is set, an error is returned if the host's name cannot be located in the DNS.
+.Pp
+If the flag bit
+.Dv NI_NUMERICSERV
+is set, the numeric form of the service address is returned
+.Pq e.g., its port number
+instead of its name.
+The two
+.Dv NI_NUMERICxxx
+flags are required to support the
+.Li "-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".
+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> .
+.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 ,
+.Xr getservbyport 3 ,
+.Xr hosts 5 ,
+.Xr services 5 ,
+.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.
+.Sh STANDARDS
+The
+.Fn getaddrinfo
+function is defined IEEE POSIX 1003.1g draft specification,
+and documented in ``Basic Socket Interface Extensions for IPv6''
+.Pq RFC2533 .
+.Sh BUGS
+The text was shamelessly copied from RFC2553.