FreeBSD manual
download PDF document: bitset.9.pdf
BITSET(9) FreeBSD Kernel Developer's Manual BITSET(9)
NAME
bitset(9) -- BITSET_DEFINE, BITSET_T_INITIALIZER, BITSET_FSET, BIT_CLR,
BIT_COPY, BIT_ISSET, BIT_SET, BIT_ZERO, BIT_FILL, BIT_SETOF, BIT_EMPTY,
BIT_ISFULLSET, BIT_FFS, BIT_FFS_AT, BIT_FLS, BIT_FOREACH_ISSET,
BIT_FOREACH_ISCLR, BIT_COUNT, BIT_SUBSET, BIT_OVERLAP, BIT_CMP, BIT_OR,
BIT_OR2, BIT_ORNOT, BIT_ORNOT2, BIT_AND, BIT_AND2, BIT_ANDNOT,
BIT_ANDNOT2, BIT_XOR, BIT_XOR2, BIT_CLR_ATOMIC, BIT_SET_ATOMIC,
BIT_SET_ATOMIC_ACQ, BIT_TEST_SET_ATOMIC, BIT_TEST_CLR_ATOMIC,
BIT_AND_ATOMIC, BIT_OR_ATOMIC, BIT_COPY_STORE_REL - bitset manipulation
macros
SYNOPSIS
#include <sys/_bitset.h>
#include <sys/bitset.h>
BITSET_DEFINE(STRUCTNAME, const SETSIZE);
BITSET_T_INITIALIZER(ARRAY_CONTENTS);
BITSET_FSET(N_WORDS);
BIT_CLR(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
BIT_COPY(const SETSIZE, struct STRUCTNAME *from, struct STRUCTNAME *to);
bool
BIT_ISSET(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
BIT_SET(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
BIT_ZERO(const SETSIZE, struct STRUCTNAME *bitset);
BIT_FILL(const SETSIZE, struct STRUCTNAME *bitset);
BIT_SETOF(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
bool
BIT_EMPTY(const SETSIZE, struct STRUCTNAME *bitset);
bool
BIT_ISFULLSET(const SETSIZE, struct STRUCTNAME *bitset);
long
BIT_FFS(const SETSIZE, struct STRUCTNAME *bitset);
long
BIT_FFS_AT(const SETSIZE, struct STRUCTNAME *bitset, long start);
long
BIT_FLS(const SETSIZE, struct STRUCTNAME *bitset);
BIT_FOREACH_ISSET(const SETSIZE, size_t bit,
const struct STRUCTNAME *bitset);
BIT_FOREACH_ISCLR(const SETSIZE, size_t bit,
const struct STRUCTNAME *bitset);
bool
BIT_OVERLAP(const SETSIZE, struct STRUCTNAME *bitset1,
struct STRUCTNAME *bitset2);
bool
BIT_CMP(const SETSIZE, struct STRUCTNAME *bitset1,
struct STRUCTNAME *bitset2);
BIT_OR(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);
BIT_OR2(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src1,
struct STRUCTNAME *src2);
BIT_ORNOT(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);
BIT_ORNOT2(const SETSIZE, struct STRUCTNAME *dst,
struct STRUCTNAME *src1, struct STRUCTNAME *src2);
BIT_AND(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);
BIT_AND2(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src1,
struct STRUCTNAME *src2);
BIT_ANDNOT(const SETSIZE, struct STRUCTNAME *dst,
struct STRUCTNAME *src);
BIT_ANDNOT2(const SETSIZE, struct STRUCTNAME *dst,
struct STRUCTNAME *src1, struct STRUCTNAME *src2);
BIT_XOR(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);
BIT_XOR2(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src1,
struct STRUCTNAME *src2);
BIT_CLR_ATOMIC(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
BIT_SET_ATOMIC(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
BIT_SET_ATOMIC_ACQ(const SETSIZE, size_t bit, struct STRUCTNAME *bitset);
bool
BIT_TEST_SET_ATOMIC(const SETSIZE, size_t bit,
struct STRUCTNAME *bitset);
bool
BIT_TEST_CLR_ATOMIC(const SETSIZE, size_t bit,
struct STRUCTNAME *bitset);
BIT_AND_ATOMIC(const SETSIZE, struct STRUCTNAME *dst,
struct STRUCTNAME *src);
BIT_OR_ATOMIC(const SETSIZE, struct STRUCTNAME *dst,
struct STRUCTNAME *src);
BIT_COPY_STORE_REL(const SETSIZE, struct STRUCTNAME *from,
struct STRUCTNAME *to);
#define _WANT_FREEBSD_BITSET
These macros are meant to be used in the kernel and are visible if
_KERNEL is defined when <sys/_bitset.h> or <sys/bitset.h> are included in
a program. Userland programs must define _WANT_FREEBSD_BITSET before
including these files to make the macros visible.
The BITSET_DEFINE() macro defines a bitset struct STRUCTNAME with room to
represent SETSIZE bits.
The BITSET_T_INITIALIZER() macro allows one to initialize a bitset struct
with a compile time literal value.
The BITSET_FSET() macro generates a compile time literal, usable by
BITSET_T_INITIALIZER(), representing a full bitset (all bits set). For
examples of BITSET_T_INITIALIZER() and BITSET_FSET() usage, see the
BITSET_T_INITIALIZER EXAMPLE section. The N_WORDS parameter to
BITSET_FSET() should be:
__bitset_words(SETSIZE)
The BIT_CLR() macro clears bit bit in the bitset pointed to by bitset.
The BIT_CLR_ATOMIC() macro is identical, but the bit is cleared
atomically. The BIT_TEST_CLR_ATOMIC() macro atomically clears the bit
and returns whether it was set.
The BIT_COPY() macro copies the contents of the bitset from to the bitset
to. BIT_COPY_STORE_REL() is similar, but copies component machine words
from from and writes them to to with atomic store with release semantics.
(That is, if to is composed of multiple machine words,
BIT_COPY_STORE_REL() performs multiple individually atomic operations.)
The BIT_ISSET() macro returns true if the bit bit in the bitset pointed
to by bitset is set.
The BIT_SET() macro sets bit bit in the bitset pointed to by bitset. The
BIT_SET_ATOMIC() macro is identical, but the bit is set atomically. The
BIT_SET_ATOMIC_ACQ() macro sets the bit with acquire semantics. The
BIT_TEST_SET_ATOMIC() macro atomically sets the bit and returns whether
it was set.
The BIT_ZERO() macro clears all bits in bitset.
The BIT_FILL() macro sets all bits in bitset.
The BIT_SETOF() macro clears all bits in bitset before setting only bit
bit.
The BIT_EMPTY() macro returns true if bitset is empty.
The BIT_ISFULLSET() macro returns true if bitset is full (all bits set).
The BIT_FFS() macro returns the 1-index of the first (lowest) set bit in
bitset, or zero if bitset is empty. Like with ffs(3), to use the non-
zero result of BIT_FFS() as a bit index parameter to any other bitset(9)
macro, you must subtract one from the result.
The BIT_FFS_AT() macro returns the 1-index of the first (lowest) set bit
in bitset, which is greater than the given 1-indexed start, or zero if no
bits in bitset greater than start are set.
bitset. The index variable bit must have been declared with type int,
and upon each iteration bit is set to the index of successive set bits.
The value of bit after the loop terminates is undefined. Similarly,
BIT_FOREACH_ISCLR() iterates over all clear bits in bitset. In the loop
body, the currently indexed bit may be set or cleared. However, setting
or clearing bits other than the currently indexed bit does not guarantee
that they will or will not be returned in subsequent iterations of the
same loop.
The BIT_COUNT() macro returns the total number of set bits in bitset.
The BIT_SUBSET() macro returns true if needle is a subset of haystack.
The BIT_OVERLAP() macro returns true if bitset1 and bitset2 have any
common bits. (That is, if bitset1 AND bitset2 is not the empty set.)
The BIT_CMP() macro returns true if bitset1 is NOT equal to bitset2.
The BIT_OR() macro sets bits present in src in dst. (It is the bitset(9)
equivalent of the scalar: dst |= src.) BIT_OR_ATOMIC() is similar, but
sets bits in the component machine words in dst atomically. (That is, if
dst is composed of multiple machine words, BIT_OR_ATOMIC() performs
multiple individually atomic operations.)
The BIT_OR2() macro computes src1 bitwise or src2 and assigns the result
to dst. (It is the bitset(9) equivalent of the scalar: dst = src1 |
src2.)
The BIT_ORNOT() macro sets bits not in src in dst. (It is the bitset(9)
equivalent of the scalar: dst |= ~ src.)
The BIT_ORNOT2() macro computes src1 bitwise or not src2 and assigns the
result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1
| ~ src2.)
The BIT_AND() macro clears bits absent from src from dst. (It is the
bitset(9) equivalent of the scalar: dst &= src.) BIT_AND_ATOMIC() is
similar, with the same atomic semantics as BIT_OR_ATOMIC().
The BIT_AND2() macro computes src1 bitwise and src2 and assigns the
result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1
& src2.)
The BIT_ANDNOT() macro clears bits set in src from dst. (It is the
bitset(9) equivalent of the scalar: dst &= ~ src.)
The BIT_ANDNOT2() macro computes src1 bitwise and not src2 and assigns
the result to dst. (It is the bitset(9) equivalent of the scalar: dst =
src1 & ~ src2.)
The BIT_XOR() macro toggles bits set in src in dst. (It is the bitset(9)
equivalent of the scalar: dst ^= src.)
The BIT_XOR2() macro computes src1 bitwise exclusive or src2 and assigns
the result to dst. (It is the bitset(9) equivalent of the scalar: dst =
src1 ^ src2.)
BITSET_T_INITIALIZER EXAMPLE
BITSET_DEFINE(_myset, MYSETSIZE);
myset = BITSET_T_INITIALIZER(0x1);
SEE ALSO
bitstring(3), cpuset(9)
HISTORY
The bitset(9) macros first appeared in FreeBSD 10.0 in January 2014.
They were MFCed to FreeBSD 9.3, released in July 2014.
This manual page first appeared in FreeBSD 11.0.
AUTHORS
The bitset(9) macros were generalized and pulled out of <sys/cpuset.h> as
<sys/_bitset.h> and <sys/bitset.h> by Attilio Rao <attilio@FreeBSD.org>.
This manual page was written by Conrad Meyer <cem@FreeBSD.org>.
CAVEATS
The SETSIZE argument to all of these macros must match the value given to
BITSET_DEFINE().
Unlike every other reference to individual set members, which are zero-
indexed, BIT_FFS(), BIT_FFS_AT() and BIT_FLS() return a one-indexed
result (or zero if the set is empty).
In order to use the macros defined in <sys/bitset.h> and <sys/_bitset.h>
in userland programs, _WANT_FREEBSD_BITSET has to be defined before
including the header files. This requirements exists to prevent a name
space pollution due to macros defined in bitset(9) in programs that
include <sys/cpuset.h> or <sched.h>.
FreeBSD 14.2-RELEASE September 20, 2021 FreeBSD 14.2-RELEASE