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_FLS,
     BIT_COUNT, BIT_SUBSET, BIT_OVERLAP, BIT_CMP, BIT_OR, BIT_OR2, BIT_AND, BIT_AND2, BIT_NAND,
     BIT_NAND2, BIT_XOR, BIT_XOR2, BIT_CLR_ATOMIC, BIT_SET_ATOMIC, BIT_SET_ATOMIC_ACQ,
     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);

     int
     BIT_FFS(const SETSIZE, struct STRUCTNAME *bitset);

     int
     BIT_FLS(const SETSIZE, struct STRUCTNAME *bitset);

     int
     BIT_COUNT(const SETSIZE, struct STRUCTNAME *bitset);

     bool
     BIT_SUBSET(const SETSIZE, struct STRUCTNAME *haystack, struct STRUCTNAME *needle);

     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_AND(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);

     BIT_AND2(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src1,
         struct STRUCTNAME *src2);

     BIT_NAND(const SETSIZE, struct STRUCTNAME *dst, struct STRUCTNAME *src);

     BIT_NAND2(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);

     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);

DESCRIPTION

     The bitset(9) family of macros provide a flexible and efficient bitset implementation if the
     maximum size of the set is known at compilation.  Throughout this manual page, the name
     SETSIZE refers to the size of the bitset in bits.  Individual bits in bitsets are referenced
     with indices zero through SETSIZE - 1.  One example use of <sys/bitset.h> is <sys/cpuset.h>.

     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_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_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_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_FLS() macro returns the 1-index of the last (highest) set bit in bitset, or zero if
     bitset is empty.  Like with fls(3), to use the non-zero result of BIT_FLS() as a bit index
     parameter to any other bitset(9) macro, you must subtract one from the result.

     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_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_NAND() macro clears bits set in src from dst.  (It is the bitset(9) equivalent of
     the scalar: dst &= ~ src.)

     The BIT_NAND2() 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);

     struct _myset myset;

     /* Initialize myset to filled (all bits set) */
     myset = BITSET_T_INITIALIZER(BITSET_FSET(__bitset_words(MYSETSIZE)));

     /* Initialize myset to only the lowest bit set */
     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()
     and BIT_FLS() return a one-indexed result (or zero if the set is empty).