chiark - git - mdw - mLib/blob - man/bits.3

   1 .\" -*-nroff-*-
   2 .TH bits 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 bits \- portable bit manipulation macros
   5 .\" @U8
   6 .\" @U16
   7 .\" @U32
   8 .\"
   9 .\" @LSL8
  10 .\" @LSR8
  11 .\" @LSL16
  12 .\" @LSR16
  13 .\" @LSL32
  14 .\" @LSR32
  15 .\"
  16 .\" @ROL8
  17 .\" @ROR8
  18 .\" @ROL16
  19 .\" @ROR16
  20 .\" @ROL32
  21 .\" @ROR32
  22 .\"
  23 .\" @GETBYTE
  24 .\" @PUTBYTE
  25 .\"
  26 .\" @LOAD8
  27 .\" @STORE8
  28 .\"
  29 .\" @LOAD16_L
  30 .\" @LOAD16_B
  31 .\" @LOAD16
  32 .\" @STORE16_L
  33 .\" @STORE16_B
  34 .\" @STORE16
  35 .\"
  36 .\" @LOAD32_L
  37 .\" @LOAD32_B
  38 .\" @LOAD32
  39 .\" @STORE32_L
  40 .\" @STORE32_B
  41 .\" @STORE32
  42 .\"
  43 .SH SYNOPSIS
  44 .nf
  45 .B "#include <mLib/bits.h>"
  46
  47 .BI "octet U8(" v );
  48 .BI "uint16 U16(" v );
  49 .BI "uint32 U32(" v );
  50
  51 .BI "octet LSL8(" v ", " s );
  52 .BI "octet LSR8(" v ", " s );
  53 .BI "uint16 LSL16(" v ", " s );
  54 .BI "uint16 LSR16(" v ", " s );
  55 .BI "uint32 LSL32(" v ", " s );
  56 .BI "uint32 LSR32(" v ", " s );
  57
  58 .BI "octet ROL8(" v ", " s );
  59 .BI "octet ROR8(" v ", " s );
  60 .BI "uint16 ROL16(" v ", " s );
  61 .BI "uint16 ROR16(" v ", " s );
  62 .BI "uint32 ROL32(" v ", " s );
  63 .BI "uint32 ROR32(" v ", " s );
  64
  65 .BI "octet GETBYTE(" p ", " o );
  66 .BI "void PUTBYTE(" p ", " o ", " v );
  67
  68 .BI "octet LOAD8(" p );
  69 .BI "void STORE8(" p ", " v );
  70
  71 .BI "uint16 LOAD16_B(" p );
  72 .BI "uint16 LOAD16_L(" p );
  73 .BI "uint16 LOAD16(" p );
  74 .BI "void STORE16_B(" p ", " v );
  75 .BI "void STORE16_L(" p ", " v );
  76 .BI "void STORE16(" p ", " v );
  77
  78 .BI "uint32 LOAD32_B(" p );
  79 .BI "uint32 LOAD32_L(" p );
  80 .BI "uint32 LOAD32(" p );
  81 .BI "void STORE32_B(" p ", " v );
  82 .BI "void STORE32_L(" p ", " v );
  83 .BI "void STORE32(" p ", " v );
  84 .fi
  85 .SH DESCRIPTION
  86 The header file
  87 .B <mLib/bits.h>
  88 contains a number of useful definitions for portably dealing with bit-
  89 and byte-level manipulation of larger quantities.  It declares three
  90 types:
  91 .TP
  92 .B octet
  93 Equivalent to
  94 .BR "unsigned char" .
  95 This is intended to be used when a character array is used to represent
  96 the octets of some external data format.  Note that on some
  97 architectures the
  98 .B "unsigned char"
  99 type may occupy more than 8 bits.
 100 .TP
 101 .B uint16
 102 Equivalent to
 103 .BR "unsigned short" .
 104 Intended to be used when a 16-bit value is required.  This type is
 105 always capable of representing any 16-bit unsigned value, but the actual
 106 type may be wider than 16 bits and will require masking.
 107 .TP
 108 .B uint32
 109 Equivalent to some (architecture-dependent) standard type.  Capable of
 110 representing any unsigned 32-bit value, although the the actual type may
 111 be wider than 32 bits.
 112 .PP
 113 The constants
 114 .BR MASK8 ,
 115 .B MASK16
 116 and
 117 .B MASK32
 118 contain bitmasks appropriate for discarding additional bits from a value
 119 before use as an 8-, 16- or 32-bit quantity.  The macros
 120 .BR U8 ,
 121 .B U16
 122 and
 123 .B U32
 124 perform masking and type-coercion on a value, and may be more useful in
 125 general.  For example,
 126 .B U16(x)
 127 yields a value of type
 128 .B uint16
 129 which contains (only) the least-significant 16 bits of
 130 .BR x .
 131 .PP
 132 The macros
 133 .BI LSL n
 134 and
 135 .BI LSR n
 136 perform left and right logical shift operations on values of width
 137 .IR n ,
 138 where
 139 .I n
 140 is one of
 141 .BR 8 ,
 142 .B 16
 143 or
 144 .BR 32 .
 145 The first argument, written
 146 .IR v ,
 147 is the value to shift, and the second, written
 148 .IR s ,
 149 is the number of bits to shift.  The value
 150 .I s
 151 is reduced modulo
 152 .I n
 153 before use.  Similarly, the macros
 154 .BI ROL n
 155 and
 156 .BI ROR n
 157 perform left and right rotations (cyclic shifts) on values of width
 158 .IR n .
 159 These macros are all written in such a way as to maximize portability.
 160 A compiler may be able to spot that simple machine instructions will
 161 suffice in many cases, although that's not the main objective.
 162 .PP
 163 The macros
 164 .BI LOAD n
 165 and
 166 .BI STORE n
 167 (where again
 168 .I n
 169 is one of
 170 .BR 8 ,
 171 .B 16
 172 or
 173 .BR 32 )
 174 perform transformations between
 175 .IR n -bit
 176 quantities and arrays of octets.  For example,
 177 .B LOAD32(q)
 178 returns the 32-bit value stored in the four octets starting at address
 179 .BR q ,
 180 and
 181 .B STORE16(q, x)
 182 stores the 16-bit value
 183 .B x
 184 in the 2 octets starting at address
 185 .BR q .
 186 Values are loaded and stored such that the most significant octet is
 187 assigned the lowest address (i.e., they use network, or big-endian byte
 188 order).  Macros
 189 .BI LOAD n _L
 190 and
 191 .BI STORE n _L
 192 are also provided for
 193 .I n
 194 either
 195 .B 16
 196 or
 197 .BR 32 :
 198 they use little-endian byte order.  There are
 199 explicit big-endian macros
 200 .BI LOAD n _B
 201 and
 202 .BI STORE n _B
 203 too.  The pointer arguments don't have to be pointers to octets; the
 204 value arguments don't have to be of the right type.  The macros perform
 205 all appropriate type casting and masking.  Again, these macros are
 206 written with portability foremost in mind, although it seems they don't
 207 actually perform at all badly in real use.
 208 .SH "SEE ALSO"
 209 .BR mLib (3).
 210 .SH AUTHOR
 211 Mark Wooding, <mdw@nsict.org>
 212