--- /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