/contrib/bind9/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
 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 */