]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2002 Robert Love |
2236e65b | 2 | .\" and Copyright (C) 2006, 2015 Michael Kerrisk |
fea681da | 3 | .\" |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da MK |
5 | .\" |
6 | .\" 2002-11-19 Robert Love <rml@tech9.net> - initial version | |
7 | .\" 2004-04-20 mtk - fixed description of return value | |
8 | .\" 2004-04-22 aeb - added glibc prototype history | |
c13182ef | 9 | .\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread |
d2b76164 | 10 | .\" migration and that CPU affinity is a per-thread attribute. |
48be1144 | 11 | .\" 2006-02-03 mtk -- Major rewrite |
ad3f4748 MK |
12 | .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a |
13 | .\" separate CPU_SET(3) page. | |
fea681da | 14 | .\" |
45186a5d | 15 | .TH SCHED_SETAFFINITY 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 16 | .SH NAME |
ad3f4748 | 17 | sched_setaffinity, sched_getaffinity \- \ |
6a7fcf3c | 18 | set and get a thread's CPU affinity mask |
7aab8961 AC |
19 | .SH LIBRARY |
20 | Standard C library | |
8fc3b2cf | 21 | .RI ( libc ", " \-lc ) |
fea681da | 22 | .SH SYNOPSIS |
ee2fa120 | 23 | .nf |
86b91fdf | 24 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
fea681da | 25 | .B #include <sched.h> |
68e4db0a | 26 | .PP |
d3df61c4 | 27 | .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize , |
475b1ecf | 28 | .BI " const cpu_set_t *" mask ); |
d3df61c4 | 29 | .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize , |
ee2fa120 | 30 | .BI " cpu_set_t *" mask ); |
ee2fa120 | 31 | .fi |
fea681da | 32 | .SH DESCRIPTION |
6a7fcf3c | 33 | A thread's CPU affinity mask determines the set of CPUs on which |
48be1144 MK |
34 | it is eligible to run. |
35 | On a multiprocessor system, setting the CPU affinity mask | |
c13182ef | 36 | can be used to obtain performance benefits. |
48be1144 | 37 | For example, |
6a7fcf3c MK |
38 | by dedicating one CPU to a particular thread |
39 | (i.e., setting the affinity mask of that thread to specify a single CPU, | |
40 | and setting the affinity mask of all other threads to exclude that CPU), | |
41 | it is possible to ensure maximum execution speed for that thread. | |
42 | Restricting a thread to run on a single CPU also avoids | |
c13182ef | 43 | the performance cost caused by the cache invalidation that occurs |
6a7fcf3c | 44 | when a thread ceases to execute on one CPU and then |
48be1144 | 45 | recommences execution on a different CPU. |
efeece04 | 46 | .PP |
c13182ef MK |
47 | A CPU affinity mask is represented by the |
48 | .I cpu_set_t | |
48be1144 MK |
49 | structure, a "CPU set", pointed to by |
50 | .IR mask . | |
ad3f4748 MK |
51 | A set of macros for manipulating CPU sets is described in |
52 | .BR CPU_SET (3). | |
efeece04 | 53 | .PP |
e511ffb6 | 54 | .BR sched_setaffinity () |
6a7fcf3c | 55 | sets the CPU affinity mask of the thread whose ID is |
0daa9e92 | 56 | .I pid |
48be1144 MK |
57 | to the value specified by |
58 | .IR mask . | |
fea681da MK |
59 | If |
60 | .I pid | |
6a7fcf3c | 61 | is zero, then the calling thread is used. |
48be1144 MK |
62 | The argument |
63 | .I cpusetsize | |
64 | is the length (in bytes) of the data pointed to by | |
fea681da | 65 | .IR mask . |
48be1144 MK |
66 | Normally this argument would be specified as |
67 | .IR "sizeof(cpu_set_t)" . | |
efeece04 | 68 | .PP |
6a7fcf3c | 69 | If the thread specified by |
6fbc0235 | 70 | .I pid |
48be1144 | 71 | is not currently running on one of the CPUs specified in |
6fbc0235 | 72 | .IR mask , |
6a7fcf3c | 73 | then that thread is migrated to one of the CPUs specified in |
6fbc0235 | 74 | .IR mask . |
efeece04 | 75 | .PP |
e511ffb6 | 76 | .BR sched_getaffinity () |
6a7fcf3c | 77 | writes the affinity mask of the thread whose ID is |
0daa9e92 | 78 | .I pid |
c13182ef | 79 | into the |
48be1144 MK |
80 | .I cpu_set_t |
81 | structure pointed to by | |
82 | .IR mask . | |
c13182ef | 83 | The |
48be1144 MK |
84 | .I cpusetsize |
85 | argument specifies the size (in bytes) of | |
86 | .IR mask . | |
fea681da MK |
87 | If |
88 | .I pid | |
6a7fcf3c | 89 | is zero, then the mask of the calling thread is returned. |
47297adb | 90 | .SH RETURN VALUE |
fea681da | 91 | On success, |
e511ffb6 | 92 | .BR sched_setaffinity () |
48be1144 | 93 | and |
e511ffb6 | 94 | .BR sched_getaffinity () |
d703afe9 MK |
95 | return 0 (but see "C library/kernel differences" below, |
96 | which notes that the underlying | |
97 | .BR sched_getaffinity () | |
98 | differs in its return value). | |
a8a93e8a | 99 | On failure, \-1 is returned, and |
fea681da | 100 | .I errno |
f6a4078b | 101 | is set to indicate the error. |
fea681da MK |
102 | .SH ERRORS |
103 | .TP | |
104 | .B EFAULT | |
105 | A supplied memory address was invalid. | |
106 | .TP | |
107 | .B EINVAL | |
10f5f294 | 108 | The affinity bit mask |
fea681da | 109 | .I mask |
9c7cf182 | 110 | contains no processors that are currently physically on the system |
6a7fcf3c | 111 | and permitted to the thread according to any restrictions that |
bcaf6dc0 MK |
112 | may be imposed by |
113 | .I cpuset | |
0fdca718 | 114 | cgroups or the "cpuset" mechanism described in |
9c7cf182 | 115 | .BR cpuset (7). |
a2126943 MK |
116 | .TP |
117 | .B EINVAL | |
118 | .RB ( sched_getaffinity () | |
119 | and, in kernels before 2.6.9, | |
120 | .BR sched_setaffinity ()) | |
48be1144 | 121 | .I cpusetsize |
fea681da MK |
122 | is smaller than the size of the affinity mask used by the kernel. |
123 | .TP | |
124 | .B EPERM | |
3213bb28 | 125 | .RB ( sched_setaffinity ()) |
6a7fcf3c | 126 | The calling thread does not have appropriate privileges. |
6b2953e4 | 127 | The caller needs an effective user ID equal to the real user ID |
6a7fcf3c | 128 | or effective user ID of the thread identified by |
fea681da MK |
129 | .IR pid , |
130 | or it must possess the | |
0daa9e92 | 131 | .B CAP_SYS_NICE |
1090e3f0 MK |
132 | capability in the user namespace of the thread |
133 | .IR pid . | |
fea681da MK |
134 | .TP |
135 | .B ESRCH | |
6a7fcf3c | 136 | The thread whose ID is \fIpid\fP could not be found. |
a1d5f77c MK |
137 | .SH VERSIONS |
138 | The CPU affinity system calls were introduced in Linux kernel 2.5.8. | |
718af393 | 139 | The system call wrappers were introduced in glibc 2.3. |
a1d5f77c MK |
140 | Initially, the glibc interfaces included a |
141 | .I cpusetsize | |
d3df61c4 MK |
142 | argument, typed as |
143 | .IR "unsigned int" . | |
a1d5f77c MK |
144 | In glibc 2.3.3, the |
145 | .I cpusetsize | |
d3df61c4 MK |
146 | argument was removed, but was then restored in glibc 2.3.4, with type |
147 | .IR size_t . | |
3113c7f3 | 148 | .SH STANDARDS |
8382f16d | 149 | These system calls are Linux-specific. |
47297adb | 150 | .SH NOTES |
9c7cf182 MK |
151 | After a call to |
152 | .BR sched_setaffinity (), | |
6a7fcf3c | 153 | the set of CPUs on which the thread will actually run is |
9c7cf182 MK |
154 | the intersection of the set specified in the |
155 | .I mask | |
156 | argument and the set of CPUs actually present on the system. | |
6a7fcf3c | 157 | The system may further restrict the set of CPUs on which the thread |
9c7cf182 MK |
158 | runs if the "cpuset" mechanism described in |
159 | .BR cpuset (7) | |
160 | is being used. | |
6a7fcf3c | 161 | These restrictions on the actual set of CPUs on which the thread |
9c7cf182 | 162 | will run are silently imposed by the kernel. |
efeece04 | 163 | .PP |
9c11e37c MK |
164 | There are various ways of determining the number of CPUs |
165 | available on the system, including: inspecting the contents of | |
166 | .IR /proc/cpuinfo ; | |
167 | using | |
144d1a36 | 168 | .BR sysconf (3) |
9c11e37c | 169 | to obtain the values of the |
1ae6b2c7 | 170 | .B _SC_NPROCESSORS_CONF |
9c11e37c | 171 | and |
1ae6b2c7 | 172 | .B _SC_NPROCESSORS_ONLN |
4efcd5dd | 173 | parameters; and inspecting the list of CPU directories under |
9c11e37c | 174 | .IR /sys/devices/system/cpu/ . |
efeece04 | 175 | .PP |
476883d7 | 176 | .BR sched (7) |
9e20ad24 MK |
177 | has a description of the Linux scheduling scheme. |
178 | .PP | |
6a7fcf3c | 179 | The affinity mask is a per-thread attribute that can be |
d2b76164 MK |
180 | adjusted independently for each of the threads in a thread group. |
181 | The value returned from a call to | |
182 | .BR gettid (2) | |
183 | can be passed in the argument | |
184 | .IR pid . | |
da49ae18 MK |
185 | Specifying |
186 | .I pid | |
ecbb9b58 | 187 | as 0 will set the attribute for the calling thread, |
da49ae18 MK |
188 | and passing the value returned from a call to |
189 | .BR getpid (2) | |
190 | will set the attribute for the main thread of the thread group. | |
d7ddac24 | 191 | (If you are using the POSIX threads API, then use |