contrib/bind-9.3/lib/isc/include/isc/bitstring.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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.7.206.1 2004/03/06 08:14:38 marka Exp $ */
  19
  20 #ifndef ISC_BITSTRING_H
  21 #define ISC_BITSTRING_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Bitstring
  29  *
  30  * A bitstring is a packed array of bits, stored in a contiguous
  31  * sequence of octets.  The "most significant bit" (msb) of a bitstring
  32  * is the high bit of the first octet.  The "least significant bit" of a
  33  * bitstring is the low bit of the last octet.
  34  *
  35  * Two bit numbering schemes are supported, "msb0" and "lsb0".
  36  *
  37  * In the "msb0" scheme, bit number 0 designates the most significant bit,
  38  * and any padding bits required to make the bitstring a multiple of 8 bits
  39  * long are added to the least significant end of the last octet.
  40  *
  41  * In the "lsb0" scheme, bit number 0 designates the least significant bit,
  42  * and any padding bits required to make the bitstring a multiple of 8 bits
  43  * long are added to the most significant end of the first octet.
  44  *
  45  * E.g., consider the bitstring "11010001111".  This bitstring is 11 bits
  46  * long and will take two octets.  Let "p" denote a pad bit.  In the msb0
  47  * encoding, it would be
  48  *
  49  *             Octet 0           Octet 1
  50  *                         |
  51  *         1 1 0 1 0 0 0 1 | 1 1 1 p p p p p
  52  *         ^               |               ^
  53  *         |                               |
  54  *         bit 0                           bit 15
  55  *
  56  * In the lsb0 encoding, it would be
  57  *
  58  *             Octet 0           Octet 1
  59  *                         |
  60  *         p p p p p 1 1 0 | 1 0 0 0 1 1 1 1
  61  *         ^               |               ^
  62  *         |                               |
  63  *         bit 15                          bit 0
  64  */
  65
  66 /***
  67  *** Imports
  68  ***/
  69
  70 #include <isc/lang.h>
  71 #include <isc/types.h>
  72
  73 ISC_LANG_BEGINDECLS
  74
  75 /***
  76  *** Types
  77  ***/
  78
  79 struct isc_bitstring {
  80         unsigned int            magic;
  81         unsigned char *         data;
  82         unsigned int            length;
  83         unsigned int            size;
  84         isc_boolean_t           lsb0;
  85 };
  86
  87 /***
  88  *** Functions
  89  ***/
  90
  91 void
  92 isc_bitstring_init(isc_bitstring_t *bitstring, unsigned char *data,
  93                    unsigned int length, unsigned int size, isc_boolean_t lsb0);
  94 /*
  95  * Make 'bitstring' refer to the bitstring of 'size' bits starting
  96  * at 'data'.  'length' bits of the bitstring are valid.  If 'lsb0'
  97  * is set then, bit 0 refers to the least significant bit of the
  98  * bitstring.  Otherwise bit 0 is the most significant bit.
  99  *
 100  * Requires:
 101  *
 102  *      'bitstring' points to a isc_bitstring_t.
 103  *
 104  *      'data' points to an array of unsigned char large enough to hold
 105  *      'size' bits.
 106  *
 107  *      'length' <= 'size'.
 108  *
 109  * Ensures:
 110  *
 111  *      'bitstring' is a valid bitstring.
 112  */
 113
 114 void
 115 isc_bitstring_invalidate(isc_bitstring_t *bitstring);
 116 /*
 117  * Invalidate 'bitstring'.
 118  *
 119  * Requires:
 120  *
 121  *      'bitstring' is a valid bitstring.
 122  *
 123  * Ensures:
 124  *
 125  *      'bitstring' is not a valid bitstring.
 126  */
 127
 128 void
 129 isc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos,
 130                    isc_bitstring_t *target, unsigned int tbitpos,
 131                    unsigned int n);
 132 /*
 133  * Starting at bit 'sbitpos', copy 'n' bits from 'source' to
 134  * the 'n' bits of 'target' starting at 'tbitpos'.
 135  *
 136  * Requires:
 137  *
 138  *      'source' and target are valid bitstrings with the same lsb0 setting.
 139  *
 140  *      'sbitpos' + 'n' is less than or equal to the length of 'source'.
 141  *
 142  *      'tbitpos' + 'n' is less than or equal to the size of 'target'.
 143  *
 144  * Ensures:
 145  *
 146  *      The specified bits have been copied, and the length of 'target'
 147  *      adjusted (if required).
 148  */
 149
 150 ISC_LANG_ENDDECLS
 151
 152 #endif /* ISC_BITSTRING_H */