CPUSET_GETDOMAIN(2)

💖 CPUSET_GETDOMAIN 💖 (the cpuset_getdomain / cpuset_setdomain syscalls, section 2 of the System Calls Manual, bestie)

okay so. hi. you're here because you wanna know how memory domains get managed, and honestly? same. this is the page for cpuset_getdomain and cpuset_setdomain, and it's giving "kernel scheduler but make it ✨policy✨". let's get into it 🦋

---

✨ NAME ✨

cpuset_getdomain, cpuset_setdomain — manage memory domain policy 💅

📚 LIBRARY 📚

Standard C Library (libc, -lc)

🎀 SYNOPSIS 🎀

#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 basically, cpuset_getdomain() and cpuset_setdomain() let you mess with sets of memory domains and the allocation policy that processes, threads, jails and other resources get to play with. Iconic, right? These functions can touch sets of memory domains that hold a whole bunch of processes, or per-object anonymous masks that only affect one single object. no cap.

The valid values for the level and which arguments are documented over in cpuset(2) — go read that bestie, it's required reading. Those arguments are what tell us which object and which set of that object we're talking about. And heads up: 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 every resource? Every single one has a mask, and you can manipulate it with CPU_LEVEL_WHICH. periodt.

Masks of type domainset_t get composed using the DOMAINSET macros. The kernel tolerates large sets as long as all the domains specified in the set actually exist — she's flexible like that 💁. But sets smaller than what the kernel uses? Those generate an error on calls to cpuset_getdomain(), even if the result set would totally fit inside the user-supplied set. Rude, but that's the rules. Calls to cpuset_setdomain() are chill about small sets though — no restrictions. 🫶

The mask you supply should have a size of setsize bytes. That size usually comes from calling sizeof(mask), which is ultimately determined by the value of DOMAINSET_SETSIZE as defined in <sys/domainset.h>.

cpuset_getdomain() retrieves the mask and policy from the object specified by level, which and id, and stores them in the space provided by mask and policy. it's giving "fetch".

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. it's giving "glow up".

---

👑 ALLOCATION POLICIES 👑

Valid policy values are as follows, and each one has a whole personality:

• DOMAINSET_POLICY_ROUNDROBIN — memory gets allocated on a round-robin basis by cycling through each domain in mask. everyone gets a turn, nobody's left out, we love a fair queen 🌈
• DOMAINSET_POLICY_FIRSTTOUCH — memory is allocated on the domain local to the CPU that the requesting thread is running on. and if allocating from that domain fails? it falls back to round-robin. main character domain, 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 and she's not hiding it 💅

---

⭐ 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 — collect them all, or honestly, don't:

• [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. (yes, EINVAL said it twice, she's thorough)
• [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. absolutely not, bestie, do not do this 😭
• [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, girl 💀
• [ERANGE] — the domainsetsize was either preposterously large or smaller than the kernel set size. preposterous!! 😭
• [EPERM] — the calling process did not have the credentials required to complete the operation. no entry, no invite, no access 💅
• [ECAPMODE] — the calling process attempted to act on a process other than itself, while in capability mode. See capsicum(4). (capability mode said "know your limits")

🔥 SEE ALSO 🔥

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

go read your siblings, they're all iconic ✨

🦋 HISTORY 🦋

The cpuset_getdomain family of system calls first appeared in FreeBSD 12.0. a whole era.

🎀 AUTHORS 🎀

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

---

and that's the whole page, bestie!! this one came to you from the Debian edition, dated June 18, 2020, and it lives in section 2 of the System Calls Manual. mwah 💖💅✨