SILC Runtime Toolkit 1.2 Beta 1

[runtime.git] / lib / silcutil / silcbitops.h

diff --git a/lib/silcutil/silcbitops.h b/lib/silcutil/silcbitops.h
index 4aa91c2e7c8e94e807a9aa294b3fac112088e3a9..8fec4042d0140f83c9d0710f4f56a471c0de6c6b 100644 (file)
--- a/lib/silcutil/silcbitops.h
+++ b/lib/silcutil/silcbitops.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2007 Pekka Riikonen
+  Copyright (C) 2007 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcutil/SILC Bit Operations Interface
+/****h* silcutil/Bit Operations Interface
  *
  * DESCRIPTION
  *
@@ -25,7 +25,9 @@
  * find bits in an arbitrarily large bitmap.  The interface does not support
  * setting the bits atomically.
  *
- * Example with a pre-allocate bitmap:
+ * EXAMPLE
+ *
+ * Example with a pre-allocated bitmap:
  *
  * // Declare bitmap of size of 500 bits
  * SILC_BITMAP_DECLARE(bitmap, 500);
@@ -41,7 +43,7 @@
  * bit = silc_bit_ffs(bitmap, bitmap_size);
  *
  * // Find next set bit from the bitmap
- * bit = silc_bit_fns(bitmap, bitmap_size, bit);
+ * bit = silc_bit_fns(bitmap, bitmap_size, bit + 1);
  *
  * // Clear bit number 100
  * silc_bit_set(bitmap, bitmap_size, 100);
@@ -53,7 +55,7 @@
 
 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
 
-/****d* silcutil/SilcBitOpAPI/SILC_BITMAP_DECLARE
+/****d* silcutil/SILC_BITMAP_DECLARE
  *
  * NAME
  *
@@ -68,7 +70,7 @@
 #define SILC_BITMAP_DECLARE(name, bits)                \
   unsigned long name[SILC_BITMAP_SIZE(bits)]
 
-/****d* silcutil/SilcBitOpAPI/SILC_BITMAP_SIZE
+/****d* silcutil/SILC_BITMAP_SIZE
  *
  * NAME
  *
@@ -83,7 +85,7 @@
  ***/
 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_set
+/****f* silcutil/silc_bit_set
  *
  * SYNOPSIS
  *
@@ -93,13 +95,13 @@
  * DESCRIPTION
  *
  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size'.  Returns
- *    FALSE on error.
+ *    FALSE on error and sets silc_errno.
  *
  ***/
 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
                      SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_clear
+/****f* silcutil/silc_bit_clear
  *
  * SYNOPSIS
  *
@@ -109,13 +111,13 @@ SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
  * DESCRIPTION
  *
  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
- *    Returns FALSE on error.
+ *    Returns FALSE on error and sets silc_errno.
  *
  ***/
 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
                        SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_toggle
+/****f* silcutil/silc_bit_toggle
  *
  * SYNOPSIS
  *
@@ -125,13 +127,13 @@ SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
  * DESCRIPTION
  *
  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
- *    Returns FALSE on error.
+ *    Returns FALSE on error and sets silc_errno.
  *
  ***/
 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
                         SilcUInt32 bitmap_size, SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_test_and_set
+/****f* silcutil/silc_bit_test_and_set
  *
  * SYNOPSIS
  *
@@ -141,13 +143,14 @@ SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
  * DESCRIPTION
  *
  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size' and
- *    return the value before setting.  Returns -1 on error.
+ *    return the value before setting.  Returns -1 on error and sets
+ *    silc_errno.
  *
  ***/
 int silc_bit_test_and_set(volatile unsigned long *bitmap,
                          SilcUInt32 bitmap_size, SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_test_and_clear
+/****f* silcutil/silc_bit_test_and_clear
  *
  * SYNOPSIS
  *
@@ -157,13 +160,14 @@ int silc_bit_test_and_set(volatile unsigned long *bitmap,
  * DESCRIPTION
  *
  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
- *    return the value before setting.  Returns -1 on error.
+ *    return the value before setting.  Returns -1 on error and sets
+ *    silc_errno.
  *
  ***/
 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
                            SilcUInt32 bitmap_size, SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_test_and_toggle
+/****f* silcutil/silc_bit_test_and_toggle
  *
  * SYNOPSIS
  *
@@ -173,28 +177,30 @@ int silc_bit_test_and_clear(volatile unsigned long *bitmap,
  * DESCRIPTION
  *
  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
- *    return the value before setting.  Returns -1 on error.
+ *    return the value before setting.  Returns -1 on error and sets
+ *    silc_errno.
  *
  ***/
 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_get
+/****f* silcutil/silc_bit_get
  *
  * SYNOPSIS
  *
  *    int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
- *                     ,SilcUInt32 bit);
+ *                     SilcUInt32 bit);
  *
  * DESCRIPTION
  *
- *    Returns the value of the bit number `bit' or -1 on error.
+ *    Returns the value of the bit number `bit' or -1 on error and sets
+ *    silc_errno.
  *
  ***/
 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
                 SilcUInt32 bit);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_ffs
+/****f* silcutil/silc_bit_ffs
  *
  * SYNOPSIS
  *
@@ -203,12 +209,13 @@ int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
  * DESCRIPTION
  *
  *    Returns the bit number of the first set bit in the `bitmap' of size
- *    of `bitmap_size'.  Returns -1 on error or there were no set bits.
+ *    of `bitmap_size'.  Returns -1 on error or when there were no set bits
+ *    and sets silc_errno.
  *
  ***/
 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_ffz
+/****f* silcutil/silc_bit_ffz
  *
  * SYNOPSIS
  *
@@ -217,12 +224,13 @@ int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
  * DESCRIPTION
  *
  *    Returns the bit number of the first zero bit in the `bitmap' of size
- *    of `bitmap_size'.  Returns -1 on error or there were no zero bits.
+ *    of `bitmap_size'.  Returns -1 on error or when there were no zero bits
+ *    and sets silc_errno.
  *
  ***/
 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_fns
+/****f* silcutil/silc_bit_fns
  *
  * SYNOPSIS
  *
@@ -233,13 +241,13 @@ int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
  *
  *    Returns the bit number of the next set bit in the `bitmap' of size
  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
- *    there were no more set bits.
+ *    when there were no more set bits and sets silc_errno.
  *
  ***/
 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
                 SilcUInt32 offset);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_fnz
+/****f* silcutil/silc_bit_fnz
  *
  * SYNOPSIS
  *
@@ -250,13 +258,13 @@ int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
  *
  *    Returns the bit number of the next zero bit in the `bitmap' of size
  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
- *    there were no more zero bits.
+ *    when there were no more zero bits and sets silc_errno.
  *
  ***/
 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
                 SilcUInt32 offset);
 
-/****f* silcutil/SilcBitOpAPI/silc_bit_clear_bitmap
+/****f* silcutil/silc_bit_clear_bitmap
  *
  * SYNOPSIS
  *