1.\" $OpenBSD: byteorder.3,v 1.14 2005/07/22 04:50:51 jaredy Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd June 4, 1993 31.Dt BYTEORDER 3 32.Os 33.Sh NAME 34.Nm htonl , 35.Nm htons , 36.Nm ntohl , 37.Nm ntohs , 38.Nm htobe64 , 39.Nm htobe32 , 40.Nm htobe16 , 41.Nm betoh64 , 42.Nm betoh32 , 43.Nm betoh16 , 44.Nm htole64 , 45.Nm htole32 , 46.Nm htole16 , 47.Nm letoh64 , 48.Nm letoh32 , 49.Nm letoh16 , 50.Nm swap64 , 51.Nm swap32 , 52.Nm swap16 53.Nd convert values between different byte orderings 54.Sh SYNOPSIS 55.Fd #include <sys/types.h> 56.Ft u_int32_t 57.Fn htonl "u_int32_t host32" 58.Ft u_int16_t 59.Fn htons "u_int16_t host16" 60.Ft u_int32_t 61.Fn ntohl "u_int32_t net32" 62.Ft u_int16_t 63.Fn ntohs "u_int16_t net16" 64.Ft u_int64_t 65.Fn htobe64 "u_int64_t host64" 66.Ft u_int32_t 67.Fn htobe32 "u_int32_t host32" 68.Ft u_int16_t 69.Fn htobe16 "u_int16_t host16" 70.Ft u_int64_t 71.Fn betoh64 "u_int64_t big64" 72.Ft u_int32_t 73.Fn betoh32 "u_int32_t big32" 74.Ft u_int16_t 75.Fn betoh16 "u_int16_t big16" 76.Ft u_int64_t 77.Fn htole64 "u_int64_t host64" 78.Ft u_int32_t 79.Fn htole32 "u_int32_t host32" 80.Ft u_int16_t 81.Fn htole16 "u_int16_t host16" 82.Ft u_int64_t 83.Fn letoh64 "u_int64_t little64" 84.Ft u_int32_t 85.Fn letoh32 "u_int32_t little32" 86.Ft u_int16_t 87.Fn letoh16 "u_int16_t little16" 88.Ft u_int64_t 89.Fn swap64 "u_int32_t val64" 90.Ft u_int32_t 91.Fn swap32 "u_int32_t val32" 92.Ft u_int16_t 93.Fn swap16 "u_int16_t val16" 94.Sh DESCRIPTION 95These routines convert 16, 32 and 64-bit quantities between different 96byte orderings. 97The 98.Dq swap 99functions reverse the byte ordering of 100the given quantity; the others convert either from/to the native 101byte order used by the host to/from either little- or big-endian (a.k.a 102network) order. 103.Pp 104Apart from the swap functions, the names can be described by this form: 105{src-order}to{dst-order}{size}. 106Both {src-order} and {dst-order} can take the following forms: 107.Pp 108.Bl -tag -width "be " -offset indent -compact 109.It h 110Host order. 111.It n 112Network order (big-endian). 113.It be 114Big-endian (most significant byte first). 115.It le 116Little-endian (least significant byte first). 117.El 118.Pp 119One of the specified orderings must be 120.Sq h . 121{size} will take these forms: 122.Pp 123.Bl -tag -width "32 " -offset indent -compact 124.It l 125Long (32-bit, used in conjunction with forms involving 126.Sq n ) . 127.It s 128Short (16-bit, used in conjunction with forms involving 129.Sq n ) . 130.It 16 13116-bit. 132.It 32 13332-bit. 134.It 64 13564-bit. 136.El 137.Pp 138The swap functions are of the form: swap{size}. 139.Pp 140Names involving 141.Sq n 142convert quantities between network 143byte order and host byte order. 144The last letter 145.Pf ( Sq s 146or 147.Sq l ) 148is a mnemonic 149for the traditional names for such quantities, 150.Li short 151and 152.Li long , 153respectively. 154Today, the C concept of 155.Li short 156and 157.Li long 158integers need not coincide with this traditional misunderstanding. 159On machines which have a byte order which is the same as the network 160order, routines are defined as null macros. 161.Pp 162The functions involving either 163.Dq be , 164.Dq le , 165or 166.Dq swap 167use the numbers 16816, 32, or 64 for specifying the bitwidth of the quantities they operate on. 169Currently all supported architectures are either big- or little-endian 170so either the 171.Dq be 172or 173.Dq le 174variants are implemented as null macros. 175.Pp 176The routines mentioned above which have either {src-order} or {dst-order} 177set to 178.Sq n 179are most often used in 180conjunction with Internet addresses and ports as returned by 181.Xr gethostbyname 3 182and 183.Xr getservent 3 . 184.Sh SEE ALSO 185.Xr gethostbyname 3 , 186.Xr getservent 3 187.Sh STANDARDS 188The 189.Fn htonl , 190.Fn htons , 191.Fn ntohl , 192and 193.Fn ntohs 194functions conform to 195.St -p1003.1 . 196The other functions are extensions that should not be used when portability 197is required. 198.Sh HISTORY 199The 200.Nm byteorder 201functions appeared in 202.Bx 4.2 . 203.Sh BUGS 204On the vax, alpha, i386, and some mips architectures, 205bytes are handled backwards from most everyone else in the world. 206This is not expected to be fixed in the near future. 207