X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/8e94a44e0eacbec394bc93d87db275295e7a670d..b6b9d458c78364bdbbd7fbd7ec543bc364014b45:/man/bits.3

diff --git a/man/bits.3 b/man/bits.3
new file mode 100644
index 0000000..77eeede
--- /dev/null
+++ b/man/bits.3
@@ -0,0 +1,172 @@
+.\" -*-nroff-*-
+.TH bits 3mLib "20 June 1999" mLib
+.SH NAME
+bits \- portable bit manipulation macros
+.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 AUTHOR
+Mark Wooding, <mdw@nsict.org>
+