From 3302ed8d6eaef8f598338f5682477c5f6acd583c Mon Sep 17 00:00:00 2001
From: Bob Halley <source@isc.org>
Date: Wed, 13 Sep 2000 00:11:45 +0000
Subject: [PATCH] bitstring assertion addition; doc fixes

---
 CHANGES                         |  5 ++++
 lib/isc/bitstring.c             |  3 ++-
 lib/isc/include/isc/bitstring.h | 43 +++++++++++++++++++++++++++++++--
 3 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index f7fecb4193..36c4a0b684 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,8 @@
+ 449.	[bug]		isc_bitstring_copy() only works correctly if the
+			two bitstrings have the same lsb0 value, but this
+			requirement was not documented, nor was there a
+			REQUIRE for it.
+
  448.   [bug]		Host output formatting change, to match v8. [RT #255]
 
  447.   [bug]		Dig didn't properly retry in TCP mode after
diff --git a/lib/isc/bitstring.c b/lib/isc/bitstring.c
index 91bfee227c..d7ba4fbf4d 100644
--- a/lib/isc/bitstring.c
+++ b/lib/isc/bitstring.c
@@ -15,7 +15,7 @@
  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: bitstring.c,v 1.9 2000/09/12 23:27:44 gson Exp $ */
+/* $Id: bitstring.c,v 1.10 2000/09/13 00:11:29 halley Exp $ */
 
 #include <config.h>
 
@@ -89,6 +89,7 @@ isc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos,
 
 	REQUIRE(VALID_BITSTRING(source));
 	REQUIRE(VALID_BITSTRING(target));
+	REQUIRE(source->lsb0 == target->lsb0);
 	if (source->lsb0) {
 		REQUIRE(sbitpos <= source->length);
 		sbitpos = PADDED(source->size) - sbitpos;
diff --git a/lib/isc/include/isc/bitstring.h b/lib/isc/include/isc/bitstring.h
index ed798a7e62..d8b6086f22 100644
--- a/lib/isc/include/isc/bitstring.h
+++ b/lib/isc/include/isc/bitstring.h
@@ -15,7 +15,7 @@
  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: bitstring.h,v 1.5 2000/08/01 01:30:00 tale Exp $ */
+/* $Id: bitstring.h,v 1.6 2000/09/13 00:11:30 halley Exp $ */
 
 #ifndef ISC_BITSTRING_H
 #define ISC_BITSTRING_H 1
@@ -24,6 +24,45 @@
  ***** Module Info
  *****/
 
+/*
+ * Bitstring
+ *
+ * A bitstring is a packed array of bits, stored in a contiguous
+ * sequence of octets.  The "most significant bit" (msb) of a bitstring
+ * is the high bit of the first octet.  The "least significant bit" of a
+ * bitstring is the low bit of the last octet.
+ *
+ * Two bit numbering schemes are supported, "msb0" and "lsb0".
+ *
+ * In the "msb0" scheme, bit number 0 designates the most significant bit,
+ * and any padding bits required to make the bitstring a multiple of 8 bits
+ * long are added to the least significant end of the last octet.
+ *
+ * In the "lsb0" scheme, bit number 0 designates the least significant bit,
+ * and any padding bits required to make the bitstring a multiple of 8 bits
+ * long are added to the most significant end of the first octet.
+ *
+ * E.g., consider the bitstring "11010001111".  This bitstring is 11 bits
+ * long and will take two octets.  Let "p" denote a pad bit.  In the msb0
+ * encoding, it would be
+ *
+ *             Octet 0           Octet 1
+ *                         |
+ *         1 1 0 1 0 0 0 1 | 1 1 1 p p p p p
+ *         ^               |               ^
+ *         |                               |
+ *         bit 0                           bit 15
+ *
+ * In the lsb0 encoding, it would be
+ *
+ *             Octet 0           Octet 1
+ *                         |
+ *         p p p p p 1 1 0 | 1 0 0 0 1 1 1 1 
+ *         ^               |               ^
+ *         |                               |
+ *         bit 15                          bit 0
+ */
+
 /***
  *** Imports
  ***/
@@ -96,7 +135,7 @@ isc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos,
  *
  * Requires:
  *
- *	'source' and target are valid bitstring.
+ *	'source' and target are valid bitstrings with the same lsb0 setting.
  *
  *	'sbitpos' + 'n' is less than or equal to the length of 'source'.
  *