CPUSET_GETAFFINITY(2)

💅 CPUSET_GETAFFINITY(2) 💅

ok so this is a page from the System Calls Manual bestie, and we're talking about CPU affinity today. stay with me, it's gonna slay ✨

---

🌸 NAME 🌸

cpuset_getaffinity, cpuset_setaffinity — manage CPU affinity

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — she's built in, no extra linking drama 💅

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

🦋 DESCRIPTION 🦋

okay so cpuset_getaffinity() and cpuset_setaffinity() are literally the two functions that let you manipulate sets of CPUs available to processes, threads, interrupts, jails and other resources. no cap. they can juggle sets of CPUs that contain many processes, or per-object anonymous masks that only effect a single object. iykyk 💫

the valid values for the level and which arguments are documented over in cpuset(2) — go read that one, bestie, it's the lore. these arguments specify which object, and which set of that object, we're referring to. and not all possible combinations are valid, lowkey. for example, only processes may belong to a numbered set accessed by a level argument of CPU_LEVEL_CPUSET. all resources, however, have a mask which may be manipulated with CPU_LEVEL_WHICH. periodt. 👑

masks of type cpuset_t are composed using the CPU_SET macros. if the user-supplied mask is not large enough to fit all of the matching CPUs, cpuset_getaffinity() fails with ERANGE. rude, but okay. calls to cpuset_setaffinity() tolerate masks of any size with no restrictions — the kernel uses the meaningful part of the mask, where the upper bound is the maximum CPU id present in the system. but if bits for non-existing CPUs are set, calls to cpuset_setaffinity() fail with EINVAL. caught in 4k 💀

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>. write that down 📝

cpuset_getaffinity() retrieves the mask from the object specified by level, which and id and stores it in the space provided by mask. she's the reader 👑

cpuset_setaffinity() attempts to set the mask for the object specified by level, which and id to the value in mask. she's the writer 💅

🌈 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. 🫶

🔥 ERRORS 🔥

the following error codes may be set in errno:

• [EINVAL] — the level or which argument was not a valid value. bestie. that's not a real level.
• [EINVAL] — the mask argument specified when calling cpuset_setaffinity() was not a valid value. also not it. 🙈
• [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. this one's actually serious, don't do it 💀
• [EFAULT] — the mask pointer passed was invalid. bad pointer energy fr fr.
• [ESRCH] — the object specified by the id and which arguments could not be found. she's not here, girl. 😭
• [ERANGE] — the cpusetsize was smaller than needed to fit all of the matching CPUs. too small, tiny, minuscule even.
• [EPERM] — the calling process did not have the credentials required to complete the operation. you don't have the clearance, babe. 🔒
• [ECAPMODE] — the calling process attempted to act on a process other than itself, while in capability mode. see capsicum(4). who do you think you are 🫣

🌟 SEE ALSO 🌟

cpuset(1), cpuset(2), cpuset_getdomain(2), cpuset_getid(2), cpuset_setdomain(2), cpuset_setid(2), pthread_affinity_np(3), pthread_attr_affinity_np(3), capsicum(4), cpuset(9)

like, go read all of them. required reading, no skipping 🎀

💜 HISTORY 💜

The cpuset_getaffinity family of system calls first appeared in FreeBSD 7.1. a legend was born and she ATE 🔥

👑 AUTHORS 👑

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

---

and that's the whole page bestie, mwah 💖 — this cutie came from Debian, dated April 27, 2022 (yes that's the source/version footer, consider it signed with a kiss 🎀💋)