BITSET(9)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

💖 BITSET(9) 💖 — bitset manipulation macros

okay so bestie, welcome to bitset(9) from the Kernel Developer's Manual. This is the bitset macro fam, and they are lowkey iconic: flexible, efficient, and ready to hold your bits if the maximum size of the set is known at compilation. 💅✨

✨ NAME ✨

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

long
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_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

💅 DESCRIPTION 💅

okay so the bitset(9) family of macros provides 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>. 🫶

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. iykyk.

BITSET_DEFINE() — defines a bitset struct STRUCTNAME with room to represent SETSIZE bits. main character struct energy, honestly.
BITSET_T_INITIALIZER() — lets you initialize a bitset struct with a compile time literal value.
BITSET_FSET() — 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)

BIT_CLR() — clears bit bit in the bitset pointed to by bitset. BIT_CLR_ATOMIC() is identical, but the bit is cleared atomically. BIT_TEST_CLR_ATOMIC() atomically clears the bit and returns whether it was set.
BIT_COPY() — 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.)
BIT_ISSET() — returns true if the bit bit in the bitset pointed to by bitset is set.
BIT_SET() — sets bit bit in the bitset pointed to by bitset. BIT_SET_ATOMIC() is identical, but the bit is set atomically. BIT_SET_ATOMIC_ACQ() sets the bit with acquire semantics. BIT_TEST_SET_ATOMIC() atomically sets the bit and returns whether it was set.
BIT_ZERO() — clears all bits in bitset.
BIT_FILL() — sets all bits in bitset.
BIT_SETOF() — clears all bits in bitset before setting only bit bit.
BIT_EMPTY() — returns true if bitset is empty.
BIT_ISFULLSET() — returns true if bitset is full (all bits set).
BIT_FFS() — 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.
BIT_FFS_AT() — 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.
BIT_FLS() — 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.
BIT_FOREACH_ISSET() — can be used to iterate over all set bits in 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.
BIT_COUNT() — returns the total number of set bits in bitset.
BIT_SUBSET() — returns true if needle is a subset of haystack.
BIT_OVERLAP() — returns true if bitset1 and bitset2 have any common bits. (That is, if bitset1 AND bitset2 is not the empty set.)
BIT_CMP() — returns true if bitset1 is NOT equal to bitset2.
BIT_OR() — 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.)
BIT_OR2() — computes src1 bitwise or src2 and assigns the result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1 | src2.)
BIT_ORNOT() — sets bits not in src in dst. (It is the bitset(9) equivalent of the scalar: dst |= ~ src.)
BIT_ORNOT2() — computes src1 bitwise or not src2 and assigns the result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1 | ~ src2.)
BIT_AND() — 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().
BIT_AND2() — computes src1 bitwise and src2 and assigns the result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1 & src2.)
BIT_ANDNOT() — clears bits set in src from dst. (It is the bitset(9) equivalent of the scalar: dst &= ~ src.)
BIT_ANDNOT2() — computes src1 bitwise and not src2 and assigns the result to dst. (It is the bitset(9) equivalent of the scalar: dst = src1 & ~ src2.)
BIT_XOR() — toggles bits set in src in dst. (It is the bitset(9) equivalent of the scalar: dst ^= src.)
BIT_XOR2() — 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 🎀

okay so here's the example, and it's giving compile-time literal realness:

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 💀

Okay bestie, caveat check — these are the little “girlie pop, pay attention” notes, fr fr.

SETSIZE match-up era — the SETSIZE argument to all of these macros must match the value given to BITSET_DEFINE(). Like, all of them. No cap.
The indexing plot twist — 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). So those three are giving different energy — iconic, but don’t mix it up. 💅
Userland header lore — 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 requirement exists to prevent namespace pollution due to macros defined in bitset(9) in programs that include <sys/cpuset.h> or <sched.h>. Define it first, bestie — before the includes, iykyk. ✨

🫶 that’s the caveat section, and yes it ate.

Cute footer sign-off: source/version is Debian, date is September 20, 2021, and the page is BITSET(9) — periodt. 💖

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms