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