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 Nov 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 120These macros operate on strings of bits. 121.Pp 122The function 123.Fn bit_alloc 124returns a pointer of type 125.Dq Fa "bitstr_t *" 126to sufficient space to store 127.Fa nbits 128bits, or 129.Dv NULL 130if no space is available. 131If successful, the returned bit string is initialized with all bits cleared. 132.Pp 133The macro 134.Fn bit_decl 135declares a bit string with sufficient space to store 136.Fa nbits 137bits. 138.Fn bit_decl 139may be used to include statically sized bit strings in structure 140definitions or to create bit strings on the stack. 141Users of this macro are responsible for initialization of the bit string, 142typically via a global initialization of the containing struct or use of the 143.Fn bit_nset 144or 145.Fn bin_nclear 146functions. 147.Pp 148The macro 149.Fn bitstr_size 150returns the number of bytes necessary to store 151.Fa nbits 152bits. 153This is useful for copying bit strings. 154.Pp 155The functions 156.Fn bit_clear 157and 158.Fn bit_set 159clear or set the zero-based numbered bit 160.Fa bit , 161in the bit string 162.Ar name . 163.Pp 164The 165.Fn bit_nset 166and 167.Fn bit_nclear 168functions 169set or clear the zero-based numbered bits from 170.Fa start 171through 172.Fa stop 173in the bit string 174.Ar name . 175.Pp 176The 177.Fn bit_test 178function 179evaluates to non-zero if the zero-based numbered bit 180.Fa bit 181of bit string 182.Fa name 183is set, and zero otherwise. 184.Pp 185The function 186.Fn bit_ffc 187stores in the location referenced by 188.Fa value 189the zero-based number of the first bit not set in the array of 190.Fa nbits 191bits referenced by 192.Fa name . 193If all bits are set, the location referenced by 194.Fa value 195is set to \-1. 196.Pp 197The 198.Fn bit_ffs 199function 200stores in the location referenced by 201.Fa value 202the zero-based number of the first bit set in the array of 203.Fa nbits 204bits referenced by 205.Fa name . 206If no bits are set, the location referenced by 207.Fa value 208is set to \-1. 209.Pp 210The function 211.Fn bit_ffc_at 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 , 218at or after the zero-based bit index 219.Fa start . 220If all bits at or after 221.Fa start 222are set, the location referenced by 223.Fa value 224is set to \-1. 225.Pp 226The 227.Fn bit_ffs_at 228function 229stores in the location referenced by 230.Fa value 231the zero-based number of the first bit set in the array of 232.Fa nbits 233bits referenced by 234.Fa name , 235at or after the zero-based bit index 236.Fa start . 237If no bits are set after 238.Fa start , 239the location referenced by 240.Fa value 241is set to \-1. 242.Pp 243The 244.Fn bit_ffc_area 245function stores in the location referenced by 246.Fa value 247the zero-based number of the first bit beginning a sequence of unset bits of 248at least 249.Fa size 250unset bits in the array of 251.Fa nbits 252bits referenced by 253.Fa name . 254If no sequence of contiguous unset bits of the specified 255.Fa size 256can be found, the location referenced by 257.Fa value 258is set to \-1. 259.Pp 260The 261.Fn bit_ffs_area 262function stores in the location referenced by 263.Fa value 264the zero-based number of the first bit beginning a sequence of set bits of 265at least 266.Fa size 267set bits in the array of 268.Fa nbits 269bits referenced by 270.Fa name . 271If no sequence of contiguous set bits of the specified 272.Fa size 273can be found, the location referenced by 274.Fa value 275is set to \-1. 276.Pp 277The 278.Fn bit_ffc_area_at 279function stores in the location referenced by 280.Fa value 281the zero-based number of the first bit beginning a sequence of unset bits of 282at least 283.Fa size 284unset bits in the array of 285.Fa nbits 286bits referenced by 287.Fa name , 288at or after the zero-based bit index 289.Fa start . 290If no sequence of contiguous unset bits of the specified 291.Fa size 292can be found at or after 293.Fa start , 294the location referenced by 295.Fa value 296is set to \-1. 297.Pp 298The 299.Fn bit_ffs_area_at 300function stores in the location referenced by 301.Fa value 302the zero-based number of the first bit beginning a sequence of set bits of 303at least 304.Fa size 305set bits in the array of 306.Fa nbits 307bits referenced by 308.Fa name , 309at or after the zero-based bit index 310.Fa start . 311If no sequence of contiguous set bits of the specified 312.Fa size 313can be found at or after 314.Fa start , 315the location referenced by 316.Fa value 317is set to \-1. 318.Pp 319The 320.Fn bit_count 321function stores in the location referenced by 322.Fa value 323the number of bits set in the array of 324.Fa nbits 325bits referenced by 326.Fa name , 327at or after the zero-based bit index 328.Fa start . 329.Pp 330The arguments in bit string macros are evaluated only once and may safely 331have 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 345make_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 362The 363.Nm bitstring 364functions first appeared in 365.Bx 4.4 . 366