xref: /dragonfly/share/man/man3/bitstring.3 (revision 8af44722) 
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