kernel/dup: Fix off-by-one in descriptor limit check.
[dragonfly.git] / share / man / man3 / bitstring.3
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
77 These macros operate on strings of bits.
78 .Pp
79 The macro
80 .Fn bit_alloc
81 returns a pointer of type
82 .Dq Fa "bitstr_t *"
83 to sufficient space to store
84 .Fa nbits
85 bits, or
86 .Dv NULL
87 if no space is available.
88 .Pp
89 The macro
90 .Fn bit_decl
91 allocates sufficient space to store
92 .Fa nbits
93 bits on the stack.
94 .Pp
95 The macro
96 .Fn bitstr_size
97 returns the number of elements of type
98 .Fa bitstr_t
99 necessary to store
100 .Fa nbits
101 bits.
102 This is useful for copying bit strings.
103 .Pp
104 The macros
105 .Fn bit_clear
106 and
107 .Fn bit_set
108 clear or set the zero-based numbered bit
109 .Fa bit ,
110 in the bit string
111 .Ar name .
112 .Pp
113 The
114 .Fn bit_nset
115 and
116 .Fn bit_nclear
117 macros
118 set or clear the zero-based numbered bits from
119 .Fa start
120 through
121 .Fa stop
122 in the bit string
123 .Ar name .
124 .Pp
125 The
126 .Fn bit_test
127 macro
128 evaluates to non-zero if the zero-based numbered bit
129 .Fa bit
130 of bit string
131 .Fa name
132 is set, and zero otherwise.
133 .Pp
134 The
135 .Fn bit_ffs
136 macro
137 stores in the location referenced by
138 .Fa value
139 the zero-based number of the first bit set in the array of
140 .Fa nbits
141 bits referenced by
142 .Fa name .
143 If no bits are set, the location referenced by
144 .Fa value
145 is set to \-1.
146 .Pp
147 The macro
148 .Fn bit_ffc
149 stores in the location referenced by
150 .Fa value
151 the zero-based number of the first bit not set in the array of
152 .Fa nbits
153 bits referenced by
154 .Fa name .
155 If all bits are set, the location referenced by
156 .Fa value
157 is set to \-1.
158 .Pp
159 The macro
160 .Fn bit_fls
161 stores in the location referenced by
162 .Fa value
163 the zero-based number of the highest bit set in array of
164 .Fa nbits
165 bits referenced by
166 .Fa name .
167 .Pp
168 The macro
169 .Fn bit_nsearch
170 stores in the location referenced by
171 .Fa value
172 the zero-based index of a span of clear bits of length
173 .Fa len
174 in the array of
175 .Fa nbits
176 bits referenced by
177 .Fa name .
178 .Pp
179 The arguments to these macros are evaluated only once and may safely
180 have 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
194 make_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
210 The
211 .Nm bitstring
212 functions first appeared in
213 .Bx 4.4 .
214 The
215 .Fn bit_fls
216 and
217 .Fn bit_nsearch
218 routines first appeared in
219 .Dx 2.9 .