1 files changed, 206 insertions, 58 deletions

diff --git a/src/lib/libc/net/inet.3 b/src/lib/libc/net/inet.3
index 49bac97e96..3f198ae8e0 100644
--- a/src/lib/libc/net/inet.3
+++ b/src/lib/libc/net/inet.3
@@ -1,4 +1,5 @@
-.\"     $NetBSD: inet.3,v 1.4 1995/02/27 09:45:26 chopps Exp $
+.\"     $OpenBSD: inet.3,v 1.22 2008/12/09 19:38:38 otto Exp $
+.\"     $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem Exp $
 .\"
 .\" Copyright (c) 1983, 1990, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -11,11 +12,7 @@
 .\" 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
+.\" 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.
 .\"
@@ -33,52 +30,74 @@
 .\"
 .\"     @(#)inet.3      8.1 (Berkeley) 6/4/93
 .\"
-.Dd June 4, 1993
+.Dd $Mdocdate: December 9 2008 $
 .Dt INET 3
-.Os BSD 4.2
+.Os
 .Sh NAME
-.Nm inet_aton ,
 .Nm inet_addr ,
+.Nm inet_aton ,
+.Nm inet_lnaof ,
+.Nm inet_makeaddr ,
+.Nm inet_netof ,
 .Nm inet_network ,
 .Nm inet_ntoa ,
-.Nm inet_makeaddr ,
-.Nm inet_lnaof ,
-.Nm inet_netof
+.Nm inet_ntop ,
+.Nm inet_pton
 .Nd Internet address manipulation routines
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
 .Fd #include <netinet/in.h>
 .Fd #include <arpa/inet.h>
-.Ft int 
-.Fn inet_aton "const char *cp" "struct in_addr *pin"
-.Ft unsigned long 
+.Ft in_addr_t
 .Fn inet_addr "const char *cp"
-.Ft unsigned long 
+.Ft int
+.Fn inet_aton "const char *cp" "struct in_addr *addr"
+.Ft in_addr_t
+.Fn inet_lnaof "struct in_addr in"
+.Ft struct in_addr
+.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
+.Ft in_addr_t
+.Fn inet_netof "struct in_addr in"
+.Ft in_addr_t
 .Fn inet_network "const char *cp"
 .Ft char *
 .Fn inet_ntoa "struct in_addr in"
-.Ft struct in_addr 
-.Fn inet_makeaddr "int net" "int lna"
-.Ft unsigned long 
-.Fn inet_lnaof "struct in_addr in"
-.Ft unsigned long 
-.Fn inet_netof "struct in_addr in"
+.Ft const char *
+.Fn inet_ntop "int af" "const void *src" "char *dst" "socklen_t size"
+.Ft int
+.Fn inet_pton "int af" "const char *src" "void *dst"
 .Sh DESCRIPTION
 The routines
 .Fn inet_aton ,
-.Fn inet_addr
+.Fn inet_addr ,
 and
 .Fn inet_network
 interpret character strings representing
 numbers expressed in the Internet standard
-.Ql \&.
+.Dq dot
 notation.
 The
+.Fn inet_pton
+function converts a presentation format address (that is, printable form
+as held in a character string) to network format (usually a
+.Li struct in_addr
+or some other internal binary representation, in network byte order).
+It returns 1 if the address was valid for the specified address family;
+0 if the address wasn't parseable in the specified address family; or \-1
+if some system error occurred (in which case
+.Va errno
+will have been set).
+This function is presently valid for
+.Dv AF_INET
+and
+.Dv AF_INET6 .
+The
 .Fn inet_aton
 routine interprets the specified character string as an Internet address,
 placing the address into the structure provided.
 It returns 1 if the string was successfully interpreted,
-or 0 if the string is invalid.
+or 0 if the string was invalid.
 The
 .Fn inet_addr
 and
@@ -86,17 +105,29 @@ and
 functions return numbers suitable for use
 as Internet addresses and Internet network
 numbers, respectively.
+.Pp
+The function
+.Fn inet_ntop
+converts an address from network format (usually a
+.Li struct in_addr
+or some other binary form, in network byte order) to presentation format
+(suitable for external display purposes).
+It returns
+.Dv NULL
+if a system
+error occurs (in which case,
+.Va errno
+will have been set), or it returns a pointer to the destination string.
 The routine
 .Fn inet_ntoa
 takes an Internet address and returns an
-.Tn ASCII
-string representing the address in
-.Ql \&.
-notation.  The routine
+ASCII string representing the address in dot notation.
+The routine
 .Fn inet_makeaddr
 takes an Internet network number and a local
 network address and constructs an Internet address
-from it.  The routines
+from it.
+The routines
 .Fn inet_netof
 and
 .Fn inet_lnaof
@@ -108,11 +139,8 @@ All Internet addresses are returned in network
 order (bytes ordered from left to right).
 All network numbers and local address parts are
 returned as machine format integer values.
-.Sh INTERNET ADDRESSES
-Values specified using the
-.Ql \&.
-notation take one
-of the following forms:
+.Sh INTERNET ADDRESSES (IP VERSION 4)
+Values specified using dot notation take one of the following forms:
 .Bd -literal -offset indent
 a.b.c.d
 a.b.c
@@ -122,28 +150,25 @@ a
 .Pp
 When four parts are specified, each is interpreted
 as a byte of data and assigned, from left to right,
-to the four bytes of an Internet address.  Note
-that when an Internet address is viewed as a 32-bit
-integer quantity on the
-.Tn VAX
-the bytes referred to
-above appear as
+to the four bytes of an Internet address.
+Note that when an Internet address is viewed as a 32-bit
+integer quantity on a system that uses little-endian
+byte order
+(such as the Intel 386, 486 and Pentium processors)
+the bytes referred to above appear as
 .Dq Li d.c.b.a .
-That is,
-.Tn VAX
-bytes are
-ordered from right to left.
+That is, little-endian bytes are ordered from right to left.
 .Pp
 When a three part address is specified, the last
 part is interpreted as a 16-bit quantity and placed
-in the right-most two bytes of the network address.
+in the rightmost two bytes of the network address.
 This makes the three part address format convenient
 for specifying Class B network addresses as
 .Dq Li 128.net.host .
 .Pp
 When a two part address is supplied, the last part
 is interpreted as a 24-bit quantity and placed in
-the right most three bytes of the network address.
+the rightmost three bytes of the network address.
 This makes the two part address format convenient
 for specifying Class A network addresses as
 .Dq Li net.host .
@@ -154,13 +179,88 @@ rearrangement.
 .Pp
 All numbers supplied as
 .Dq parts
-in a
-.Ql  \&.
-notation
+in a dot notation
 may be decimal, octal, or hexadecimal, as specified
 in the C language (i.e., a leading 0x or 0X implies
-hexadecimal; otherwise, a leading 0 implies octal;
+hexadecimal; a leading 0 implies octal;
 otherwise, the number is interpreted as decimal).
+.Sh INTERNET ADDRESSES (IP VERSION 6)
+In order to support scoped IPv6 addresses,
+.Xr getaddrinfo 3
+and
+.Xr getnameinfo 3
+are recommended rather than the functions presented here.
+.Pp
+The presentation format of an IPv6 address is given in RFC 2373:
+.Pp
+There are three conventional forms for representing IPv6 addresses as
+text strings:
+.Bl -enum
+.It
+The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
+hexadecimal values of the eight 16-bit pieces of the address.
+Examples:
+.Bd -literal -offset indent
+FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
+1080:0:0:0:8:800:200C:417A
+.Ed
+.Pp
+Note that it is not necessary to write the leading zeros in an
+individual field, but there must be at least one numeral in
+every field (except for the case described in 2.).
+.It
+Due to the method of allocating certain styles of IPv6
+addresses, it will be common for addresses to contain long
+strings of zero bits.
+In order to make writing addresses
+containing zero bits easier, a special syntax is available to
+compress the zeros.
+The use of
+.Dq \&:\&:
+indicates multiple groups
+of 16 bits of zeros.
+The
+.Dq \&:\&:
+can only appear once in an
+address.
+The
+.Dq \&:\&:
+can also be used to compress the leading and/or trailing zeros in an address.
+.Pp
+For example the following addresses:
+.Bd -literal -offset indent
+1080:0:0:0:8:800:200C:417A  a unicast address
+FF01:0:0:0:0:0:0:43         a multicast address
+0:0:0:0:0:0:0:1             the loopback address
+0:0:0:0:0:0:0:0             the unspecified addresses
+.Ed
+.Pp
+may be represented as:
+.Bd -literal -offset indent
+1080::8:800:200C:417A       a unicast address
+FF01::43                    a multicast address
+::1                         the loopback address
+::                          the unspecified addresses
+.Ed
+.It
+An alternative form that is sometimes more convenient when
+dealing with a mixed environment of IPv4 and IPv6 nodes is
+x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
+of the six high-order 16-bit pieces of the address, and the 'd's
+are the decimal values of the four low-order 8-bit pieces of the
+address (standard IPv4 representation).
+Examples:
+.Bd -literal -offset indent
+0:0:0:0:0:0:13.1.68.3
+0:0:0:0:0:FFFF:129.144.52.38
+.Ed
+.Pp
+or in compressed form:
+.Bd -literal -offset indent
+::13.1.68.3
+::FFFF:129.144.52.38
+.Ed
+.El
 .Sh DIAGNOSTICS
 The constant
 .Dv INADDR_NONE
@@ -170,28 +270,76 @@ and
 .Fn inet_network
 for malformed requests.
 .Sh SEE ALSO
+.Xr byteorder 3 ,
 .Xr gethostbyname 3 ,
 .Xr getnetent 3 ,
+.Xr inet_net 3 ,
 .Xr hosts 5 ,
-.Xr networks 5 ,
+.Xr networks 5
+.Rs
+.%R RFC 2373
+.%D July 1998
+.%T "IP Version 6 Addressing Architecture"
+.Re
+.Rs
+.%R RFC 3493
+.%D February 2003
+.%T "Basic Socket Interface Extensions for IPv6"
+.Re
+.Sh STANDARDS
+The
+.Nm inet_ntop
+and
+.Nm inet_pton
+functions conform to the IETF IPv6 BSD API and address formatting
+specifications.
+Note that
+.Nm inet_pton
+does not accept 1-, 2-, or 3-part dotted addresses; all four parts
+must be specified.
+This is a narrower input set than that accepted by
+.Nm inet_aton .
 .Sh HISTORY
-These
-functions appeared in 
+The
+.Nm inet_addr ,
+.Nm inet_network ,
+.Nm inet_makeaddr ,
+.Nm inet_lnaof ,
+and
+.Nm inet_netof
+functions appeared in
 .Bx 4.2 .
+The
+.Nm inet_aton
+and
+.Nm inet_ntoa
+functions appeared in
+.Bx 4.3 .
+The
+.Nm inet_pton
+and
+.Nm inet_ntop
+functions appeared in BIND 4.9.4.
 .Sh BUGS
 The value
 .Dv INADDR_NONE
 (0xffffffff) is a valid broadcast address, but
 .Fn inet_addr
 cannot return that value without indicating failure.
+Also,
+.Fn inet_addr
+should have been designed to return a
+.Li struct in_addr .
 The newer
 .Fn inet_aton
-function does not share this problem.
+function does not share these problems, and almost all existing code
+should be modified to use
+.Fn inet_aton
+instead.
+.Pp
 The problem of host byte ordering versus network byte ordering is
 confusing.
+.Pp
 The string returned by
 .Fn inet_ntoa
 resides in a static memory area.
-.Pp
-Inet_addr should return a
-.Fa struct in_addr .