From a507f9dd9387923514b8801e5f4424765bf792d1 Mon Sep 17 00:00:00 2001 From: guenther <> Date: Sun, 13 Jul 2014 13:17:16 +0000 Subject: Split out ntoh[ls] and hton[ls] into their own manpage. Update byteorder(3) to cover the new functions in ok deraadt@ millert@ --- src/lib/libc/net/byteorder.3 | 212 +++++++++++++++++-------------------------- 1 file changed, 85 insertions(+), 127 deletions(-) (limited to 'src/lib/libc/net/byteorder.3') 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. -- cgit v1.2.3-55-g6feb