usr/src/man/man3c/endian.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd January 30, 2016
  15 .Dt ENDIAN 3C
  16 .Os
  17 .Sh NAME
  18 .Nm endian ,
  19 .Nm be16toh ,
  20 .Nm be32toh ,
  21 .Nm be64toh ,
  22 .Nm betoh16 ,
  23 .Nm betoh32 ,
  24 .Nm betoh64 ,
  25 .Nm htobe16 ,
  26 .Nm htobe32 ,
  27 .Nm htobe64 ,
  28 .Nm htole16 ,
  29 .Nm htole32 ,
  30 .Nm htole64 ,
  31 .Nm le16toh ,
  32 .Nm le32toh ,
  33 .Nm le64toh ,
  34 .Nm letoh16 ,
  35 .Nm letoh32 ,
  36 .Nm letoh64
  37 .Nd convert between big and little endian byte order
  38 .Sh SYNOPSIS
  39 .In endian.h
  40 .Ft uint16_t
  41 .Fo be16toh
  42 .Fa "uint16_t be16"
  43 .Fc
  44 .Ft uint32_t
  45 .Fo be32toh
  46 .Fa "uint32_t be32"
  47 .Fc
  48 .Ft uint64_t
  49 .Fo betoh64
  50 .Fa "uint64_t be64"
  51 .Fc
  52 .Ft uint16_t
  53 .Fo betoh16
  54 .Fa "uint16_t be16"
  55 .Fc
  56 .Ft uint32_t
  57 .Fo betoh32
  58 .Fa "uint32_t be32"
  59 .Fc
  60 .Ft uint64_t
  61 .Fo be64toh
  62 .Fa "uint64_t be64"
  63 .Fc
  64 .Ft uint16_t
  65 .Fo htobe16
  66 .Fa "uint16_t host16"
  67 .Fc
  68 .Ft uint32_t
  69 .Fo htobe32
  70 .Fa "uint32_t host32"
  71 .Fc
  72 .Ft uint64_t
  73 .Fo htobe64
  74 .Fa "uint64_t host64"
  75 .Fc
  76 .Ft uint16_t
  77 .Fo htole16
  78 .Fa "uint16_t host16"
  79 .Fc
  80 .Ft uint32_t
  81 .Fo htole32
  82 .Fa "uint32_t host32"
  83 .Fc
  84 .Ft uint64_t
  85 .Fo htole64
  86 .Fa "uint64_t host64"
  87 .Fc
  88 .Ft uint16_t
  89 .Fo le16toh
  90 .Fa "uint16_t le16"
  91 .Fc
  92 .Ft uint32_t
  93 .Fo le32toh
  94 .Fa "uint32_t le32"
  95 .Fc
  96 .Ft uint64_t
  97 .Fo le64toh
  98 .Fa "uint64_t le64"
  99 .Fc
 100 .Ft uint16_t
 101 .Fo letoh16
 102 .Fa "uint16_t le16"
 103 .Fc
 104 .Ft uint32_t
 105 .Fo letoh32
 106 .Fa "uint32_t le32"
 107 .Fc
 108 .Ft uint64_t
 109 .Fo letoh64
 110 .Fa "uint64_t le64"
 111 .Fc
 112 .Sh DESCRIPTION
 113 The
 114 .Nm
 115 family of functions convert 16, 32, and 64-bit values between the host's
 116 native byte order and big- or little-endian.
 117 All of the functions in this family simply return their input when the host's
 118 native byte order is the same as the desired order.
 119 For more information on endianness, see
 120 .Xr byteorder 5 .
 121 .Pp
 122 The
 123 .Fn betoh16 ,
 124 .Fn betoh32 ,
 125 and
 126 .Fn betoh64
 127 functions take a 16-bit, 32-bit, or 64-bit value and convert it from
 128 big-endian to the host's native endianness, swapping bytes as required.
 129 .Pp
 130 The
 131 .Fn letoh16 ,
 132 .Fn letoh32 ,
 133 and
 134 .Fn letoh64
 135 functions take a 16-bit, 32-bit, or 64-bit value and convert it from
 136 little-endian to the host's native endianness, swapping bytes as
 137 required.
 138 .Pp
 139 The
 140 .Fn htobe16 ,
 141 .Fn htobe32 ,
 142 and
 143 .Fn htobe64
 144 functions take a 16-bit, 32-bit, or 64-bit value and convert it from
 145 the host's native endianness to big-endian, swapping bytes as required.
 146 .Pp
 147 The
 148 .Fn htole16 ,
 149 .Fn htole32 ,
 150 and
 151 .Fn htole64
 152 functions take a 16-bit, 32-bit, or 64-bit value and convert it from
 153 the host's native endianness to little-endian, swapping bytes as
 154 required.
 155 .Pp
 156 The functions
 157 .Fn be16toh ,
 158 .Fn be32toh ,
 159 .Fn be64toh ,
 160 .Fn le16toh ,
 161 .Fn le32toh ,
 162 and
 163 .Fn le64toh ,
 164 are the same as
 165 .Fn betoh16 ,
 166 .Fn betoh32 ,
 167 .Fn betoh64 ,
 168 .Fn letoh16 ,
 169 .Fn letoh32 ,
 170 and
 171 .Fn letoh64
 172 respectively.
 173 Historically, different platforms have diverged on the naming of these
 174 functions.
 175 To better support extant software, both are provided.
 176 .Pp
 177 While these functions are common across multiple platforms, they have
 178 not been standardized.
 179 Portable applications should instead use the functions defined in
 180 .Xr byteorder 3C .
 181 .Sh RETURN VALUES
 182 The functions always succeed and return a value that has been properly
 183 converted.
 184 .Sh INTERFACE STABILITY
 185 .Sy Committed
 186 .Sh MT-LEVEL
 187 .Sy MT-Safe
 188 .Sh SEE ALSO
 189 .Xr byteorder 3C ,
 190 .Xr endian.h 3HEAD ,
 191 .Xr attributes 5 ,
 192 .Xr byteorder 5