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