/contrib/bind9/lib/isc/include/isc/bitstring.h

https://bitbucket.org/freebsd/freebsd-head/ · C++ Header · 157 lines · 23 code · 15 blank · 119 comment · 0 complexity · 47be3c40230b741d5ea7a15fce3c6172 MD5 · raw file

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