CPUSET_GETDOMAIN(2)

💅 CPUSET_GETDOMAIN(2) — manage memory domain policy 🎀

okay so bestie, this one lives in the System Calls Manual (section 2, iykyk) and it's literally from the Standard C Library (libc, -lc) ✨ — yes, that libc. she's serving kernel-adjacent realness and honestly? iconic.

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe, character for character:

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

int
cpuset_getdomain(cpulevel_t level, cpuwhich_t which, id_t id,
    size_t setsize, domainset_t *mask, int *policy);

int
cpuset_setdomain(cpulevel_t level, cpuwhich_t which, id_t id,
    size_t setsize, const domainset_t *mask, int policy);

---

🦋 DESCRIPTION 🦋

so cpuset_getdomain() and cpuset_setdomain() are the two main characters here, and they let you manipulate sets of memory domains and the allocation policy available to processes, threads, jails and other resources. no cap. these functions can mess with sets of memory domains that contain many processes, or per-object anonymous masks that only affect a single object. lowkey versatile 💅

the valid values for the level and which arguments? those are documented in cpuset(2). they're what tell the kernel which object and which set of that object we're talking about. heads up though: not all possible combinations are valid 🙈 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 can be manipulated with CPU_LEVEL_WHICH. periodt.

masks of type domainset_t are composed using the DOMAINSET macros ✨ and here's the tea: the kernel tolerates large sets as long as all domains specified in the set exist. but sets smaller than the kernel uses generate an error on calls to cpuset_getdomain() — even if the result set would fit within the user supplied set 😭 meanwhile calls to cpuset_setdomain() tolerate small sets with no restrictions. generous queen.

the supplied mask should have a size of setsize bytes. that size is usually provided by calling sizeof(mask), which is ultimately determined by the value of DOMAINSET_SETSIZE as defined in <sys/domainset.h>. yeah. that's the whole chain. 🫶

cpuset_getdomain() retrieves the mask and policy from the object specified by level, which and id, and stores it in the space provided by mask and policy — like a little gift handoff 🎁

cpuset_setdomain() attempts to set the mask and policy for the object specified by level, which and id to the values in mask and policy. she tries. she manifests.

---

👑 ALLOCATION POLICIES 👑

valid policy values are as follows, and yes there are exactly three, no more no less:

• DOMAINSET_POLICY_ROUNDROBIN — memory is allocated on a round-robin basis by cycling through each domain in mask. everyone gets a turn, very fair, very democratic 🌀
• DOMAINSET_POLICY_FIRSTTOUCH — memory is allocated on the domain local to the CPU the requesting thread is running on. if allocation from this domain fails, it falls back to round-robin. first choice energy, but with a backup plan 💅
• DOMAINSET_POLICY_PREFER — memory is allocated preferentially from the single domain specified in the mask. if memory is unavailable, the domains listed in the parent cpuset get visited in a round-robin order. she has a favorite but she's not gonna let you starve ⭐

---

💖 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. we love a signal.

---

💀 ERRORS 💀

the following error codes may be set in errno — memorize these, bestie:

• [EINVAL] — the level or which argument was not a valid value. 🙈
• [EINVAL] — the mask or policy argument specified when calling cpuset_setdomain() was not a valid value. yeah, she's listed twice, that's not a typo, that's canon.
• [EDEADLK] — the cpuset_setdomain() 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 serious, please do not.
• [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, babes 😭
• [ERANGE] — the domainsetsize was either preposterously large or smaller than the kernel set size. "preposterously" is doing so much work here and I respect it 💀
• [EPERM] — the calling process did not have the credentials required to complete the operation. no badge, no entry 🎀
• [ECAPMODE] — the calling process attempted to act on a process other than itself, while in capability mode. see capsicum(4). read the lore, iykyk 🧚

---

🌈 SEE ALSO 🌈

cpuset(1), cpuset(2), cpuset_getaffinity(2), cpuset_getid(2), cpuset_setaffinity(2), cpuset_setid(2), capsicum(4), cpuset(9)

like, go read all of them. the whole extended universe. 🫶

---

⭐ HISTORY ⭐

the cpuset_getdomain family of system calls first appeared in FreeBSD 12.0. yes she's a FreeBSD 12.0 girly, she's been around, she has lore. 🔥

🎀 AUTHORS 🎀

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

---

💜 okay that's the whole page, bestie! don't forget the little sign-off down there — this one's from Debian, dated June 18, 2020, and it lives at CPUSET_GETDOMAIN(2). mwah! 🍓✨