+++ /dev/null
-.\" -*-nroff-*-
-.TH bits 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-bits \- portable bit manipulation macros
-.\" @U8
-.\" @U16
-.\" @U32
-.\"
-.\" @LSL8
-.\" @LSR8
-.\" @LSL16
-.\" @LSR16
-.\" @LSL32
-.\" @LSR32
-.\"
-.\" @ROL8
-.\" @ROR8
-.\" @ROL16
-.\" @ROR16
-.\" @ROL32
-.\" @ROR32
-.\"
-.\" @GETBYTE
-.\" @PUTBYTE
-.\"
-.\" @LOAD8
-.\" @STORE8
-.\"
-.\" @LOAD16_L
-.\" @LOAD16_B
-.\" @LOAD16
-.\" @STORE16_L
-.\" @STORE16_B
-.\" @STORE16
-.\"
-.\" @LOAD32_L
-.\" @LOAD32_B
-.\" @LOAD32
-.\" @STORE32_L
-.\" @STORE32_B
-.\" @STORE32
-.\"
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/bits.h>"
-
-.BI "octet U8(" v );
-.BI "uint16 U16(" v );
-.BI "uint32 U32(" v );
-
-.BI "octet LSL8(" v ", " s );
-.BI "octet LSR8(" v ", " s );
-.BI "uint16 LSL16(" v ", " s );
-.BI "uint16 LSR16(" v ", " s );
-.BI "uint32 LSL32(" v ", " s );
-.BI "uint32 LSR32(" v ", " s );
-
-.BI "octet ROL8(" v ", " s );
-.BI "octet ROR8(" v ", " s );
-.BI "uint16 ROL16(" v ", " s );
-.BI "uint16 ROR16(" v ", " s );
-.BI "uint32 ROL32(" v ", " s );
-.BI "uint32 ROR32(" v ", " s );
-
-.BI "octet GETBYTE(" p ", " o );
-.BI "void PUTBYTE(" p ", " o ", " v );
-
-.BI "octet LOAD8(" p );
-.BI "void STORE8(" p ", " v );
-
-.BI "uint16 LOAD16_B(" p );
-.BI "uint16 LOAD16_L(" p );
-.BI "uint16 LOAD16(" p );
-.BI "void STORE16_B(" p ", " v );
-.BI "void STORE16_L(" p ", " v );
-.BI "void STORE16(" p ", " v );
-
-.BI "uint32 LOAD32_B(" p );
-.BI "uint32 LOAD32_L(" p );
-.BI "uint32 LOAD32(" p );
-.BI "void STORE32_B(" p ", " v );
-.BI "void STORE32_L(" p ", " v );
-.BI "void STORE32(" p ", " v );
-.fi
-.SH DESCRIPTION
-The header file
-.B <mLib/bits.h>
-contains a number of useful definitions for portably dealing with bit-
-and byte-level manipulation of larger quantities. It declares three
-types:
-.TP
-.B octet
-Equivalent to
-.BR "unsigned char" .
-This is intended to be used when a character array is used to represent
-the octets of some external data format. Note that on some
-architectures the
-.B "unsigned char"
-type may occupy more than 8 bits.
-.TP
-.B uint16
-Equivalent to
-.BR "unsigned short" .
-Intended to be used when a 16-bit value is required. This type is
-always capable of representing any 16-bit unsigned value, but the actual
-type may be wider than 16 bits and will require masking.
-.TP
-.B uint32
-Equivalent to some (architecture-dependent) standard type. Capable of
-representing any unsigned 32-bit value, although the the actual type may
-be wider than 32 bits.
-.PP
-The constants
-.BR MASK8 ,
-.B MASK16
-and
-.B MASK32
-contain bitmasks appropriate for discarding additional bits from a value
-before use as an 8-, 16- or 32-bit quantity. The macros
-.BR U8 ,
-.B U16
-and
-.B U32
-perform masking and type-coercion on a value, and may be more useful in
-general. For example,
-.B U16(x)
-yields a value of type
-.B uint16
-which contains (only) the least-significant 16 bits of
-.BR x .
-.PP
-The macros
-.BI LSL n
-and
-.BI LSR n
-perform left and right logical shift operations on values of width
-.IR n ,
-where
-.I n
-is one of
-.BR 8 ,
-.B 16
-or
-.BR 32 .
-The first argument, written
-.IR v ,
-is the value to shift, and the second, written
-.IR s ,
-is the number of bits to shift. The value
-.I s
-is reduced modulo
-.I n
-before use. Similarly, the macros
-.BI ROL n
-and
-.BI ROR n
-perform left and right rotations (cyclic shifts) on values of width
-.IR n .
-These macros are all written in such a way as to maximize portability.
-A compiler may be able to spot that simple machine instructions will
-suffice in many cases, although that's not the main objective.
-.PP
-The macros
-.BI LOAD n
-and
-.BI STORE n
-(where again
-.I n
-is one of
-.BR 8 ,
-.B 16
-or
-.BR 32 )
-perform transformations between
-.IR n -bit
-quantities and arrays of octets. For example,
-.B LOAD32(q)
-returns the 32-bit value stored in the four octets starting at address
-.BR q ,
-and
-.B STORE16(q, x)
-stores the 16-bit value
-.B x
-in the 2 octets starting at address
-.BR q .
-Values are loaded and stored such that the most significant octet is
-assigned the lowest address (i.e., they use network, or big-endian byte
-order). Macros
-.BI LOAD n _L
-and
-.BI STORE n _L
-are also provided for
-.I n
-either
-.B 16
-or
-.BR 32 :
-they use little-endian byte order. There are
-explicit big-endian macros
-.BI LOAD n _B
-and
-.BI STORE n _B
-too. The pointer arguments don't have to be pointers to octets; the
-value arguments don't have to be of the right type. The macros perform
-all appropriate type casting and masking. Again, these macros are
-written with portability foremost in mind, although it seems they don't
-actually perform at all badly in real use.
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
-
~mdw / mLib / blobdiff