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 August 8, 2021
  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_ff_at ,
  72 .Nm bit_ffc_at ,
  73 .Nm bit_ffs_at ,
  74 .Nm bit_ffc_area ,
  75 .Nm bit_ffs_area ,
  76 .Nm bit_ff_area_at ,
  77 .Nm bit_ffc_area_at ,
  78 .Nm bit_ffs_area_at ,
  79 .Nm bit_nclear ,
  80 .Nm bit_nset ,
  81 .Nm bit_ntest ,
  82 .Nm bit_set ,
  83 .Nm bit_test ,
  84 .Nm bitstr_size
  85 .Nd bit-string manipulation functions and macros
  86 .Sh SYNOPSIS
  87 .In bitstring.h
  88 .Ft bitstr_t *
  89 .Fn bit_alloc "int nbits"
  90 .Ft void
  91 .Fn bit_decl "bitstr_t *name" "int nbits"
  92 .Ft void
  93 .Fn bit_clear "bitstr_t *name" "int bit"
  94 .Ft void
  95 .Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value"
  96 .Ft void
  97 .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value"
  98 .Ft void
  99 .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value"
 100 .Ft void
 101 .Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value"
 102 .Ft void
 103 .Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value"
 104 .Ft void
 105 .Fn bit_ff_at "bitstr_t *name" "int start" "int nbits" "int match" "int *value"
 106 .Ft void
 107 .Fn bit_ffc_area "bitstr_t *name" "int nbits" "int size" "int *value"
 108 .Ft void
 109 .Fn bit_ffs_area "bitstr_t *name" "int nbits" "int size" "int *value"
 110 .Ft void
 111 .Fn bit_ffc_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value"
 112 .Ft void
 113 .Fn bit_ffs_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value"
 114 .Ft void
 115 .Fn bit_ff_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int match" "int *value"
 116 .Fn bit_foreach "bitstr_t *name" "int nbits" "int var"
 117 .Fn bit_foreach_at "bitstr_t *name" "int start" "int nbits" "int var"
 118 .Fn bit_foreach_unset "bitstr_t *name" "int nbits" "int var"
 119 .Fn bit_foreach_unset_at "bitstr_t *name" "int start" "int nbits" "int var"
 120 .Ft void
 121 .Fn bit_nclear "bitstr_t *name" "int start" "int stop"
 122 .Ft void
 123 .Fn bit_nset "bitstr_t *name" "int start" "int stop"
 124 .Ft int
 125 .Fn bit_ntest "bitstr_t *name" "int start" "int stop" "int match"
 126 .Ft void
 127 .Fn bit_set "bitstr_t *name" "int bit"
 128 .Ft int
 129 .Fn bitstr_size "int nbits"
 130 .Ft int
 131 .Fn bit_test "bitstr_t *name" "int bit"
 132 .Sh DESCRIPTION
 133 These macros operate on strings of bits.
 134 .Pp
 135 The function
 136 .Fn bit_alloc
 137 returns a pointer of type
 138 .Dq Fa "bitstr_t *"
 139 to sufficient space to store
 140 .Fa nbits
 141 bits, or
 142 .Dv NULL
 143 if no space is available.
 144 If successful, the returned bit string is initialized with all bits cleared.
 145 .Pp
 146 The macro
 147 .Fn bit_decl
 148 declares a bit string with sufficient space to store
 149 .Fa nbits
 150 bits.
 151 .Fn bit_decl
 152 may be used to include statically sized bit strings in structure
 153 definitions or to create bit strings on the stack.
 154 Users of this macro are responsible for initialization of the bit string,
 155 typically via a global initialization of the containing struct or use of the
 156 .Fn bit_nset
 157 or
 158 .Fn bin_nclear
 159 functions.
 160 .Pp
 161 The macro
 162 .Fn bitstr_size
 163 returns the number of bytes necessary to store
 164 .Fa nbits
 165 bits.
 166 This is useful for copying bit strings.
 167 .Pp
 168 The functions
 169 .Fn bit_clear
 170 and
 171 .Fn bit_set
 172 clear or set the zero-based numbered bit
 173 .Fa bit ,
 174 in the bit string
 175 .Ar name .
 176 .Pp
 177 The
 178 .Fn bit_nset
 179 and
 180 .Fn bit_nclear
 181 functions
 182 set or clear the zero-based numbered bits from
 183 .Fa start
 184 through
 185 .Fa stop
 186 in the bit string
 187 .Ar name .
 188 .Pp
 189 The
 190 .Fn bit_test
 191 function
 192 evaluates to non-zero if the zero-based numbered bit
 193 .Fa bit
 194 of bit string
 195 .Fa name
 196 is set, and zero otherwise.
 197 .Pp
 198 The
 199 .Fn bit_ntest
 200 function
 201 evaluates to non-zero if the zero-based numbered bits from
 202 .Fa start
 203 through
 204 .Fa stop
 205 in the bit string
 206 .Ar name
 207 all have the value
 208 .Ar match .
 209 .Pp
 210 The function
 211 .Fn bit_ffc
 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 If all bits are set, the location referenced by
 219 .Fa value
 220 is set to \-1.
 221 .Pp
 222 The
 223 .Fn bit_ffs
 224 function
 225 stores in the location referenced by
 226 .Fa value
 227 the zero-based number of the first bit set in the array of
 228 .Fa nbits
 229 bits referenced by
 230 .Fa name .
 231 If no bits are set, the location referenced by
 232 .Fa value
 233 is set to \-1.
 234 .Pp
 235 The function
 236 .Fn bit_ffc_at
 237 stores in the location referenced by
 238 .Fa value
 239 the zero-based number of the first bit not set in the array of
 240 .Fa nbits
 241 bits referenced by
 242 .Fa name ,
 243 at or after the zero-based bit index
 244 .Fa start .
 245 If all bits at or after
 246 .Fa start
 247 are set, the location referenced by
 248 .Fa value
 249 is set to \-1.
 250 .Pp
 251 The
 252 .Fn bit_ffs_at
 253 function
 254 stores in the location referenced by
 255 .Fa value
 256 the zero-based number of the first bit set in the array of
 257 .Fa nbits
 258 bits referenced by
 259 .Fa name ,
 260 at or after the zero-based bit index
 261 .Fa start .
 262 If no bits are set after
 263 .Fa start ,
 264 the location referenced by
 265 .Fa value
 266 is set to \-1.
 267 .Pp
 268 The
 269 .Fn bit_ff_at
 270 function
 271 stores in the location referenced by
 272 .Fa value
 273 the zero-based number of the first bit in the array of
 274 .Fa nbits
 275 bits referenced by
 276 .Fa name ,
 277 at or after the zero-based bit index
 278 .Fa start
 279 that has value
 280 .Fa match .
 281 If no bits after
 282 .Fa start
 283 match that value, the location referenced by
 284 .Fa value
 285 is set to \-1.
 286 .Pp
 287 The
 288 .Fn bit_ffc_area
 289 function stores in the location referenced by
 290 .Fa value
 291 the zero-based number of the first bit beginning a sequence of unset bits of
 292 at least
 293 .Fa size
 294 unset bits in the array of
 295 .Fa nbits
 296 bits referenced by
 297 .Fa name .
 298 If no sequence of contiguous unset bits of the specified
 299 .Fa size
 300 can be found, the location referenced by
 301 .Fa value
 302 is set to \-1.
 303 .Pp
 304 The
 305 .Fn bit_ffs_area
 306 function stores in the location referenced by
 307 .Fa value
 308 the zero-based number of the first bit beginning a sequence of set bits of
 309 at least
 310 .Fa size
 311 set bits in the array of
 312 .Fa nbits
 313 bits referenced by
 314 .Fa name .
 315 If no sequence of contiguous set bits of the specified
 316 .Fa size
 317 can be found, the location referenced by
 318 .Fa value
 319 is set to \-1.
 320 .Pp
 321 The
 322 .Fn bit_ffc_area_at
 323 function stores in the location referenced by
 324 .Fa value
 325 the zero-based number of the first bit beginning a sequence of unset bits of
 326 at least
 327 .Fa size
 328 unset bits in the array of
 329 .Fa nbits
 330 bits referenced by
 331 .Fa name ,
 332 at or after the zero-based bit index
 333 .Fa start .
 334 If no sequence of contiguous unset bits of the specified
 335 .Fa size
 336 can be found at or after
 337 .Fa start ,
 338 the location referenced by
 339 .Fa value
 340 is set to \-1.
 341 .Pp
 342 The
 343 .Fn bit_ffs_area_at
 344 function stores in the location referenced by
 345 .Fa value
 346 the zero-based number of the first bit beginning a sequence of set bits of
 347 at least
 348 .Fa size
 349 set bits in the array of
 350 .Fa nbits
 351 bits referenced by
 352 .Fa name ,
 353 at or after the zero-based bit index
 354 .Fa start .
 355 If no sequence of contiguous set bits of the specified
 356 .Fa size
 357 can be found at or after
 358 .Fa start ,
 359 the location referenced by
 360 .Fa value
 361 is set to \-1.
 362 .Pp
 363 The
 364 .Fn bit_ff_area_at
 365 function stores in the location referenced by
 366 .Fa value
 367 the zero-based number of the first bit beginning a sequence of bits of
 368 at least
 369 .Fa size
 370 bits in the array of
 371 .Fa nbits
 372 bits referenced by
 373 .Fa name ,
 374 at or after the zero-based bit index
 375 .Fa start
 376 in which all bits have the value
 377 .Fa match .
 378 If no sequence of contiguous such bits of the specified
 379 .Fa size
 380 can be found at or after
 381 .Fa start ,
 382 the location referenced by
 383 .Fa value
 384 is set to \-1.
 385 .Pp
 386 The
 387 .Fn bit_count
 388 function stores in the location referenced by
 389 .Fa value
 390 the number of bits set in the array of
 391 .Fa nbits
 392 bits referenced by
 393 .Fa name ,
 394 at or after the zero-based bit index
 395 .Fa start .
 396 .Pp
 397 The macro
 398 .Fn bit_foreach
 399 traverses all set bits in the array of
 400 .Fa nbits
 401 referenced by
 402 .Fa name
 403 in the forward direction, assigning each location in turn to
 404 .Fa var .
 405 .Pp
 406 The macro
 407 .Fn bit_foreach_at
 408 traverses all set bits in the array of
 409 .Fa nbits
 410 referenced by
 411 .Fa name
 412 in the forward direction at or after the zero-based bit index
 413 .Fa start ,
 414 assigning each location in turn to
 415 .Fa var .
 416 .Pp
 417 The macro
 418 .Fn bit_foreach_unset
 419 traverses all unset bits in the array of
 420 .Fa nbits
 421 referenced by
 422 .Fa name
 423 in the forward direction, assigning each location in turn to
 424 .Fa var .
 425 .Pp
 426 The macro
 427 .Fn bit_foreach_unset_at
 428 traverses all unset bits in the array of
 429 .Fa nbits
 430 referenced by
 431 .Fa name
 432 in the forward direction at or after the zero-based bit index
 433 .Fa start ,
 434 assigning each location in turn to
 435 .Fa var .
 436 .Pp
 437 The arguments in bit string macros are evaluated only once and may safely
 438 have side effects.
 439 .Sh EXAMPLES
 440 .Bd -literal -offset indent
 441 #include <limits.h>
 442 #include <bitstring.h>
 443
 444 \&...
 445 #define LPR_BUSY_BIT            0
 446 #define LPR_FORMAT_BIT          1
 447 #define LPR_DOWNLOAD_BIT        2
 448 \&...
 449 #define LPR_AVAILABLE_BIT       9
 450 #define LPR_MAX_BITS            10
 451
 452 make_lpr_available()
 453 {
 454         bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
 455         ...
 456         bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
 457         ...
 458         if (!bit_test(bitlist, LPR_BUSY_BIT)) {
 459                 bit_clear(bitlist, LPR_FORMAT_BIT);
 460                 bit_clear(bitlist, LPR_DOWNLOAD_BIT);
 461                 bit_set(bitlist, LPR_AVAILABLE_BIT);
 462         }
 463 }
 464 .Ed
 465 .Sh SEE ALSO
 466 .Xr malloc 3 ,
 467 .Xr bitset 9
 468 .Sh HISTORY
 469 The
 470 .Nm bitstring
 471 functions first appeared in
 472 .Bx 4.4 .