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 May 23, 2016 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_nclear , 74.Nm bit_nset , 75.Nm bit_set , 76.Nm bit_test , 77.Nm bitstr_size 78.Nd bit-string manipulation functions and macros 79.Sh SYNOPSIS 80.In bitstring.h 81.Ft bitstr_t * 82.Fn bit_alloc "int nbits" 83.Ft void 84.Fn bit_decl "bitstr_t *name" "int nbits" 85.Ft void 86.Fn bit_clear "bitstr_t *name" "int bit" 87.Ft void 88.Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value" 89.Ft void 90.Fn bit_ffc "bitstr_t *name" "int nbits" "int *value" 91.Ft void 92.Fn bit_ffs "bitstr_t *name" "int nbits" "int *value" 93.Ft void 94.Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value" 95.Ft void 96.Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value" 97.Ft void 98.Fn bit_nclear "bitstr_t *name" "int start" "int stop" 99.Ft void 100.Fn bit_nset "bitstr_t *name" "int start" "int stop" 101.Ft void 102.Fn bit_set "bitstr_t *name" "int bit" 103.Ft int 104.Fn bitstr_size "int nbits" 105.Ft int 106.Fn bit_test "bitstr_t *name" "int bit" 107.Sh DESCRIPTION 108These macros operate on strings of bits. 109.Pp 110The function 111.Fn bit_alloc 112returns a pointer of type 113.Dq Fa "bitstr_t *" 114to sufficient space to store 115.Fa nbits 116bits, or 117.Dv NULL 118if no space is available. 119If successful, the returned bit string is initialized with all bits cleared. 120.Pp 121The macro 122.Fn bit_decl 123declares a bit string with sufficient space to store 124.Fa nbits 125bits. 126.Fn bit_decl 127may be used to include statically sized bit strings in structure 128definitions or to create bit strings on the stack. 129Users of this macro are responsible for initialization of the bit string, 130typically via a global initialization of the containing struct or use of the 131.Fn bit_nset 132or 133.Fn bin_nclear 134functions. 135.Pp 136The macro 137.Fn bitstr_size 138returns the number of bytes necessary to store 139.Fa nbits 140bits. 141This is useful for copying bit strings. 142.Pp 143The functions 144.Fn bit_clear 145and 146.Fn bit_set 147clear or set the zero-based numbered bit 148.Fa bit , 149in the bit string 150.Ar name . 151.Pp 152The 153.Fn bit_nset 154and 155.Fn bit_nclear 156functions 157set or clear the zero-based numbered bits from 158.Fa start 159through 160.Fa stop 161in the bit string 162.Ar name . 163.Pp 164The 165.Fn bit_test 166function 167evaluates to non-zero if the zero-based numbered bit 168.Fa bit 169of bit string 170.Fa name 171is set, and zero otherwise. 172.Pp 173The function 174.Fn bit_ffc 175stores in the location referenced by 176.Fa value 177the zero-based number of the first bit not set in the array of 178.Fa nbits 179bits referenced by 180.Fa name . 181If all bits are set, the location referenced by 182.Fa value 183is set to \-1. 184.Pp 185The 186.Fn bit_ffs 187function 188stores in the location referenced by 189.Fa value 190the zero-based number of the first bit set in the array of 191.Fa nbits 192bits referenced by 193.Fa name . 194If no bits are set, the location referenced by 195.Fa value 196is set to \-1. 197.Pp 198The function 199.Fn bit_ffc_at 200stores in the location referenced by 201.Fa value 202the zero-based number of the first bit not set in the array of 203.Fa nbits 204bits referenced by 205.Fa name , 206at or after the zero-based bit index 207.Fa start . 208If all bits at or after 209.Fa start 210are set, the location referenced by 211.Fa value 212is set to \-1. 213.Pp 214The 215.Fn bit_ffs_at 216function 217stores in the location referenced by 218.Fa value 219the zero-based number of the first bit set in the array of 220.Fa nbits 221bits referenced by 222.Fa name , 223at or after the zero-based bit index 224.Fa start . 225If no bits are set after 226.Fa start , 227the location referenced by 228.Fa value 229is set to \-1. 230.Pp 231The 232.Fn bit_count 233function stores in the location referenced by 234.Fa value 235the number of bits 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 . 241.Pp 242The arguments in bit string macros are evaluated only once and may safely 243have side effects. 244.Sh EXAMPLES 245.Bd -literal -offset indent 246#include <limits.h> 247#include <bitstring.h> 248 249\&... 250#define LPR_BUSY_BIT 0 251#define LPR_FORMAT_BIT 1 252#define LPR_DOWNLOAD_BIT 2 253\&... 254#define LPR_AVAILABLE_BIT 9 255#define LPR_MAX_BITS 10 256 257make_lpr_available() 258{ 259 bitstr_t bit_decl(bitlist, LPR_MAX_BITS); 260 ... 261 bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); 262 ... 263 if (!bit_test(bitlist, LPR_BUSY_BIT)) { 264 bit_clear(bitlist, LPR_FORMAT_BIT); 265 bit_clear(bitlist, LPR_DOWNLOAD_BIT); 266 bit_set(bitlist, LPR_AVAILABLE_BIT); 267 } 268} 269.Ed 270.Sh SEE ALSO 271.Xr malloc 3 , 272.Xr bitset 9 273.Sh HISTORY 274The 275.Nm bitstring 276functions first appeared in 277.Bx 4.4 . 278