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