Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / isc / include / isc / bitstring.h
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
78 ISC_LANG_BEGINDECLS
79
80 /***
81  *** Types
82  ***/
83
84 struct 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
96 void
97 isc_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
119 void
120 isc_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
133 void
134 isc_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
155 ISC_LANG_ENDDECLS
156
157 #endif /* ISC_BITSTRING_H */