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