From 49d8a62b3570cdf4248e91192daa206258fdd193 Mon Sep 17 00:00:00 2001 From: guenther Date: Sun, 13 Jul 2014 13:17:16 +0000 Subject: [PATCH] Split out ntoh[ls] and hton[ls] into their own manpage. Update byteorder(3) to cover the new functions in ok deraadt@ millert@ --- lib/libc/net/Makefile.inc | 19 ++-- lib/libc/net/byteorder.3 | 212 +++++++++++++++----------------------- lib/libc/net/htonl.3 | 104 +++++++++++++++++++ 3 files changed, 199 insertions(+), 136 deletions(-) create mode 100644 lib/libc/net/htonl.3 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. -- 2.20.1