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