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@

1 files changed, 85 insertions, 127 deletions

diff --git a/src/lib/libc/net/byteorder.3 b/src/lib/libc/net/byteorder.3
index 53f9fd071d..921c8343fa 100644
--- a/src/lib/libc/net/byteorder.3
+++ b/src/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.