share/man/man3/bitstring.3

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