manage CPU affinity sets
Standard C Library (libc, -lc)
which, id_t id,
which, id_t id,
cpuset family of system calls allow applications to
control sets of processors and memory domains and assign processes and threads
to these sets. Processor sets contain lists of CPUs and domains that members
may run on and exist only as long as some process is a member of the set. All
processes in the system have an assigned set. The default set for all
processes in the system is the set numbered 1. Threads belong to the same set
as the process which contains them, however, they may further restrict their
set with the anonymous per-thread mask to bind to a specific CPU or subset of
CPUs and memory domains.
Sets are referenced by a number of type
cpuset_id_t. Each thread has a root set, an assigned
set, and an anonymous mask. Only the root and assigned sets are numbered.
The root set is the set of all CPUs and memory domains available in the
system or in the system partition the thread is running in. The assigned set
is a subset of the root set and is administratively assignable on a
per-process basis. Many processes and threads may be members of a numbered
The anonymous set is a further thread-specific refinement on the
assigned set. It is intended that administrators will manipulate numbered
while application developers will manipulate anonymous sets using
To select the correct set a value of type
cpulevel_t is used. The following values for
level are supported:
The which argument determines how the value
of id is interpreted and is of type
cpuwhich_t. The which argument
may have the following values:
An id of '-1' may be used with a
CPU_WHICH_CPUSET to mean the current thread,
process, or current thread's cpuset. All cpuset syscalls allow this
A level argument of
CPU_LEVEL_WHICH combined with a
which argument other than
CPU_WHICH_CPUSET refers to the anonymous mask of the
object. This mask does not have an id and may only be manipulated with
cpuset() creates a new set containing the
same CPUs as the root set of the current process and stores its id in the
space provided by setid. On successful completion the
calling process joins the set and is the only member. Children inherit this
set after a call to
cpuset_setid() attempts to set the id of
the object specified by the which argument. Currently
CPU_WHICH_PID is the only acceptable value for which
as threads do not have an id distinct from their process and the API does
not permit changing the id of an existing set. Upon successful completion
all of the threads in the target process will be running on CPUs permitted
by the set.
cpuset_getid() retrieves a set id from the
object indicated by which and stores it in the space
pointed to by setid. The retrieved id may be that of
either the root or assigned set depending on the value of
level. level should be
CPU_LEVEL_ROOT to get the set id from the process or
thread specified by the id argument. Specifying
CPU_LEVEL_WHICH with a process or thread is
unsupported since this references the unnumbered anonymous mask.
The actual contents of the sets may be retrieved or manipulated
See those manual pages for more detail.
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.
The following error codes may be set in errno:
- The which or level argument
was not a valid value.
cpuset_setid() call would leave a thread
without a valid CPU to run on because the set does not overlap with the
thread's anonymous mask.
- The setid pointer passed to
cpuset() was invalid.
- The object specified by the id and
which arguments could not be found.
- The calling process did not have the credentials required to complete the
- There was no free cpusetid_t for allocation.
cpuset family of system calls first appeared in