man pages from WIDE

3 files changed, 498 insertions, 2 deletions

diff --git a/src/lib/libc/net/Makefile.inc b/src/lib/libc/net/Makefile.inc
index 97e11ba794..66e4794057 100644
--- a/src/lib/libc/net/Makefile.inc
+++ b/src/lib/libc/net/Makefile.inc
@@ -1,4 +1,4 @@
-#       $OpenBSD: Makefile.inc,v 1.21 1999/07/03 19:56:26 deraadt Exp $
+#       $OpenBSD: Makefile.inc,v 1.22 1999/07/03 20:22:21 deraadt Exp $
 
 # net sources
 .PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net ${LIBCSRCDIR}/net
@@ -27,7 +27,13 @@ SRCS+=	base64.c freeaddrinfo.c gai_strerror.c getaddrinfo.c gethostnamadr.c \
 
 MAN+=   byteorder.3 ethers.3 gethostbyname.3 getnetent.3 getprotoent.3 \
         getservent.3 inet.3 inet_net.3 iso_addr.3 link_addr.3 ns.3 ipx.3 \
-        rcmd.3 rcmdsh.3 resolver.3 net_addrcmp.3
+        rcmd.3 rcmdsh.3 resolver.3 net_addrcmp.3 \
+        getnameinfo.3 getaddrinfo.3 if_indextoname.3
+
+MLINKS+= getnameinfo.3 freeaddrinfo.3
+MLINKS+= getnameinfo.3 gai_strerror.3
+MLINKS+= if_indextoname.3 if_nametoindex.3
+MLINKS+= if_indextoname.3 if_nameindex.3
 
 MLINKS+=byteorder.3 htonl.3 byteorder.3 htons.3 byteorder.3 ntohl.3 \
         byteorder.3 ntohs.3 byteorder.3 htobe16.3 byteorder.3 htobe32.3 \
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3
new file mode 100644
index 0000000000..cff60d9d4e
--- /dev/null
+++ b/src/lib/libc/net/getaddrinfo.3
@@ -0,0 +1,359 @@
+.\" 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: getaddrinfo.3,v 1.1 1999/07/03 20:22:21 deraadt Exp $
+.\"
+.Dd May 25, 1995
+.Dt GETADDRINFO 3
+.Os KAME
+.Sh NAME
+.Nm getaddrinfo
+.Nm freeaddrinfo ,
+.Nm gai_strerror
+.Nd nodename-to-address translation in protocol-independent manner
+.Sh SYNOPSIS
+.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"
+.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 functionality of 
+.Xr gethostbyname 3
+and
+.Xr getservbyname 3 ,
+in more sophisticated manner.
+.Pp
+The addrinfo structure is defined as a result of including the
+.Li <netdb.h>
+header:
+.Bd -literal -offset
+struct addrinfo {                                                  *
+     int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
+     int     ai_family;    /* PF_xxx */
+     int     ai_socktype;  /* SOCK_xxx */
+     int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
+     size_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 */
+};
+.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
+.Fa ai_family
+means the caller will accept any protocol family.
+A value of 0 for
+.Fa ai_socktype
+means the caller will accept any socket type.
+A value of 0 for
+.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
+.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
+.Li addrinfo
+structure initialized to zero with
+.Fa ai_family
+set to 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
+structure in this list by following the
+.Fa ai_next
+pointer, until a
+.Dv NULL
+pointer is encountered.
+In each returned
+.Li addrinfo
+structure the three members
+.Fa ai_family ,
+.Fa ai_socktype ,
+and
+.Fa ai_protocol
+are the corresponding arguments for a call to the
+.Fn socket
+function.
+In each
+.Li addrinfo
+structure the
+.Fa ai_addr
+member points to a filled-in socket address structure whose length is
+specified by the
+.Fa ai_addrlen
+member.
+.Pp
+If the
+.Dv AI_PASSIVE
+bit is set in the
+.Fa ai_flags
+member of the
+.Fa hints
+structure, then the caller plans to use the returned socket address
+structure in a call to
+.Fn bind .
+In this case, if the
+.Fa nodename
+argument is a
+.Dv NULL
+pointer, then the IP address portion of the socket
+address structure will be set to
+.Dv INADDR_ANY
+for an IPv4 address or
+.Dv IN6ADDR_ANY_INIT
+for an IPv6 address.
+.Pp
+If the
+.Dv AI_PASSIVE
+bit is not set in the
+.Fa ai_flags
+member of the
+.Fa hints
+structure, then the returned socket address structure will be ready for a
+call to
+.Fn connect
+.Pq for a connection-oriented protocol
+or either
+.Fn connect ,
+.Fn sendto , or
+.Fn sendmsg
+.Pq for a connectionless protocol .
+In this case, if the
+.Fa nodename
+argument is a
+.Dv NULL
+pointer, then the IP address portion of the
+socket address structure will be set to the loopback address.
+.Pp
+If the
+.Dv AI_CANONNAME
+bit is set in the
+.Fa ai_flags
+member of the
+.Fa hints
+structure, then upon successful return the
+.Fa ai_canonname
+member of the first
+.Li addrinfo
+structure in the linked list will point to a null-terminated string
+containing the canonical name of the specified
+.Fa nodename .
+.Pp
+If the
+.Dv AI_NUMERICHOST
+bit is set in the
+.Fa ai_flags
+member of the
+.Fa hints
+structure, then a
+.Pf non Dv -NULL
+.Fa nodename
+string must be a numeric host address string.
+Otherwise an error of
+.Dv EAI_NONAME
+is returned.
+This flag prevents any type of name resolution service (e.g., the DNS)
+from being called.                                               
+.Pp
+All of the information returned by
+.Fn getaddrinfo
+is dynamically allocated:
+the
+.Li addrinfo
+structures, and 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
+is called.
+The
+.Fa addrinfo
+structure pointed to by the
+.Fa ai argument
+is freed, along with any dynamic storage pointed to by the structure.
+This operation is repeated until a
+.Dv NULL
+.Fa ai_next
+pointer is encountered.
+.Pp
+To aid applications in printing error messages based on the
+.Dv EAI_xxx
+codes returned by
+.Fn getaddrinfo ,
+.Fn gai_strerror
+is defined.
+The argument is one of the
+.Dv EAI_xxx
+values defined earlier and the return value points to a string describing
+the error.
+If the argument is not one of the
+.Dv EAI_xxx
+values, the function still returns a pointer to a string whose contents
+indicate an unknown error.
+.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
+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> ,
+and as follows:
+.Pp
+.Bl -tag -width EAI_ADDRFAMILY -compact
+.It Dv EAI_ADDRFAMILY 
+address family for nodename not supported
+.It Dv EAI_AGAIN
+temporary failure in name resolution
+.It Dv EAI_BADFLAGS
+invalid value for ai_flags
+.It Dv EAI_FAIL
+non-recoverable failure in name resolution
+.It Dv EAI_FAMILY
+ai_family not supported
+.It Dv EAI_MEMORY
+memory allocation failure
+.It Dv EAI_NODATA
+no address associated with nodename
+.It Dv EAI_NONAME
+nodename nor servname provided, or not known
+.It Dv EAI_SERVICE
+servname not supported for ai_socktype
+.It Dv EAI_SOCKTYPE
+ai_socktype not supported
+.It Dv EAI_SYSTEM
+system error returned in errno
+.El
+.Pp
+If called with proper argument,
+.Fn gai_strerror
+returns a pointer to a string describing the given error code.
+If the argument is not one of the
+.Dv EAI_xxx
+values, the function still returns a pointer to a string whose contents
+indicate an unknown error.
+.Sh SEE ALSO
+.Xr getnameinfo 3 ,
+.Xr gethostbyname 3 ,
+.Xr getservbyname 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.
diff --git a/src/lib/libc/net/if_indextoname.3 b/src/lib/libc/net/if_indextoname.3
new file mode 100644
index 0000000000..c8bb212536
--- /dev/null
+++ b/src/lib/libc/net/if_indextoname.3
@@ -0,0 +1,131 @@
+.\" Copyright (c) 1983, 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: @(#)rcmd.3        8.1 (Berkeley) 6/4/93
+.\"     $Id: if_indextoname.3,v 1.1 1999/07/03 20:22:21 deraadt Exp $
+.\"
+.Dd May 21, 1998
+.Dt IF_NAMETOINDEX 3
+.Os KAME
+.Sh NAME
+.Nm if_nametoindex ,
+.Nm if_indextoname ,
+.Nm if_nameindex ,
+.Nd convert interface index to name, and vice versa
+.Sh SYNOPSIS
+.Fd #include <net/if.h>
+.Ft "unsigned int"
+.Fn if_nametoindex "const char *ifname"
+.Ft "char *"
+.Fn if_indextoname "unsigned int ifindex" "char *ifname"
+.Ft "struct if_nameindex *"
+.Fn if_nameindex "void"
+.Ft "void"
+.Sh DESCRIPTION
+The functions map interface index to readable interface name
+.Po
+such as
+.Li ``lo0''
+.Pc
+, and vice versa.
+.Pp
+.Fn if_nametoindex
+converts readable interface name to interface index
+.Pp positive integer value .
+If the specified interface does not exist, 0 will be returned.
+.Pp
+.Fn if_indextoname
+converts interface index to readable interface name.
+The
+.Fa ifname
+argument must point to a buffer of at least
+.Dv IF_NAMESIZE
+bytes into which the interface name corresponding to the specified index is
+returned.
+.Po
+.Dv IF_NAMESIZE
+is also defined in
+.Li <net/if.h>
+and its value includes a terminating null byte at the end of the
+interface name.
+.Pc
+This pointer is also the return value of the function.
+If there is no interface corresponding to the specified index,
+.Dv NULL
+is returned.
+.Pp
+.Fn if_nameindex
+returns an array of
+.Fa if_nameindex
+structures.
+.Fa if_nametoindex
+is also defined in
+.Li <net/if.h> ,
+and is as follows:
+.Bd -literal -offset
+struct if_nameindex {
+    unsigned int   if_index;  /* 1, 2, ... */
+    char          *if_name;   /* null terminated name: "le0", ... */
+};
+.Ed
+.Pp
+The end of the array of structures is indicated by a structure with
+an
+.Fa if_index
+of 0 and an
+.Fa if_name
+of
+.Dv NULL .
+The function returns a
+.Dv NULL
+pointer upon an error.
+The memory used for this array of structures along with the interface
+names pointed to by the
+.Fa if_name
+members is obtained dynamically.
+This memory is freed by the
+.Xr free 3
+function.
+.Sh DIAGNOSTICS
+.Fn if_nametoindex
+returns 0 on error, positive integer on success.
+.Fn if_indextoname
+and
+.Fn if_nameindex
+return
+.Dv NULL
+on errors.
+.Sh SEE ALSO
+R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
+``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
+.Sh STANDARDS
+These functions are defined in ``Basic Socket Interface Extensions for IPv6''
+.Pq RFC2533 .