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.\" @(#)bitstring.3 8.1 (Berkeley) 7/19/93 31.\" $FreeBSD: src/share/man/man3/bitstring.3,v 1.6.2.5 2001/12/17 11:30:11 ru Exp $ 32.\" $DragonFly: src/share/man/man3/bitstring.3,v 1.2 2003/06/17 04:36:58 dillon Exp $ 33.\" 34.Dd July 19, 1993 35.Dt BITSTRING 3 36.Os 37.Sh NAME 38.Nm bit_alloc , 39.Nm bit_clear , 40.Nm bit_decl , 41.Nm bit_ffs , 42.Nm bit_fls , 43.Nm bit_nclear , 44.Nm bit_nset , 45.Nm bit_nsearch , 46.Nm bit_set , 47.Nm bitstr_size , 48.Nm bit_test 49.Nd bit-string manipulation macros 50.Sh SYNOPSIS 51.In bitstring.h 52.Ft bitstr_t * 53.Fn bit_alloc "int nbits" 54.Ft void 55.Fn bit_decl "bitstr_t *name" "int nbits" 56.Ft void 57.Fn bit_clear "bitstr_t *name" "int bit" 58.Ft void 59.Fn bit_ffc "bitstr_t *name" "int nbits" "int *value" 60.Ft void 61.Fn bit_ffs "bitstr_t *name" "int nbits" "int *value" 62.Ft void 63.Fn bit_fls "bitstr_t *name" "int nbits" "int *value" 64.Ft void 65.Fn bit_nclear "bitstr_t *name" "int start" "int stop" 66.Ft void 67.Fn bit_nset "bitstr_t *name" "int start" "int stop" 68.Ft void 69.Fn bit_nsearch "bitstr_t *name" "int nbits" "int *value" "int len" 70.Ft void 71.Fn bit_set "bitstr_t *name" "int bit" 72.Ft int 73.Fn bitstr_size "int nbits" 74.Ft int 75.Fn bit_test "bitstr_t *name" "int bit" 76.Sh DESCRIPTION 77These macros operate on strings of bits. 78.Pp 79The macro 80.Fn bit_alloc 81returns a pointer of type 82.Dq Fa "bitstr_t *" 83to sufficient space to store 84.Fa nbits 85bits, or 86.Dv NULL 87if no space is available. 88.Pp 89The macro 90.Fn bit_decl 91allocates sufficient space to store 92.Fa nbits 93bits on the stack. 94.Pp 95The macro 96.Fn bitstr_size 97returns the number of elements of type 98.Fa bitstr_t 99necessary to store 100.Fa nbits 101bits. 102This is useful for copying bit strings. 103.Pp 104The macros 105.Fn bit_clear 106and 107.Fn bit_set 108clear or set the zero-based numbered bit 109.Fa bit , 110in the bit string 111.Ar name . 112.Pp 113The 114.Fn bit_nset 115and 116.Fn bit_nclear 117macros 118set or clear the zero-based numbered bits from 119.Fa start 120through 121.Fa stop 122in the bit string 123.Ar name . 124.Pp 125The 126.Fn bit_test 127macro 128evaluates to non-zero if the zero-based numbered bit 129.Fa bit 130of bit string 131.Fa name 132is set, and zero otherwise. 133.Pp 134The 135.Fn bit_ffs 136macro 137stores in the location referenced by 138.Fa value 139the zero-based number of the first bit set in the array of 140.Fa nbits 141bits referenced by 142.Fa name . 143If no bits are set, the location referenced by 144.Fa value 145is set to \-1. 146.Pp 147The macro 148.Fn bit_ffc 149stores in the location referenced by 150.Fa value 151the zero-based number of the first bit not set in the array of 152.Fa nbits 153bits referenced by 154.Fa name . 155If all bits are set, the location referenced by 156.Fa value 157is set to \-1. 158.Pp 159The macro 160.Fn bit_fls 161stores in the location referenced by 162.Fa value 163the zero-based number of the highest bit set in array of 164.Fa nbits 165bits referenced by 166.Fa name . 167.Pp 168The macro 169.Fn bit_nsearch 170stores in the location referenced by 171.Fa value 172the zero-based index of a span of clear bits of length 173.Fa len 174in the array of 175.Fa nbits 176bits referenced by 177.Fa name . 178.Pp 179The arguments to these macros are evaluated only once and may safely 180have side effects. 181.Sh EXAMPLES 182.Bd -literal -offset indent 183#include <limits.h> 184#include <bitstring.h> 185 186\&... 187#define LPR_BUSY_BIT 0 188#define LPR_FORMAT_BIT 1 189#define LPR_DOWNLOAD_BIT 2 190\&... 191#define LPR_AVAILABLE_BIT 9 192#define LPR_MAX_BITS 10 193 194make_lpr_available() 195{ 196 bitstr_t bit_decl(bitlist, LPR_MAX_BITS); 197 ... 198 bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); 199 ... 200 if (!bit_test(bitlist, LPR_BUSY_BIT)) { 201 bit_clear(bitlist, LPR_FORMAT_BIT); 202 bit_clear(bitlist, LPR_DOWNLOAD_BIT); 203 bit_set(bitlist, LPR_AVAILABLE_BIT); 204 } 205} 206.Ed 207.Sh SEE ALSO 208.Xr malloc 3 209.Sh HISTORY 210The 211.Nm bitstring 212functions first appeared in 213.Bx 4.4 . 214The 215.Fn bit_fls 216and 217.Fn bit_nsearch 218routines first appeared in 219.Dx 2.9 . 220