1SCHED_SETAFFINITY(2) Linux Programmer's Manual SCHED_SETAFFINITY(2)
2
6 sched_setaffinity, sched_getaffinity - set and get a thread's CPU
7 affinity mask
8
10 #define _GNU_SOURCE /* See feature_test_macros(7) */
11 #include <sched.h>
12 int sched_setaffinity(pid_t pid, size_t cpusetsize,
14 const cpu_set_t *mask);
15 int sched_getaffinity(pid_t pid, size_t cpusetsize,
16 cpu_set_t *mask);
17
19 A thread's CPU affinity mask determines the set of CPUs on which it is
20 eligible to run. On a multiprocessor system, setting the CPU affinity
21 mask can be used to obtain performance benefits. For example, by dedi‐
22 cating one CPU to a particular thread (i.e., setting the affinity mask
23 of that thread to specify a single CPU, and setting the affinity mask
24 of all other threads to exclude that CPU), it is possible to ensure
25 maximum execution speed for that thread. Restricting a thread to run
26 on a single CPU also avoids the performance cost caused by the cache
27 invalidation that occurs when a thread ceases to execute on one CPU and
28 then recommences execution on a different CPU.
29 A CPU affinity mask is represented by the cpu_set_t structure, a "CPU
31 set", pointed to by mask. A set of macros for manipulating CPU sets is
32 described in CPU_SET(3).
33 sched_setaffinity() sets the CPU affinity mask of the thread whose ID
35 is pid to the value specified by mask. If pid is zero, then the call‐
36 ing thread is used. The argument cpusetsize is the length (in bytes)
37 of the data pointed to by mask. Normally this argument would be speci‐
38 fied as sizeof(cpu_set_t).
39 If the thread specified by pid is not currently running on one of the
41 CPUs specified in mask, then that thread is migrated to one of the CPUs
42 specified in mask.
43 sched_getaffinity() writes the affinity mask of the thread whose ID is
45 pid into the cpu_set_t structure pointed to by mask. The cpusetsize
46 argument specifies the size (in bytes) of mask. If pid is zero, then
47 the mask of the calling thread is returned.
48
50 On success, sched_setaffinity() and sched_getaffinity() return 0 (but
51 see "C library/kernel differences" below, which notes that the underly‐
52 ing sched_getaffinity() differs in its return value). On failure, -1
53 is returned, and errno is set to indicate the error.
54
56 EFAULT A supplied memory address was invalid.
57 EINVAL The affinity bit mask mask contains no processors that are cur‐
59 rently physically on the system and permitted to the thread ac‐
60 cording to any restrictions that may be imposed by cpuset
61 cgroups or the "cpuset" mechanism described in cpuset(7).
62 EINVAL (sched_getaffinity() and, in kernels before 2.6.9,
64 sched_setaffinity()) cpusetsize is smaller than the size of the
65 affinity mask used by the kernel.