share/man/man9/byteorder.9

   1 .\"     $NetBSD: byteorder.9,v 1.3 2009/04/10 23:30:57 tsutsui Exp $
   2 .\"
   3 .\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org>
   4 .\" 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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man9/byteorder.9,v 1.6 2003/05/21 17:32:55 ru Exp $
  28 .\"
  29 .Dd April 10, 2009
  30 .Dt BYTEORDER 9
  31 .Os
  32 .Sh NAME
  33 .Nm bswap16 ,
  34 .Nm bswap32 ,
  35 .Nm bswap64 ,
  36 .Nm be16toh ,
  37 .Nm be32toh ,
  38 .Nm be64toh ,
  39 .Nm htobe16 ,
  40 .Nm htobe32 ,
  41 .Nm htobe64 ,
  42 .Nm htole16 ,
  43 .Nm htole32 ,
  44 .Nm htole64 ,
  45 .Nm le16toh ,
  46 .Nm le32toh ,
  47 .Nm le64toh ,
  48 .Nm be16enc ,
  49 .Nm be16dec ,
  50 .Nm be32enc ,
  51 .Nm be32dec ,
  52 .Nm be64enc ,
  53 .Nm be64dec ,
  54 .Nm le16enc ,
  55 .Nm le16dec ,
  56 .Nm le32enc ,
  57 .Nm le32dec ,
  58 .Nm le64enc ,
  59 .Nm le64dec
  60 .Nd byte order operations
  61 .Sh SYNOPSIS
  62 .In sys/endian.h
  63 .Ft uint16_t
  64 .Fn bswap16 "uint16_t int16"
  65 .Ft uint32_t
  66 .Fn bswap32 "uint32_t int32"
  67 .Ft uint64_t
  68 .Fn bswap64 "uint64_t int64"
  69 .Ft uint16_t
  70 .Fn be16toh "uint16_t big16"
  71 .Ft uint32_t
  72 .Fn be32toh "uint32_t big32"
  73 .Ft uint64_t
  74 .Fn be64toh "uint64_t big64"
  75 .Ft uint16_t
  76 .Fn htobe16 "uint16_t host16"
  77 .Ft uint32_t
  78 .Fn htobe32 "uint32_t host32"
  79 .Ft uint64_t
  80 .Fn htobe64 "uint64_t host64"
  81 .Ft uint16_t
  82 .Fn htole16 "uint16_t host16"
  83 .Ft uint32_t
  84 .Fn htole32 "uint32_t host32"
  85 .Ft uint64_t
  86 .Fn htole64 "uint64_t host64"
  87 .Ft uint16_t
  88 .Fn le16toh "uint16_t little16"
  89 .Ft uint32_t
  90 .Fn le32toh "uint32_t little32"
  91 .Ft uint64_t
  92 .Fn le64toh "uint64_t little64"
  93 .Ft uint16_t
  94 .Fn be16dec "const void *stream"
  95 .Ft uint32_t
  96 .Fn be32dec "const void *stream"
  97 .Ft uint64_t
  98 .Fn be64dec "const void *stream"
  99 .Ft uint16_t
 100 .Fn le16dec "const void *stream"
 101 .Ft uint32_t
 102 .Fn le32dec "const void *stream"
 103 .Ft uint64_t
 104 .Fn le64dec "const void *stream"
 105 .Ft void
 106 .Fn be16enc "void *stream" "uint16_t host16"
 107 .Ft void
 108 .Fn be32enc "void *stream" "uint32_t host32"
 109 .Ft void
 110 .Fn be64enc "void *stream" "uint64_t host64"
 111 .Ft void
 112 .Fn le16enc "void *stream" "uint16_t host16"
 113 .Ft void
 114 .Fn le32enc "void *stream" "uint32_t host32"
 115 .Ft void
 116 .Fn le64enc "void *stream" "uint64_t host64"
 117 .Sh DESCRIPTION
 118 The
 119 .Fn bswap16 ,
 120 .Fn bswap32 ,
 121 and
 122 .Fn bswap64
 123 functions return a byte order swapped integer.
 124 On big endian systems, the number is converted to little endian byte order.
 125 On little endian systems, the number is converted to big endian byte order.
 126 .Pp
 127 The
 128 .Fn be16toh ,
 129 .Fn be32toh ,
 130 and
 131 .Fn be64toh
 132 functions return a big endian byte ordered integer
 133 converted to the system's native byte order.
 134 The return value will be the same as the argument on big endian systems.
 135 .Pp
 136 The
 137 .Fn le16toh ,
 138 .Fn le32toh ,
 139 and
 140 .Fn le64toh
 141 functions return a little endian byte ordered integer
 142 converted to the system's native byte order.
 143 The return value will be the same as the argument on little endian systems.
 144 .Pp
 145 The
 146 .Fn htobe16 ,
 147 .Fn htobe32 ,
 148 and
 149 .Fn htobe64
 150 functions return an integer in the system's native
 151 byte order converted to big endian byte order.
 152 The return value will be the same as the argument on big endian systems.
 153 .Pp
 154 The
 155 .Fn htole16 ,
 156 .Fn htole32 ,
 157 and
 158 .Fn htole64
 159 functions return an integer in the system's native
 160 byte order converted to little endian byte order.
 161 The return value will be the same as the argument on little endian systems.
 162 .Pp
 163 The
 164 .Fn be16enc ,
 165 .Fn be16dec ,
 166 .Fn be32enc ,
 167 .Fn be32dec ,
 168 .Fn be64enc ,
 169 .Fn be64dec ,
 170 .Fn le16enc ,
 171 .Fn le16dec ,
 172 .Fn le32enc ,
 173 .Fn le32dec ,
 174 .Fn le64enc ,
 175 and
 176 .Fn le64dec
 177 functions encode and decode integers to/from octet stream
 178 on any alignment in big/little endian format.
 179 .Sh SEE ALSO
 180 .Xr byteorder 3
 181 .Sh HISTORY
 182 The
 183 .Fn hto*
 184 and
 185 .Fn *toh
 186 functions first appeared in
 187 .Nx 1.5 .
 188 These functions were introduced to handle PCI bus master devices which assumed
 189 host's memory used to pass integer parameters via DMA transfer was
 190 always little endian even on big endian systems.
 191 .Pp
 192 The encode/decode functions first appeared in
 193 .Fx 5.1 ,
 194 and ported to
 195 .Nx 3.0
 196 as a part of
 197 .Xr uuidgen 2
 198 support.
 199 .Sh AUTHORS
 200 This manual page was written by
 201 .An Mike Barcroft Aq mike@FreeBSD.org .