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