Split out ntoh[ls] and hton[ls] into their own manpage.

Update byteorder(3) to cover the new functions in <endian.h>

ok deraadt@ millert@

3 files changed, 199 insertions, 136 deletions

diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc
index b3acad72bfd..6b427174d8d 100644
--- a/lib/libc/net/Makefile.inc
+++ b/lib/libc/net/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.54 2014/06/11 16:59:47 chrisz Exp $
+#	$OpenBSD: Makefile.inc,v 1.55 2014/07/13 13:17:16 guenther Exp $
 
 # net sources
 .PATH: ${LIBCSRCDIR}/arch/${MACHINE_CPU}/net ${LIBCSRCDIR}/net
@@ -27,18 +27,18 @@ SRCS+=	ip6opt.c rthdr.c vars6.c
 
 MAN+=	byteorder.3 ethers.3 gai_strerror.3 getaddrinfo.3 gethostbyname.3 \
 	getifaddrs.3 getnameinfo.3 getnetent.3 getpeereid.3 getprotoent.3 \
-	getrrsetbyname.3 getservent.3 if_indextoname.3 \
+	getrrsetbyname.3 getservent.3 htonl.3 if_indextoname.3 \
 	inet_addr.3 inet_lnaof.3 inet_net.3 inet_ntop.3 \
 	inet6_opt_init.3 inet6_rth_space.3 link_addr.3 \
 	rcmd.3 rcmdsh.3 resolver.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 \
-	byteorder.3 htobe64.3 byteorder.3 betoh16.3 byteorder.3 betoh32.3 \
-	byteorder.3 betoh64.3 byteorder.3 htole16.3 byteorder.3 htole32.3 \
-	byteorder.3 htole64.3 byteorder.3 letoh16.3 byteorder.3 letoh32.3 \
-	byteorder.3 letoh64.3 byteorder.3 swap16.3 byteorder.3 swap32.3 \
-	byteorder.3 swap64.3
+MLINKS+=byteorder.3 htobe16.3 byteorder.3 htobe32.3 byteorder.3 htobe64.3 \
+	byteorder.3 be16toh.3 byteorder.3 be32toh.3 byteorder.3 be64toh.3 \
+	byteorder.3 betoh16.3 byteorder.3 betoh32.3 byteorder.3 betoh64.3 \
+	byteorder.3 htole16.3 byteorder.3 htole32.3 byteorder.3 htole64.3 \
+	byteorder.3 le16toh.3 byteorder.3 le32toh.3 byteorder.3 le64toh.3 \
+	byteorder.3 letoh16.3 byteorder.3 letoh32.3 byteorder.3 letoh64.3 \
+	byteorder.3 swap16.3 byteorder.3 swap32.3 byteorder.3 swap64.3
 MLINKS+=ethers.3 ether_aton.3 ethers.3 ether_hostton.3 ethers.3 ether_line.3 \
 	ethers.3 ether_ntoa.3 ethers.3 ether_ntohost.3
 MLINKS+=getaddrinfo.3 freeaddrinfo.3
@@ -59,6 +59,7 @@ MLINKS+=getservent.3 endservent.3 getservent.3 getservbyname.3 \
 	getservent.3 getservent_r.3 getservent.3 getservbyname_r.3 \
 	getservent.3 getservbyport_r.3 getservent.3 setservent_r.3 \
 	getservent.3 endservent_r.3
+MLINKS+=htonl.3 htons.3 htonl.3 ntohl.3 htonl.3 ntohs.3
 MLINKS+= if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
 	if_indextoname.3 if_freenameindex.3
 MLINKS+=inet_addr.3 inet_aton.3 inet_addr.3 inet_network.3 \
diff --git a/lib/libc/net/byteorder.3 b/lib/libc/net/byteorder.3
index 53f9fd071d5..921c8343fa7 100644
--- a/lib/libc/net/byteorder.3
+++ b/lib/libc/net/byteorder.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: byteorder.3,v 1.18 2013/06/05 03:39:22 tedu Exp $
+.\"	$OpenBSD: byteorder.3,v 1.19 2014/07/13 13:17:16 guenther Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,23 +27,25 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 5 2013 $
+.Dd $Mdocdate: July 13 2014 $
 .Dt BYTEORDER 3
 .Os
 .Sh NAME
-.Nm htonl ,
-.Nm htons ,
-.Nm ntohl ,
-.Nm ntohs ,
 .Nm htobe64 ,
 .Nm htobe32 ,
 .Nm htobe16 ,
+.Nm be64toh ,
+.Nm be32toh ,
+.Nm be16toh ,
 .Nm betoh64 ,
 .Nm betoh32 ,
 .Nm betoh16 ,
 .Nm htole64 ,
 .Nm htole32 ,
 .Nm htole16 ,
+.Nm le64toh ,
+.Nm le32toh ,
+.Nm le16toh ,
 .Nm letoh64 ,
 .Nm letoh32 ,
 .Nm letoh16 ,
@@ -52,45 +54,49 @@
 .Nm swap16
 .Nd convert values between different byte orderings
 .Sh SYNOPSIS
-.In sys/types.h
-.Ft u_int32_t
-.Fn htonl "u_int32_t host32"
-.Ft u_int16_t
-.Fn htons "u_int16_t host16"
-.Ft u_int32_t
-.Fn ntohl "u_int32_t net32"
-.Ft u_int16_t
-.Fn ntohs "u_int16_t net16"
-.Ft u_int64_t
-.Fn htobe64 "u_int64_t host64"
-.Ft u_int32_t
-.Fn htobe32 "u_int32_t host32"
-.Ft u_int16_t
-.Fn htobe16 "u_int16_t host16"
-.Ft u_int64_t
-.Fn betoh64 "u_int64_t big64"
-.Ft u_int32_t
-.Fn betoh32 "u_int32_t big32"
-.Ft u_int16_t
-.Fn betoh16 "u_int16_t big16"
-.Ft u_int64_t
-.Fn htole64 "u_int64_t host64"
-.Ft u_int32_t
-.Fn htole32 "u_int32_t host32"
-.Ft u_int16_t
-.Fn htole16 "u_int16_t host16"
-.Ft u_int64_t
-.Fn letoh64 "u_int64_t little64"
-.Ft u_int32_t
-.Fn letoh32 "u_int32_t little32"
-.Ft u_int16_t
-.Fn letoh16 "u_int16_t little16"
-.Ft u_int64_t
-.Fn swap64 "u_int64_t val64"
-.Ft u_int32_t
-.Fn swap32 "u_int32_t val32"
-.Ft u_int16_t
-.Fn swap16 "u_int16_t val16"
+.In endian.h
+.Ft uint64_t
+.Fn htobe64 "uint64_t host64"
+.Ft uint32_t
+.Fn htobe32 "uint32_t host32"
+.Ft uint16_t
+.Fn htobe16 "uint16_t host16"
+.Ft uint64_t
+.Fn be64toh "uint64_t big64"
+.Ft uint32_t
+.Fn be32toh "uint32_t big32"
+.Ft uint16_t
+.Fn be16toh "uint16_t big16"
+.Ft uint64_t
+.Fn betoh64 "uint64_t big64"
+.Ft uint32_t
+.Fn betoh32 "uint32_t big32"
+.Ft uint16_t
+.Fn betoh16 "uint16_t big16"
+.Ft uint64_t
+.Fn htole64 "uint64_t host64"
+.Ft uint32_t
+.Fn htole32 "uint32_t host32"
+.Ft uint16_t
+.Fn htole16 "uint16_t host16"
+.Ft uint64_t
+.Fn letoh64 "uint64_t little64"
+.Ft uint64_t
+.Fn le64toh "uint64_t little64"
+.Ft uint32_t
+.Fn le32toh "uint32_t little32"
+.Ft uint16_t
+.Fn le16toh "uint16_t little16"
+.Ft uint32_t
+.Fn letoh32 "uint32_t little32"
+.Ft uint16_t
+.Fn letoh16 "uint16_t little16"
+.Ft uint64_t
+.Fn swap64 "uint64_t val64"
+.Ft uint32_t
+.Fn swap32 "uint32_t val32"
+.Ft uint16_t
+.Fn swap16 "uint16_t val16"
 .Sh DESCRIPTION
 These routines convert 16, 32 and 64-bit quantities between different
 byte orderings.
@@ -101,70 +107,16 @@ the given quantity; the others convert either from/to the native
 byte order used by the host to/from either little- or big-endian (a.k.a
 network) order.
 .Pp
-Apart from the swap functions, the names can be described by this form:
-{src-order}to{dst-order}{size}.
-Both {src-order} and {dst-order} can take the following forms:
-.Pp
-.Bl -tag -width "be " -offset indent -compact
-.It h
-Host order.
-.It n
-Network order (big-endian).
-.It be
-Big-endian (most significant byte first).
-.It le
-Little-endian (least significant byte first).
-.El
-.Pp
-One of the specified orderings must be
-.Sq h .
-{size} will take these forms:
-.Pp
-.Bl -tag -width "32 " -offset indent -compact
-.It l
-Long (32-bit, used in conjunction with forms involving
-.Sq n ) .
-.It s
-Short (16-bit, used in conjunction with forms involving
-.Sq n ) .
-.It 16
-16-bit.
-.It 32
-32-bit.
-.It 64
-64-bit.
-.El
-.Pp
-The swap functions are of the form: swap{size}.
-.Pp
-Names involving
-.Sq n
-convert quantities between network
-byte order and host byte order.
-The last letter
-.Pf ( Sq s
-or
-.Sq l )
-is a mnemonic
-for the traditional names for such quantities,
-.Li short
-and
-.Li long ,
-respectively.
-Today, the C concept of
-.Li short
-and
-.Li long
-integers need not coincide with this traditional misunderstanding.
-On machines which have a byte order which is the same as the network
-order, routines are defined as null macros.
+Apart from the swap functions,
+the names containing
+.Dq be
+convert between host and big-endian (most significant byte first) order
+of the given quantity, while the names containing
+.Dq le
+convert between host and little-endian least significant byte first) order
+of the given quantity.
 .Pp
-The functions involving either
-.Dq be ,
-.Dq le ,
-or
-.Dq swap
-use the numbers
+All these functions use the numbers
 16, 32, or 64 for specifying the bitwidth of the quantities they operate on.
 Currently all supported architectures are either big- or little-endian
 so either the
@@ -172,34 +124,40 @@ so either the
 or
 .Dq le
 variants are implemented as null macros.
-.Pp
-The routines mentioned above which have either {src-order} or {dst-order}
-set to
-.Sq n
-are most often used in
-conjunction with Internet addresses and ports as returned by
-.Xr gethostbyname 3
-and
-.Xr getservent 3 .
 .Sh SEE ALSO
-.Xr gethostbyname 3 ,
-.Xr getservent 3
+.Xr htonl 3
 .Sh STANDARDS
 The
-.Fn htonl ,
-.Fn htons ,
-.Fn ntohl ,
+.Fn htobe64 ,
+.Fn htobe32 ,
+.Fn htobe16 ,
+.Fn be64toh ,
+.Fn be32toh ,
+.Fn be16toh ,
+.Fn htole64 ,
+.Fn htole32 ,
+.Fn htole16 ,
+.Fn le64toh ,
+.Fn le32toh ,
 and
-.Fn ntohs
-functions conform to
+.Fn le16toh
+functions are expected to conform to a future version of
 .St -p1003.1 .
-The other functions are extensions that should not be used when portability
-is required.
+The other functions are extensions that should not be used
+when portability is required.
 .Sh HISTORY
 The
-.Nm byteorder
+.Nm swap{size}
+and
+.Nm {src-order}to{dst-order}{size}
 functions appeared in
 .Bx 4.2 .
+The
+.Nm {src-order}{size}to{dst-order}
+functions appeared in
+.Ox 5.6 .
+A subset of them was submitted for standardization after
+.St -p1003.1-2008 .
 .Sh BUGS
 On the vax, alpha, amd64, i386, and some mips and arm architectures,
 bytes are handled backwards from most everyone else in the world.
diff --git a/lib/libc/net/htonl.3 b/lib/libc/net/htonl.3
new file mode 100644
index 00000000000..fdc84cb64ca
--- /dev/null
+++ b/lib/libc/net/htonl.3
@@ -0,0 +1,104 @@
+.\"	$OpenBSD: htonl.3,v 1.1 2014/07/13 13:17:16 guenther Exp $
+.\"
+.\" 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. 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.
+.\"
+.Dd $Mdocdate: July 13 2014 $
+.Dt HTONL 3
+.Os
+.Sh NAME
+.Nm htonl ,
+.Nm htons ,
+.Nm ntohl ,
+.Nm ntohs
+.Nd convert values between host and network byte orderings
+.Sh SYNOPSIS
+.In netinet/in.h
+.Ft uint32_t
+.Fn htonl "uint32_t host32"
+.Ft uint16_t
+.Fn htons "uint16_t host16"
+.Ft uint32_t
+.Fn ntohl "uint32_t net32"
+.Ft uint16_t
+.Fn ntohs "uint16_t net16"
+.Sh DESCRIPTION
+These routines convert 16 and 32-bit quantities between different
+byte orderings.
+.Pp
+The
+.Fn htonl
+and
+.Fn htons
+functions convert quantities from host to network byte order while the
+.Fn ntohl
+and
+.Fn ntohs
+functions convert the other direction.
+.Pp
+The last letter
+.Pf ( Sq s
+or
+.Sq l )
+is a mnemonic
+for the traditional names for such quantities,
+.Li short
+and
+.Li long ,
+respectively.
+Today, the C concept of
+.Li short
+and
+.Li long
+integers need not coincide with this traditional misunderstanding.
+On machines which have a byte order which is the same as the network
+order, routines are defined as null macros.
+.Pp
+These routines are most often used in conjunction with Internet
+addresses and ports as returned by
+.Xr gethostbyname 3
+and
+.Xr getservent 3 .
+.Sh SEE ALSO
+.Xr gethostbyname 3 ,
+.Xr getservent 3
+.Sh STANDARDS
+The
+.Fn htonl ,
+.Fn htons ,
+.Fn ntohl ,
+and
+.Fn ntohs
+functions conform to
+.St -p1003.1 .
+.Sh HISTORY
+These functions appeared in
+.Bx 4.2 .
+.Sh BUGS
+On the vax, alpha, amd64, i386, and some mips and arm architectures,
+bytes are handled backwards from most everyone else in the world.
+This is not expected to be fixed in the near future.