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 133These macros operate on strings of bits. 134.Pp 135The function 136.Fn bit_alloc 137returns a pointer of type 138.Dq Fa "bitstr_t *" 139to sufficient space to store 140.Fa nbits 141bits, or 142.Dv NULL 143if no space is available. 144If successful, the returned bit string is initialized with all bits cleared. 145.Pp 146The macro 147.Fn bit_decl 148declares a bit string with sufficient space to store 149.Fa nbits 150bits. 151.Fn bit_decl 152may be used to include statically sized bit strings in structure 153definitions or to create bit strings on the stack. 154Users of this macro are responsible for initialization of the bit string, 155typically via a global initialization of the containing struct or use of the 156.Fn bit_nset 157or 158.Fn bin_nclear 159functions. 160.Pp 161The macro 162.Fn bitstr_size 163returns the number of bytes necessary to store 164.Fa nbits 165bits. 166This is useful for copying bit strings. 167.Pp 168The functions 169.Fn bit_clear 170and 171.Fn bit_set 172clear or set the zero-based numbered bit 173.Fa bit , 174in the bit string 175.Ar name . 176.Pp 177The 178.Fn bit_nset 179and 180.Fn bit_nclear 181functions 182set or clear the zero-based numbered bits from 183.Fa start 184through 185.Fa stop 186in the bit string 187.Ar name . 188.Pp 189The 190.Fn bit_test 191function 192evaluates to non-zero if the zero-based numbered bit 193.Fa bit 194of bit string 195.Fa name 196is set, and zero otherwise. 197.Pp 198The 199.Fn bit_ntest 200function 201evaluates to non-zero if the zero-based numbered bits from 202.Fa start 203through 204.Fa stop 205in the bit string 206.Ar name 207all have the value 208.Ar match . 209.Pp 210The function 211.Fn bit_ffc 212stores in the location referenced by 213.Fa value 214the zero-based number of the first bit not set in the array of 215.Fa nbits 216bits referenced by 217.Fa name . 218If all bits are set, the location referenced by 219.Fa value 220is set to \-1. 221.Pp 222The 223.Fn bit_ffs 224function 225stores in the location referenced by 226.Fa value 227the zero-based number of the first bit set in the array of 228.Fa nbits 229bits referenced by 230.Fa name . 231If no bits are set, the location referenced by 232.Fa value 233is set to \-1. 234.Pp 235The function 236.Fn bit_ffc_at 237stores in the location referenced by 238.Fa value 239the zero-based number of the first bit not set in the array of 240.Fa nbits 241bits referenced by 242.Fa name , 243at or after the zero-based bit index 244.Fa start . 245If all bits at or after 246.Fa start 247are set, the location referenced by 248.Fa value 249is set to \-1. 250.Pp 251The 252.Fn bit_ffs_at 253function 254stores in the location referenced by 255.Fa value 256the zero-based number of the first bit set in the array of 257.Fa nbits 258bits referenced by 259.Fa name , 260at or after the zero-based bit index 261.Fa start . 262If no bits are set after 263.Fa start , 264the location referenced by 265.Fa value 266is set to \-1. 267.Pp 268The 269.Fn bit_ff_at 270function 271stores in the location referenced by 272.Fa value 273the zero-based number of the first bit in the array of 274.Fa nbits 275bits referenced by 276.Fa name , 277at or after the zero-based bit index 278.Fa start 279that has value 280.Fa match . 281If no bits after 282.Fa start 283match that value, the location referenced by 284.Fa value 285is set to \-1. 286.Pp 287The 288.Fn bit_ffc_area 289function stores in the location referenced by 290.Fa value 291the zero-based number of the first bit beginning a sequence of unset bits of 292at least 293.Fa size 294unset bits in the array of 295.Fa nbits 296bits referenced by 297.Fa name . 298If no sequence of contiguous unset bits of the specified 299.Fa size 300can be found, the location referenced by 301.Fa value 302is set to \-1. 303.Pp 304The 305.Fn bit_ffs_area 306function stores in the location referenced by 307.Fa value 308the zero-based number of the first bit beginning a sequence of set bits of 309at least 310.Fa size 311set bits in the array of 312.Fa nbits 313bits referenced by 314.Fa name . 315If no sequence of contiguous set bits of the specified 316.Fa size 317can be found, the location referenced by 318.Fa value 319is set to \-1. 320.Pp 321The 322.Fn bit_ffc_area_at 323function stores in the location referenced by 324.Fa value 325the zero-based number of the first bit beginning a sequence of unset bits of 326at least 327.Fa size 328unset bits in the array of 329.Fa nbits 330bits referenced by 331.Fa name , 332at or after the zero-based bit index 333.Fa start . 334If no sequence of contiguous unset bits of the specified 335.Fa size 336can be found at or after 337.Fa start , 338the location referenced by 339.Fa value 340is set to \-1. 341.Pp 342The 343.Fn bit_ffs_area_at 344function stores in the location referenced by 345.Fa value 346the zero-based number of the first bit beginning a sequence of set bits of 347at least 348.Fa size 349set bits in the array of 350.Fa nbits 351bits referenced by 352.Fa name , 353at or after the zero-based bit index 354.Fa start . 355If no sequence of contiguous set bits of the specified 356.Fa size 357can be found at or after 358.Fa start , 359the location referenced by 360.Fa value 361is set to \-1. 362.Pp 363The 364.Fn bit_ff_area_at 365function stores in the location referenced by 366.Fa value 367the zero-based number of the first bit beginning a sequence of bits of 368at least 369.Fa size 370bits in the array of 371.Fa nbits 372bits referenced by 373.Fa name , 374at or after the zero-based bit index 375.Fa start 376in which all bits have the value 377.Fa match . 378If no sequence of contiguous such bits of the specified 379.Fa size 380can be found at or after 381.Fa start , 382the location referenced by 383.Fa value 384is set to \-1. 385.Pp 386The 387.Fn bit_count 388function stores in the location referenced by 389.Fa value 390the number of bits set in the array of 391.Fa nbits 392bits referenced by 393.Fa name , 394at or after the zero-based bit index 395.Fa start . 396.Pp 397The macro 398.Fn bit_foreach 399traverses all set bits in the array of 400.Fa nbits 401referenced by 402.Fa name 403in the forward direction, assigning each location in turn to 404.Fa var . 405.Pp 406The macro 407.Fn bit_foreach_at 408traverses all set bits in the array of 409.Fa nbits 410referenced by 411.Fa name 412in the forward direction at or after the zero-based bit index 413.Fa start , 414assigning each location in turn to 415.Fa var . 416.Pp 417The macro 418.Fn bit_foreach_unset 419traverses all unset bits in the array of 420.Fa nbits 421referenced by 422.Fa name 423in the forward direction, assigning each location in turn to 424.Fa var . 425.Pp 426The macro 427.Fn bit_foreach_unset_at 428traverses all unset bits in the array of 429.Fa nbits 430referenced by 431.Fa name 432in the forward direction at or after the zero-based bit index 433.Fa start , 434assigning each location in turn to 435.Fa var . 436.Pp 437The arguments in bit string macros are evaluated only once and may safely 438have 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 452make_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 469The 470.Nm bitstring 471functions first appeared in 472.Bx 4.4 . 473