CPU Affinity - The GNU C Library

On a multi-processor system the operating system usually distributes the different processes which are runnable on all available CPUs in a way which allows the system to work most efficiently. Which processes and threads run can be to some extend be control with the scheduling functionality described in the last sections. But which CPU finally executes which process or thread is not covered.

There are a number of reasons why a program might want to have control over this aspect of the system as well:

The POSIX standard up to this date is of not much help to solve this problem. The Linux kernel provides a set of interfaces to allow specifying affinity sets for a process. The scheduler will schedule the thread or process on on CPUs specified by the affinity masks. The interfaces which the GNU C library define follow to some extend the Linux kernel interface.

— Data Type: cpu_set_t

This data set is a bitset where each bit represents a CPU. How the system's CPUs are mapped to bits in the bitset is system dependent. The data type has a fixed size; in the unlikely case that the number of bits are not sufficient to describe the CPUs of the system a different interface has to be used.
This type is a GNU extension and is defined in sched.h.

To manipulate the bitset, to set and reset bits, a number of macros is defined. Some of the macros take a CPU number as a parameter. Here it is important to never exceed the size of the bitset. The following macro specifies the number of bits in the cpu_set_t bitset.

— Macro: int CPU_SETSIZE

The value of this macro is the maximum number of CPUs which can be handled with a cpu_set_t object.

The type cpu_set_t should be considered opaque; all manipulation should happen via the next four macros.

— Macro: void CPU_ZERO (cpu_set_t *set)

This macro initializes the CPU set set to be the empty set.
This macro is a GNU extension and is defined in sched.h.

— Macro: void CPU_SET (int cpu, cpu_set_t *set)

This macro adds cpu to the CPU set set.
The cpu parameter must not have side effects since it is evaluated more than once.
This macro is a GNU extension and is defined in sched.h.

— Macro: void CPU_CLR (int cpu, cpu_set_t *set)

This macro removes cpu from the CPU set set.
The cpu parameter must not have side effects since it is evaluated more than once.
This macro is a GNU extension and is defined in sched.h.

— Macro: int CPU_ISSET (int cpu, const cpu_set_t *set)

This macro returns a nonzero value (true) if cpu is a member of the CPU set set, and zero (false) otherwise.
The cpu parameter must not have side effects since it is evaluated more than once.
This macro is a GNU extension and is defined in sched.h.

CPU bitsets can be constructed from scratch or the currently installed affinity mask can be retrieved from the system.

— Function: int sched_getaffinity (pid_t pid, size_t cpusetsize, cpu_set_t *cpuset)

This functions stores the CPU affinity mask for the process or thread with the ID pid in the cpusetsize bytes long bitmap pointed to by cpuset. If successful, the function always initializes all bits in the cpu_set_t object and returns zero.
If pid does not correspond to a process or thread on the system the or the function fails for some other reason, it returns -1 and errno is set to represent the error condition.

ESRCH
No process or thread with the given ID found.
EFAULT
The pointer cpuset is does not point to a valid object.

This function is a GNU extension and is declared in sched.h.

Note that it is not portably possible to use this information to retrieve the information for different POSIX threads. A separate interface must be provided for that.

— Function: int sched_setaffinity (pid_t pid, size_t cpusetsize, const cpu_set_t *cpuset)

This function installs the cpusetsize bytes long affinity mask pointed to by cpuset for the process or thread with the ID pid. If successful the function returns zero and the scheduler will in future take the affinity information into account.
If the function fails it will return -1 and errno is set to the error code:

ESRCH
No process or thread with the given ID found.
EFAULT
The pointer cpuset is does not point to a valid object.
EINVAL
The bitset is not valid. This might mean that the affinity set might not leave a processor for the process or thread to run on.

This function is a GNU extension and is declared in sched.h.

22.3.5 Limiting execution to certain CPUs