Add a slew of manual pages.

[mLib] / man / bits.3

.\" -*-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>