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 .\" Copyright (c) 2014,2016 Spectra Logic Corporation
  31 .\" All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions, and the following disclaimer,
  38 .\"    without modification.
  39 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  40 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  41 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  42 .\"    including a substantially similar Disclaimer requirement for further
  43 .\"    binary redistribution.
  44 .\"
  45 .\" NO WARRANTY
  46 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  47 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  48 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  49 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  50 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  51 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  52 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  53 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  54 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  55 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  56 .\" POSSIBILITY OF SUCH DAMAGES.
  57 .\"
  58 .\"     @(#)bitstring.3 8.1 (Berkeley) 7/19/93
  59 .\" $FreeBSD$
  60 .\"
  61 .Dd November 18, 2019
  62 .Dt BITSTRING 3
  63 .Os
  64 .Sh NAME
  65 .Nm bit_alloc ,
  66 .Nm bit_clear ,
  67 .Nm bit_count ,
  68 .Nm bit_decl ,
  69 .Nm bit_ffc ,
  70 .Nm bit_ffs ,
  71 .Nm bit_ffc_at ,
  72 .Nm bit_ffs_at ,
  73 .Nm bit_ffc_area ,
  74 .Nm bit_ffs_area ,
  75 .Nm bit_ffc_area_at ,
  76 .Nm bit_ffs_area_at ,
  77 .Nm bit_nclear ,
  78 .Nm bit_nset ,
  79 .Nm bit_set ,
  80 .Nm bit_test ,
  81 .Nm bitstr_size
  82 .Nd bit-string manipulation functions and macros
  83 .Sh SYNOPSIS
  84 .In bitstring.h
  85 .Ft bitstr_t *
  86 .Fn bit_alloc "int nbits"
  87 .Ft void
  88 .Fn bit_decl "bitstr_t *name" "int nbits"
  89 .Ft void
  90 .Fn bit_clear "bitstr_t *name" "int bit"
  91 .Ft void
  92 .Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value"
  93 .Ft void
  94 .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value"
  95 .Ft void
  96 .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value"
  97 .Ft void
  98 .Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value"
  99 .Ft void
 100 .Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value"
 101 .Ft void
 102 .Fn bit_ffc_area "bitstr_t *name" "int nbits" "int size" "int *value"
 103 .Ft void
 104 .Fn bit_ffs_area "bitstr_t *name" "int nbits" "int size" "int *value"
 105 .Ft void
 106 .Fn bit_ffc_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value"
 107 .Ft void
 108 .Fn bit_ffs_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value"
 109 .Ft void
 110 .Fn bit_nclear "bitstr_t *name" "int start" "int stop"
 111 .Ft void
 112 .Fn bit_nset "bitstr_t *name" "int start" "int stop"
 113 .Ft void
 114 .Fn bit_set "bitstr_t *name" "int bit"
 115 .Ft int
 116 .Fn bitstr_size "int nbits"
 117 .Ft int
 118 .Fn bit_test "bitstr_t *name" "int bit"
 119 .Sh DESCRIPTION
 120 These macros operate on strings of bits.
 121 .Pp
 122 The function
 123 .Fn bit_alloc
 124 returns a pointer of type
 125 .Dq Fa "bitstr_t *"
 126 to sufficient space to store
 127 .Fa nbits
 128 bits, or
 129 .Dv NULL
 130 if no space is available.
 131 If successful, the returned bit string is initialized with all bits cleared.
 132 .Pp
 133 The macro
 134 .Fn bit_decl
 135 declares a bit string with sufficient space to store
 136 .Fa nbits
 137 bits.
 138 .Fn bit_decl
 139 may be used to include statically sized bit strings in structure
 140 definitions or to create bit strings on the stack.
 141 Users of this macro are responsible for initialization of the bit string,
 142 typically via a global initialization of the containing struct or use of the
 143 .Fn bit_nset
 144 or
 145 .Fn bin_nclear
 146 functions.
 147 .Pp
 148 The macro
 149 .Fn bitstr_size
 150 returns the number of bytes necessary to store
 151 .Fa nbits
 152 bits.
 153 This is useful for copying bit strings.
 154 .Pp
 155 The functions
 156 .Fn bit_clear
 157 and
 158 .Fn bit_set
 159 clear or set the zero-based numbered bit
 160 .Fa bit ,
 161 in the bit string
 162 .Ar name .
 163 .Pp
 164 The
 165 .Fn bit_nset
 166 and
 167 .Fn bit_nclear
 168 functions
 169 set or clear the zero-based numbered bits from
 170 .Fa start
 171 through
 172 .Fa stop
 173 in the bit string
 174 .Ar name .
 175 .Pp
 176 The
 177 .Fn bit_test
 178 function
 179 evaluates to non-zero if the zero-based numbered bit
 180 .Fa bit
 181 of bit string
 182 .Fa name
 183 is set, and zero otherwise.
 184 .Pp
 185 The function
 186 .Fn bit_ffc
 187 stores in the location referenced by
 188 .Fa value
 189 the zero-based number of the first bit not set in the array of
 190 .Fa nbits
 191 bits referenced by
 192 .Fa name .
 193 If all bits are set, the location referenced by
 194 .Fa value
 195 is set to \-1.
 196 .Pp
 197 The
 198 .Fn bit_ffs
 199 function
 200 stores in the location referenced by
 201 .Fa value
 202 the zero-based number of the first bit set in the array of
 203 .Fa nbits
 204 bits referenced by
 205 .Fa name .
 206 If no bits are set, the location referenced by
 207 .Fa value
 208 is set to \-1.
 209 .Pp
 210 The function
 211 .Fn bit_ffc_at
 212 stores in the location referenced by
 213 .Fa value
 214 the zero-based number of the first bit not set in the array of
 215 .Fa nbits
 216 bits referenced by
 217 .Fa name ,
 218 at or after the zero-based bit index
 219 .Fa start .
 220 If all bits at or after
 221 .Fa start
 222 are set, the location referenced by
 223 .Fa value
 224 is set to \-1.
 225 .Pp
 226 The
 227 .Fn bit_ffs_at
 228 function
 229 stores in the location referenced by
 230 .Fa value
 231 the zero-based number of the first bit set in the array of
 232 .Fa nbits
 233 bits referenced by
 234 .Fa name ,
 235 at or after the zero-based bit index
 236 .Fa start .
 237 If no bits are set after
 238 .Fa start ,
 239 the location referenced by
 240 .Fa value
 241 is set to \-1.
 242 .Pp
 243 The
 244 .Fn bit_ffc_area
 245 function stores in the location referenced by
 246 .Fa value
 247 the zero-based number of the first bit beginning a sequence of unset bits of
 248 at least
 249 .Fa size
 250 unset bits in the array of
 251 .Fa nbits
 252 bits referenced by
 253 .Fa name .
 254 If no sequence of contiguous unset bits of the specified
 255 .Fa size
 256 can be found, the location referenced by
 257 .Fa value
 258 is set to \-1.
 259 .Pp
 260 The
 261 .Fn bit_ffs_area
 262 function stores in the location referenced by
 263 .Fa value
 264 the zero-based number of the first bit beginning a sequence of set bits of
 265 at least
 266 .Fa size
 267 set bits in the array of
 268 .Fa nbits
 269 bits referenced by
 270 .Fa name .
 271 If no sequence of contiguous set bits of the specified
 272 .Fa size
 273 can be found, the location referenced by
 274 .Fa value
 275 is set to \-1.
 276 .Pp
 277 The
 278 .Fn bit_ffc_area_at
 279 function stores in the location referenced by
 280 .Fa value
 281 the zero-based number of the first bit beginning a sequence of unset bits of
 282 at least
 283 .Fa size
 284 unset bits in the array of
 285 .Fa nbits
 286 bits referenced by
 287 .Fa name ,
 288 at or after the zero-based bit index
 289 .Fa start .
 290 If no sequence of contiguous unset bits of the specified
 291 .Fa size
 292 can be found at or after
 293 .Fa start ,
 294 the location referenced by
 295 .Fa value
 296 is set to \-1.
 297 .Pp
 298 The
 299 .Fn bit_ffs_area_at
 300 function stores in the location referenced by
 301 .Fa value
 302 the zero-based number of the first bit beginning a sequence of set bits of
 303 at least
 304 .Fa size
 305 set bits in the array of
 306 .Fa nbits
 307 bits referenced by
 308 .Fa name ,
 309 at or after the zero-based bit index
 310 .Fa start .
 311 If no sequence of contiguous set bits of the specified
 312 .Fa size
 313 can be found at or after
 314 .Fa start ,
 315 the location referenced by
 316 .Fa value
 317 is set to \-1.
 318 .Pp
 319 The
 320 .Fn bit_count
 321 function stores in the location referenced by
 322 .Fa value
 323 the number of bits set in the array of
 324 .Fa nbits
 325 bits referenced by
 326 .Fa name ,
 327 at or after the zero-based bit index
 328 .Fa start .
 329 .Pp
 330 The arguments in bit string macros are evaluated only once and may safely
 331 have side effects.
 332 .Sh EXAMPLES
 333 .Bd -literal -offset indent
 334 #include <limits.h>
 335 #include <bitstring.h>
 336
 337 \&...
 338 #define LPR_BUSY_BIT            0
 339 #define LPR_FORMAT_BIT          1
 340 #define LPR_DOWNLOAD_BIT        2
 341 \&...
 342 #define LPR_AVAILABLE_BIT       9
 343 #define LPR_MAX_BITS            10
 344
 345 make_lpr_available()
 346 {
 347         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 348         ...
 349         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 350         ...
 351         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 352                 bit_clear(bitlist, LPR_FORMAT_BIT);
 353                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 354                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 355         }
 356 }
 357 .Ed
 358 .Sh SEE ALSO
 359 .Xr malloc 3 ,
 360 .Xr bitset 9
 361 .Sh HISTORY
 362 The
 363 .Nm bitstring
 364 functions first appeared in
 365 .Bx 4.4 .