xref: /freebsd/share/man/man3/bitstring.3 (revision e17f5b1d) 
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 November 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