share/man/man3/bitstring.3

   1 .\"     $NetBSD: bitstring.3,v 1.12 2004/11/10 16:36:28 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Paul Vixie.
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)bitstring.3 8.1 (Berkeley) 7/19/93
  33 .\"
  34 .Dd July 19, 1993
  35 .Dt BITSTRING 3
  36 .Os
  37 .Sh NAME
  38 .Nm bit_alloc ,
  39 .Nm bit_clear ,
  40 .Nm bit_decl ,
  41 .Nm bit_ffc ,
  42 .Nm bit_ffs ,
  43 .Nm bit_nclear ,
  44 .Nm bit_nset ,
  45 .Nm bit_set ,
  46 .Nm bitstr_size ,
  47 .Nm bit_test
  48 .Nd bit-string manipulation macros
  49 .Sh SYNOPSIS
  50 .In bitstring.h
  51 .Ft bitstr_t *
  52 .Fn bit_alloc "int nbits"
  53 .Fn bit_clear "bit_str name" "int bit"
  54 .Fn bit_decl "bit_str name" "int nbits"
  55 .Fn bit_ffc "bit_str name" "int nbits" "int *value"
  56 .Fn bit_ffs "bit_str name" "int nbits" "int *value"
  57 .Fn bit_nclear "bit_str name" "int start" "int stop"
  58 .Fn bit_nset "bit_str name" "int start" "int stop"
  59 .Fn bit_set "bit_str name" "int bit"
  60 .Fn bitstr_size "int nbits"
  61 .Fn bit_test "bit_str name" "int bit"
  62 .Sh DESCRIPTION
  63 These macros operate on strings of bits.
  64 .Pp
  65 The macro
  66 .Fn bit_alloc
  67 returns a pointer of type
  68 .Dq Fa "bitstr_t *"
  69 to sufficient space to store
  70 .Fa nbits
  71 bits, or
  72 .Dv NULL
  73 if no space is available.
  74 .Pp
  75 The macro
  76 .Fn bit_decl
  77 allocates sufficient space to store
  78 .Fa nbits
  79 bits on the stack.
  80 .Pp
  81 The macro
  82 .Fn bitstr_size
  83 returns the number of elements of type
  84 .Fa bitstr_t
  85 necessary to store
  86 .Fa nbits
  87 bits.
  88 This is useful for copying bit strings.
  89 .Pp
  90 The macros
  91 .Fn bit_clear
  92 and
  93 .Fn bit_set
  94 clear or set the zero-based numbered bit
  95 .Fa bit ,
  96 in the bit string
  97 .Ar name .
  98 .Pp
  99 The
 100 .Fn bit_nset
 101 and
 102 .Fn bit_nclear
 103 macros
 104 set or clear the zero-based numbered bits from
 105 .Fa start
 106 to
 107 .Fa stop
 108 in the bit string
 109 .Ar name .
 110 .Pp
 111 The
 112 .Fn bit_test
 113 macro
 114 evaluates to non-zero if the zero-based numbered bit
 115 .Fa bit
 116 of bit string
 117 .Fa name
 118 is set, and zero otherwise.
 119 .Pp
 120 The
 121 .Fn bit_ffs
 122 macro
 123 stores in the location referenced by
 124 .Fa value
 125 the zero-based number of the first bit set in the array of
 126 .Fa nbits
 127 bits referenced by
 128 .Fa name .
 129 If no bits are set, the location referenced by
 130 .Fa value
 131 is set to \-1.
 132 .Pp
 133 The macro
 134 .Fn bit_ffc
 135 stores in the location referenced by
 136 .Fa value
 137 the zero-based number of the first bit not set in the array of
 138 .Fa nbits
 139 bits referenced by
 140 .Fa name .
 141 If all bits are set, the location referenced by
 142 .Fa value
 143 is set to \-1.
 144 .Pp
 145 The arguments to these macros are evaluated only once and may safely
 146 have side effects.
 147 .Sh EXAMPLES
 148 .Bd -literal -offset indent
 149 #include \*[Lt]limits.h\*[Gt]
 150 #include \*[Lt]bitstring.h\*[Gt]
 151
 152 \&...
 153 #define LPR_BUSY_BIT            0
 154 #define LPR_FORMAT_BIT          1
 155 #define LPR_DOWNLOAD_BIT        2
 156 \&...
 157 #define LPR_AVAILABLE_BIT       9
 158 #define LPR_MAX_BITS            10
 159
 160 make_lpr_available()
 161 {
 162         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 163         ...
 164         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 165         ...
 166         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 167                 bit_clear(bitlist, LPR_FORMAT_BIT);
 168                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 169                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 170         }
 171 }
 172 .Ed
 173 .Sh SEE ALSO
 174 .Xr malloc 3
 175 .Sh HISTORY
 176 The
 177 .Nm bitstring
 178 functions first appeared in
 179 .Bx 4.4 .