CPUSET(9)

🦋 CPUSET(9) — cpuset manipulation macros 🦋

okay so bestie, this is a page from the Kernel Developer's Manual (yes, the kernel girlies are thriving), and it's all about the cpuset(9) macro family — the little squad that lets you poke at CPU sets in the kernel. no cap, it's giving bitset energy and honestly? iconic. 💅

---

✨ NAME ✨

cpuset(9) — CPUSET_T_INITIALIZER, CPUSET_FSET, CPU_CLR, CPU_COPY, CPU_ISSET, CPU_SET, CPU_ZERO, CPU_FILL, CPU_SETOF, CPU_EMPTY, CPU_ISFULLSET, CPU_FFS, CPU_COUNT, CPU_SUBSET, CPU_OVERLAP, CPU_CMP, CPU_OR, CPU_ORNOT, CPU_AND, CPU_ANDNOT, CPU_XOR, CPU_CLR_ATOMIC, CPU_TEST_CLR_ATOMIC, CPU_SET_ATOMIC, CPU_SET_ATOMIC_ACQ, CPU_TEST_SET_ATOMIC, CPU_AND_ATOMIC, CPU_OR_ATOMIC, CPU_COPY_STORE_REL — cpuset manipulation macros 🎀

---

🌸 SYNOPSIS 🌸

#include <sys/_cpuset.h>
#include <sys/cpuset.h>

CPUSET_T_INITIALIZER(ARRAY_CONTENTS);

CPUSET_FSET

CPU_CLR(size_t cpu_idx, cpuset_t *cpuset);

CPU_COPY(cpuset_t *from, cpuset_t *to);

bool
CPU_ISSET(size_t cpu_idx, cpuset_t *cpuset);

CPU_SET(size_t cpu_idx, cpuset_t *cpuset);

CPU_ZERO(cpuset_t *cpuset);

CPU_FILL(cpuset_t *cpuset);

CPU_SETOF(size_t cpu_idx, cpuset_t *cpuset);

bool
CPU_EMPTY(cpuset_t *cpuset);

bool
CPU_ISFULLSET(cpuset_t *cpuset);

int
CPU_FFS(cpuset_t *cpuset);

int
CPU_COUNT(cpuset_t *cpuset);

bool
CPU_SUBSET(cpuset_t *haystack, cpuset_t *needle);

bool
CPU_OVERLAP(cpuset_t *cpuset1, cpuset_t *cpuset2);

bool
CPU_CMP(cpuset_t *cpuset1, cpuset_t *cpuset2);

CPU_OR(cpuset_t *dst, cpuset_t *src1, cpuset_t *src2);

CPU_ORNOT(cpuset_t *dst, cpuset_t *src1, cpuset_t *src2);

CPU_AND(cpuset_t *dst, cpuset_t *src1, cpuset_t *src2);

CPU_ANDNOT(cpuset_t *dst, cpuset_t *src1, cpuset_t *src2);

CPU_XOR(cpuset_t *dst, cpuset_t *src1, cpuset_t *src2);

CPU_CLR_ATOMIC(size_t cpu_idx, cpuset_t *cpuset);

CPU_TEST_CLR_ATOMIC(size_t cpu_idx, cpuset_t *cpuset);

CPU_SET_ATOMIC(size_t cpu_idx, cpuset_t *cpuset);

CPU_SET_ATOMIC_ACQ(size_t cpu_idx, cpuset_t *cpuset);

CPU_TEST_SET_ATOMIC(size_t cpu_idx, cpuset_t *cpuset);

CPU_AND_ATOMIC(cpuset_t *dst, cpuset_t *src);

CPU_OR_ATOMIC(cpuset_t *dst, cpuset_t *src);

CPU_COPY_STORE_REL(cpuset_t *from, cpuset_t *to);

---

💖 DESCRIPTION 💖

okay so the cpuset(9) family of macros gives you a flexible and efficient CPU set implementation, and it's backed by the bitset(9) macros — cute little teamwork moment fr fr. every single CPU gets represented by exactly one bit. the maximum number of CPUs that cpuset_t can represent is CPU_SETSIZE, and individual CPUs inside cpusets are referenced with indices zero through CPU_SETSIZE - 1. (zero-indexed, the way we like it, except for one chaotic exception we'll get to — see caveats, bestie, don't say I didn't warn you 😭)

The CPUSET_T_INITIALIZER() macro lets you initialize a cpuset_t with a compile time literal value. slay.

The CPUSET_FSET() macro defines a compile time literal that's usable by CPUSET_T_INITIALIZER(), and it represents a full cpuset (all CPUs present). for examples of CPUSET_T_INITIALIZER() and CPUSET_FSET() usage, peek at the “CPUSET_T_INITIALIZER EXAMPLE” section down below 👑

The CPU_CLR() macro removes CPU cpu_idx from the cpuset pointed to by cpuset. The CPU_CLR_ATOMIC() macro is identical, but the bit representing the CPU is cleared with atomic machine instructions — spicy and thread-safe. The CPU_TEST_CLR_ATOMIC() macro atomically clears the bit representing the CPU and returns whether it was set. multitasking icon behavior tbh.

The CPU_COPY() macro copies the contents of the cpuset from to the cpuset to. CPU_COPY_STORE_REL() is similar, but it 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, CPU_COPY_STORE_REL() performs multiple individually atomic operations — so it's not one big atomic moment, it's several little ones, iykyk.)

The CPU_SET() macro adds CPU cpu_idx to the cpuset pointed to by cpuset, if it's not already present. The CPU_SET_ATOMIC() macro is identical, but the bit representing the CPU is set with atomic machine instructions. The CPU_SET_ATOMIC_ACQ() macro sets the bit representing the CPU with atomic acquire semantics. The CPU_TEST_SET_ATOMIC() macro atomically sets the bit representing the CPU and returns whether it was set. no cap, that's the whole squad.

The CPU_ISSET() macro returns true if CPU cpu_idx is a member of the cpuset pointed to by cpuset. it's giving "are you in the group chat" energy ✨

The CPU_ZERO() macro removes all CPUs from cpuset. emptying the whole set, clean slate, main character reset arc.

The CPU_FILL() macro adds all CPUs to cpuset. everybody's invited, we're filling the whole roster 🫶

The CPU_SETOF() macro removes all CPUs in cpuset before adding only CPU cpu_idx. so it's a full glow-up: out with the old, in with the one.

The CPU_EMPTY() macro returns true if cpuset is empty.

The CPU_ISFULLSET() macro returns true if cpuset is full (the set of all CPUs).

The CPU_FFS() macro returns the 1-index of the first (lowest) CPU in cpuset, or zero if cpuset is empty. and listen — like with ffs(3), to use the non-zero result of CPU_FFS() as a cpu_idx index parameter to any other cpuset(9) macro, you must subtract one from the result. do not skip the subtraction, bestie, I'm begging 🙈

The CPU_COUNT() macro returns the total number of CPUs in cpuset. the headcount, the attendance sheet, the "how many of us are actually here" check.

The CPU_SUBSET() macro returns true if needle is a subset of haystack. needle in a haystack, literally, that's the whole bit.

The CPU_OVERLAP() macro returns true if cpuset1 and cpuset2 have any common CPUs. (that is, if cpuset1 AND cpuset2 is not the empty set.)

The CPU_CMP() macro returns true if cpuset1 is NOT equal to cpuset2. read that twice — it's the not equal girlie, the contrarian of the family, do not get it twisted 💀

The CPU_OR() macro adds CPUs present in src to dst. (it's the cpuset(9) equivalent of the scalar: dst |= src.) CPU_OR_ATOMIC() is similar, but sets the bits representing CPUs in the component machine words in dst with atomic machine instructions. (that is, if dst is composed of multiple machine words, CPU_OR_ATOMIC() performs multiple individually atomic operations — same deal as the copy one, multiple little atomic moments, not one.)

The CPU_ORNOT() macro add CPUs not in src to dst. (it's the cpuset(9) equivalent of the scalar: dst |= ~ src.)

The CPU_AND() macro removes CPUs absent from src from dst. (it's the cpuset(9) equivalent of the scalar: dst &= src.) CPU_AND_ATOMIC() is similar, with the same atomic semantics as CPU_OR_ATOMIC().

The CPU_ANDNOT() macro removes CPUs in src from dst. (it's the cpuset(9) equivalent of the scalar: dst &= ~ src.)

---

🧚 CPUSET_T_INITIALIZER EXAMPLE 🧚

here's the vibe in actual code, bestie — go off:

cpuset_t myset;

/* Initialize myset to filled (all CPUs) */
myset = CPUSET_T_INITIALIZER(CPUSET_FSET);

/* Initialize myset to only the lowest CPU */
myset = CPUSET_T_INITIALIZER(0x1);

---

🌈 SEE ALSO 🌈

• cpuset(1)
• cpuset(2)
• bitset(9)

the whole friend group, fr fr 🫶

---

⭐ HISTORY ⭐

<sys/cpuset.h> first appeared in FreeBSD 7.1, released in January 2009, and in FreeBSD 8.0, released in November 2009. a true elder of the timeline ngl.

This manual page first appeared in FreeBSD 11.0. late bloomer but she ate 💅

---

👑 AUTHORS 👑

The cpuset(9) macros were written by Jeff Roberson <jeff@FreeBSD.org>. This manual page was written by Conrad Meyer <cem@FreeBSD.org>. legends, both of them, we stan 🌸

---

💀 CAVEATS 💀

unlike every other reference to individual set members, which are zero-indexed, CPU_FFS() returns a one-indexed result (or zero if the cpuset is empty). girl really said "I'm built different" and honestly? it's the one thing you cannot forget. subtract one, bestie, or your index will be off by one and you'll be sad 😭

---

and that's the whole page, bestie! 🎀 this one dropped from the Debian edition, dated August 7, 2025 — so go forth, manipulate those cpusets, and remember: zero-indexed everywhere except CPU_FFS(). periodt. 💖✨🦋