CPUSET_GETAFFINITY(2)

💖 CPUSET_GETAFFINITY(2) — the CPU affinity girlies' manual 💖

okay so bestie, welcome to the System Calls Manual corner of the internet, where we talk about cpuset_getaffinity and cpuset_setaffinity — the two functions that literally decide which CPUs your little guys get to run on. no cap. let's get into it 🦋

---

✨ NAME ✨

cpuset_getaffinity, cpuset_setaffinity — manage CPU affinity 💅

📚 LIBRARY 📚

Standard C Library (libc, -lc) — she's built in, you don't gotta link anything extra 🫶

🌸 SYNOPSIS 🌸

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

int
cpuset_getaffinity(cpulevel_t level, cpuwhich_t which, id_t id,
    size_t setsize, cpuset_t *mask);

int
cpuset_setaffinity(cpulevel_t level, cpuwhich_t which, id_t id,
    size_t setsize, const cpuset_t *mask);

like. look at those signatures. const on the setter's mask because she would NEVER modify your mask, she's respectful 😌

---

💫 DESCRIPTION 💫

okay so cpuset_getaffinity() and cpuset_setaffinity() let you mess with sets of CPUs available to processes, threads, interrupts, jails and other resources. iconic range honestly. these functions can manipulate sets of CPUs that hold many processes, OR per-object anonymous masks that only affect a single object. both vibes are valid 🎀

the valid values for the level and which arguments live over in cpuset(2) — go read her, she's the source of truth. those two arguments are basically telling the kernel which object and which set of that object we're talking about. not all possible combinations are valid tho!! for example: only processes may belong to a numbered set accessed by a level argument of CPU_LEVEL_CPUSET. but all resources have a mask that may be manipulated with CPU_LEVEL_WHICH. periodt.

masks of type cpuset_t get composed using the CPU_SET macros. the kernel is chill and tolerates large sets — as long as all the CPUs specified in the set actually exist. but sets smaller than the kernel uses? yeah that generates an error on calls to cpuset_getaffinity(), even if the result set would fit inside the set you supplied. rude? a little. calls to cpuset_setaffinity() on the other hand tolerate small sets with no restrictions, so she's the forgiving sister 🙈

the supplied mask should have a size of setsize bytes. this size is usually provided by calling sizeof(mask), which is ultimately determined by the value of CPU_SETSIZE as defined in <sys/cpuset.h>. don't skip this bestie, the size matters fr fr.

• cpuset_getaffinity() — retrieves the mask from the object specified by level, which and id, and stores it in the space provided by mask. it's giving "read the room, then report back" 📖
• cpuset_setaffinity() — attempts to set the mask for the object specified by level, which and id to the value in mask. she's giving main character energy, making decisions 👑

---

🔥 RETURN VALUES 🔥

upon successful completion, the value 0 is returned. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. classic. slay.

---

😭 ERRORS 😭

the following error codes may be set in errno:

• [EINVAL] — the level or which argument was not a valid value. 💀
• [EINVAL] — the mask argument specified when calling cpuset_setaffinity() was not a valid value.
• [EDEADLK] — the cpuset_setaffinity() call would leave a thread without a valid CPU to run on, because the set does not overlap with the thread's anonymous mask. bestie. that's a whole crisis. do not do that.
• [EFAULT] — the mask pointer passed was invalid. 🫠
• [ESRCH] — the object specified by the id and which arguments could not be found. she's not here, she ghosted.
• [ERANGE] — the cpusetsize was either preposterously large or smaller than the kernel set size. preposterously is the actual word and i'm obsessed with it.
• [EPERM] — the calling process did not have the credentials required to complete the operation. no permission, no party 🙅‍♀️
• [ECAPMODE] — the calling process attempted to act on a process other than itself, while in capability mode. see capsicum(4). that's a boundary violation and we don't do those here.

---

👑 SEE ALSO 👑

capsicum(4), cpuset(1), cpuset(2), cpuset_getid(2), cpuset_setid(2), cpuset_getdomain(2), cpuset_setdomain(2), pthread_affinity_np(3), pthread_attr_affinity_np(3), cpuset(9) — the whole friend group, go say hi 🫶

---

🌈 HISTORY 🌈

the cpuset_getaffinity family of system calls first appeared in FreeBSD 7.1. an elder. a legend. respect her 💜

🎀 AUTHORS 🎀

Jeffrey Roberson <jeff@FreeBSD.org> — thank you for your service king 🫡

---

and that's the whole page bestie, no notes. this was the Debian build of the CPUSET_GETAFFINITY(2) page, dated May 23, 2017, and honestly? she ate. go set some affinities. love u, bye 💖✨🦋