bitstring.h revision 290001 
1/*
2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: bitstring.h,v 1.14 2007/06/19 23:47:18 tbox Exp $ */
19
20#ifndef ISC_BITSTRING_H
21#define ISC_BITSTRING_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file isc/bitstring.h
28 *
29 * \brief Bitstring manipulation functions.
30 *
31 * A bitstring is a packed array of bits, stored in a contiguous
32 * sequence of octets.  The "most significant bit" (msb) of a bitstring
33 * is the high bit of the first octet.  The "least significant bit" of a
34 * bitstring is the low bit of the last octet.
35 *
36 * Two bit numbering schemes are supported, "msb0" and "lsb0".
37 *
38 * In the "msb0" scheme, bit number 0 designates the most significant bit,
39 * and any padding bits required to make the bitstring a multiple of 8 bits
40 * long are added to the least significant end of the last octet.
41 *
42 * In the "lsb0" scheme, bit number 0 designates the least significant bit,
43 * and any padding bits required to make the bitstring a multiple of 8 bits
44 * long are added to the most significant end of the first octet.
45 *
46 * E.g., consider the bitstring "11010001111".  This bitstring is 11 bits
47 * long and will take two octets.  Let "p" denote a pad bit.  In the msb0
48 * encoding, it would be
49 *
50 * \verbatim
51 *             Octet 0           Octet 1
52 *                         |
53 *         1 1 0 1 0 0 0 1 | 1 1 1 p p p p p
54 *         ^               |               ^
55 *         |                               |
56 *         bit 0                           bit 15
57 * \endverbatim
58 *
59 * In the lsb0 encoding, it would be
60 *
61 * \verbatim
62 *             Octet 0           Octet 1
63 *                         |
64 *         p p p p p 1 1 0 | 1 0 0 0 1 1 1 1
65 *         ^               |               ^
66 *         |                               |
67 *         bit 15                          bit 0
68 * \endverbatim
69 */
70
71/***
72 *** Imports
73 ***/
74
75#include <isc/lang.h>
76#include <isc/types.h>
77
78ISC_LANG_BEGINDECLS
79
80/***
81 *** Types
82 ***/
83
84struct isc_bitstring {
85	unsigned int		magic;
86	unsigned char *		data;
87	unsigned int		length;
88	unsigned int		size;
89	isc_boolean_t		lsb0;
90};
91
92/***
93 *** Functions
94 ***/
95
96void
97isc_bitstring_init(isc_bitstring_t *bitstring, unsigned char *data,
98		   unsigned int length, unsigned int size, isc_boolean_t lsb0);
99/*!<
100 * \brief Make 'bitstring' refer to the bitstring of 'size' bits starting
101 * at 'data'.  'length' bits of the bitstring are valid.  If 'lsb0'
102 * is set then, bit 0 refers to the least significant bit of the
103 * bitstring.  Otherwise bit 0 is the most significant bit.
104 *
105 * Requires:
106 *
107 *\li	'bitstring' points to a isc_bitstring_t.
108 *
109 *\li	'data' points to an array of unsigned char large enough to hold
110 *	'size' bits.
111 *
112 *\li	'length' <= 'size'.
113 *
114 * Ensures:
115 *
116 *\li	'bitstring' is a valid bitstring.
117 */
118
119void
120isc_bitstring_invalidate(isc_bitstring_t *bitstring);
121/*!<
122 * \brief Invalidate 'bitstring'.
123 *
124 * Requires:
125 *
126 *\li	'bitstring' is a valid bitstring.
127 *
128 * Ensures:
129 *
130 *\li	'bitstring' is not a valid bitstring.
131 */
132
133void
134isc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos,
135		   isc_bitstring_t *target, unsigned int tbitpos,
136		   unsigned int n);
137/*!<
138 * \brief Starting at bit 'sbitpos', copy 'n' bits from 'source' to
139 * the 'n' bits of 'target' starting at 'tbitpos'.
140 *
141 * Requires:
142 *
143 *\li	'source' and target are valid bitstrings with the same lsb0 setting.
144 *
145 *\li	'sbitpos' + 'n' is less than or equal to the length of 'source'.
146 *
147 *\li	'tbitpos' + 'n' is less than or equal to the size of 'target'.
148 *
149 * Ensures:
150 *
151 *\li	The specified bits have been copied, and the length of 'target'
152 *	adjusted (if required).
153 */
154
155ISC_LANG_ENDDECLS
156
157#endif /* ISC_BITSTRING_H */
158