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

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