Debian Codegraph @

upstream/debian-trixie/man2/sched_setaffinity.2

raw
1 .\" Copyright (C) 2002 Robert Love
2 .\" and Copyright (C) 2006, 2015 Michael Kerrisk
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .\" 2002-11-19 Robert Love <[email protected]> - initial version
7 .\" 2004-04-20 mtk - fixed description of return value
8 .\" 2004-04-22 aeb - added glibc prototype history
9 .\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread
10 .\" migration and that CPU affinity is a per-thread attribute.
11 .\" 2006-02-03 mtk -- Major rewrite
12 .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a
13 .\" separate CPU_SET(3) page.
14 .\"
15 .TH sched_setaffinity 2 2024-06-15 "Linux man-pages 6.9.1"
16 .SH NAME
17 sched_setaffinity, sched_getaffinity \- \
18 set and get a thread's CPU affinity mask
19 .SH LIBRARY
20 Standard C library
21 .RI ( libc ", " \-lc )
22 .SH SYNOPSIS
23 .nf
24 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
25 .B #include <sched.h>
26 .P
27 .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
28 .BI " const cpu_set_t *" mask );
29 .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
30 .BI " cpu_set_t *" mask );
31 .fi
32 .SH DESCRIPTION
33 A thread's CPU affinity mask determines the set of CPUs on which
34 it is eligible to run.
35 On a multiprocessor system, setting the CPU affinity mask
36 can be used to obtain performance benefits.
37 For example,
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
43 the performance cost caused by the cache invalidation that occurs
44 when a thread ceases to execute on one CPU and then
45 recommences execution on a different CPU.
46 .P
47 A CPU affinity mask is represented by the
48 .I cpu_set_t
49 structure, a "CPU set", pointed to by
50 .IR mask .
51 A set of macros for manipulating CPU sets is described in
52 .BR CPU_SET (3).
53 .P
54 .BR sched_setaffinity ()
55 sets the CPU affinity mask of the thread whose ID is
56 .I pid
57 to the value specified by
58 .IR mask .
59 If
60 .I pid
61 is zero, then the calling thread is used.
62 The argument
63 .I cpusetsize
64 is the length (in bytes) of the data pointed to by
65 .IR mask .
66 Normally this argument would be specified as
67 .IR "sizeof(cpu_set_t)" .
68 .P
69 If the thread specified by
70 .I pid
71 is not currently running on one of the CPUs specified in
72 .IR mask ,
73 then that thread is migrated to one of the CPUs specified in
74 .IR mask .
75 .P
76 .BR sched_getaffinity ()
77 writes the affinity mask of the thread whose ID is
78 .I pid
79 into the
80 .I cpu_set_t
81 structure pointed to by
82 .IR mask .
83 The
84 .I cpusetsize
85 argument specifies the size (in bytes) of
86 .IR mask .
87 If
88 .I pid
89 is zero, then the mask of the calling thread is returned.
90 .SH RETURN VALUE
91 On success,
92 .BR sched_setaffinity ()
93 and
94 .BR sched_getaffinity ()
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).
99 On failure, \-1 is returned, and
100 .I errno
101 is set to indicate the error.
102 .SH ERRORS
103 .TP
104 .B EFAULT
105 A supplied memory address was invalid.
106 .TP
107 .B EINVAL
108 The affinity bit mask
109 .I mask
110 contains no processors that are currently physically on the system
111 and permitted to the thread according to any restrictions that
112 may be imposed by
113 .I cpuset
114 cgroups or the "cpuset" mechanism described in
115 .BR cpuset (7).
116 .TP
117 .B EINVAL
118 .RB ( sched_getaffinity ()
119 and, before Linux 2.6.9,
120 .BR sched_setaffinity ())
121 .I cpusetsize
122 is smaller than the size of the affinity mask used by the kernel.
123 .TP
124 .B EPERM
125 .RB ( sched_setaffinity ())
126 The calling thread does not have appropriate privileges.
127 The caller needs an effective user ID equal to the real user ID
128 or effective user ID of the thread identified by
129 .IR pid ,
130 or it must possess the
131 .B CAP_SYS_NICE
132 capability in the user namespace of the thread
133 .IR pid .
134 .TP
135 .B ESRCH
136 The thread whose ID is \fIpid\fP could not be found.
137 .SH STANDARDS
138 Linux.
139 .SH HISTORY
140 Linux 2.5.8,
141 glibc 2.3.
142 .P
143 Initially, the glibc interfaces included a
144 .I cpusetsize
145 argument, typed as
146 .IR "unsigned int" .
147 In glibc 2.3.3, the
148 .I cpusetsize
149 argument was removed, but was then restored in glibc 2.3.4, with type
150 .IR size_t .
151 .SH NOTES
152 After a call to
153 .BR sched_setaffinity (),
154 the set of CPUs on which the thread will actually run is
155 the intersection of the set specified in the
156 .I mask
157 argument and the set of CPUs actually present on the system.
158 The system may further restrict the set of CPUs on which the thread
159 runs if the "cpuset" mechanism described in
160 .BR cpuset (7)
161 is being used.
162 These restrictions on the actual set of CPUs on which the thread
163 will run are silently imposed by the kernel.
164 .P
165 There are various ways of determining the number of CPUs
166 available on the system, including: inspecting the contents of
167 .IR /proc/cpuinfo ;
168 using
169 .BR sysconf (3)
170 to obtain the values of the
171 .B _SC_NPROCESSORS_CONF
172 and
173 .B _SC_NPROCESSORS_ONLN
174 parameters; and inspecting the list of CPU directories under
175 .IR /sys/devices/system/cpu/ .
176 .P
177 .BR sched (7)
178 has a description of the Linux scheduling scheme.
179 .P
180 The affinity mask is a per-thread attribute that can be
181 adjusted independently for each of the threads in a thread group.
182 The value returned from a call to
183 .BR gettid (2)
184 can be passed in the argument
185 .IR pid .
186 Specifying
187 .I pid
188 as 0 will set the attribute for the calling thread,
189 and passing the value returned from a call to
190 .BR getpid (2)
191 will set the attribute for the main thread of the thread group.
192 (If you are using the POSIX threads API, then use
193 .BR pthread_setaffinity_np (3)
194 instead of
195 .BR sched_setaffinity ().)
196 .P
197 The
198 .I isolcpus
199 boot option can be used to isolate one or more CPUs at boot time,
200 so that no processes are scheduled onto those CPUs.
201 Following the use of this boot option,
202 the only way to schedule processes onto the isolated CPUs is via
203 .BR sched_setaffinity ()
204 or the
205 .BR cpuset (7)
206 mechanism.
207 For further information, see the kernel source file
208 .IR Documentation/admin\-guide/kernel\-parameters.txt .
209 As noted in that file,
210 .I isolcpus
211 is the preferred mechanism of isolating CPUs
212 (versus the alternative of manually setting the CPU affinity
213 of all processes on the system).
214 .P
215 A child created via
216 .BR fork (2)
217 inherits its parent's CPU affinity mask.
218 The affinity mask is preserved across an
219 .BR execve (2).
220 .SS C library/kernel differences
221 This manual page describes the glibc interface for the CPU affinity calls.
222 The actual system call interface is slightly different, with the
223 .I mask
224 being typed as
225 .IR "unsigned long\ *" ,
226 reflecting the fact that the underlying implementation of CPU
227 sets is a simple bit mask.
228 .P
229 On success, the raw
230 .BR sched_getaffinity ()
231 system call returns the number of bytes placed copied into the
232 .I mask
233 buffer;
234 this will be the minimum of
235 .I cpusetsize
236 and the size (in bytes) of the
237 .I cpumask_t
238 data type that is used internally by the kernel to
239 represent the CPU set bit mask.
240 .SS Handling systems with large CPU affinity masks
241 The underlying system calls (which represent CPU masks as bit masks of type
242 .IR "unsigned long\ *" )
243 impose no restriction on the size of the CPU mask.
244 However, the
245 .I cpu_set_t
246 data type used by glibc has a fixed size of 128 bytes,
247 meaning that the maximum CPU number that can be represented is 1023.
248 .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
249 .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
250 If the kernel CPU affinity mask is larger than 1024,
251 then calls of the form:
252 .P
253 .in +4n
254 .EX
255 sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
256 .EE
257 .in
258 .P
259 fail with the error
260 .BR EINVAL ,
261 the error produced by the underlying system call for the case where the
262 .I mask
263 size specified in
264 .I cpusetsize
265 is smaller than the size of the affinity mask used by the kernel.
266 (Depending on the system CPU topology, the kernel affinity mask can
267 be substantially larger than the number of active CPUs in the system.)
268 .P
269 When working on systems with large kernel CPU affinity masks,
270 one must dynamically allocate the
271 .I mask
272 argument (see
273 .BR CPU_ALLOC (3)).
274 Currently, the only way to do this is by probing for the size
275 of the required mask using
276 .BR sched_getaffinity ()
277 calls with increasing mask sizes (until the call does not fail with the error
278 .BR EINVAL ).
279 .P
280 Be aware that
281 .BR CPU_ALLOC (3)
282 may allocate a slightly larger CPU set than requested
283 (because CPU sets are implemented as bit masks allocated in units of
284 .IR sizeof(long) ).
285 Consequently,
286 .BR sched_getaffinity ()
287 can set bits beyond the requested allocation size, because the kernel
288 sees a few additional bits.
289 Therefore, the caller should iterate over the bits in the returned set,
290 counting those which are set, and stop upon reaching the value returned by
291 .BR CPU_COUNT (3)
292 (rather than iterating over the number of bits
293 requested to be allocated).
294 .SH EXAMPLES
295 The program below creates a child process.
296 The parent and child then each assign themselves to a specified CPU
297 and execute identical loops that consume some CPU time.
298 Before terminating, the parent waits for the child to complete.
299 The program takes three command-line arguments:
300 the CPU number for the parent,
301 the CPU number for the child,
302 and the number of loop iterations that both processes should perform.
303 .P
304 As the sample runs below demonstrate, the amount of real and CPU time
305 consumed when running the program will depend on intra-core caching effects
306 and whether the processes are using the same CPU.
307 .P
308 We first employ
309 .BR lscpu (1)
310 to determine that this (x86)
311 system has two cores, each with two CPUs:
312 .P
313 .in +4n
314 .EX
315 $ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP
316 Thread(s) per core: 2
317 Core(s) per socket: 2
318 Socket(s): 1
319 .EE
320 .in
321 .P
322 We then time the operation of the example program for three cases:
323 both processes running on the same CPU;
324 both processes running on different CPUs on the same core;
325 and both processes running on different CPUs on different cores.
326 .P
327 .in +4n
328 .EX
329 $ \fBtime \-p ./a.out 0 0 100000000\fP
330 real 14.75
331 user 3.02
332 sys 11.73
333 $ \fBtime \-p ./a.out 0 1 100000000\fP
334 real 11.52
335 user 3.98
336 sys 19.06
337 $ \fBtime \-p ./a.out 0 3 100000000\fP
338 real 7.89
339 user 3.29
340 sys 12.07
341 .EE
342 .in
343 .SS Program source
344 \&
345 .\" SRC BEGIN (sched_setaffinity.c)
346 .EX
347 #define _GNU_SOURCE
348 #include <err.h>
349 #include <sched.h>
350 #include <stdio.h>
351 #include <stdlib.h>
352 #include <sys/wait.h>
353 #include <unistd.h>
354 \&
355 int
356 main(int argc, char *argv[])
357 {
358 int parentCPU, childCPU;
359 cpu_set_t set;
360 unsigned int nloops;
361 \&
362 if (argc != 4) {
363 fprintf(stderr, "Usage: %s parent\-cpu child\-cpu num\-loops\[rs]n",
364 argv[0]);
365 exit(EXIT_FAILURE);
366 }
367 \&
368 parentCPU = atoi(argv[1]);
369 childCPU = atoi(argv[2]);
370 nloops = atoi(argv[3]);
371 \&
372 CPU_ZERO(&set);
373 \&
374 switch (fork()) {
375 case \-1: /* Error */
376 err(EXIT_FAILURE, "fork");
377 \&
378 case 0: /* Child */
379 CPU_SET(childCPU, &set);
380 \&
381 if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1)
382 err(EXIT_FAILURE, "sched_setaffinity");
383 \&
384 for (unsigned int j = 0; j < nloops; j++)
385 getppid();
386 \&
387 exit(EXIT_SUCCESS);
388 \&
389 default: /* Parent */
390 CPU_SET(parentCPU, &set);
391 \&
392 if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1)
393 err(EXIT_FAILURE, "sched_setaffinity");
394 \&
395 for (unsigned int j = 0; j < nloops; j++)
396 getppid();
397 \&
398 wait(NULL); /* Wait for child to terminate */
399 exit(EXIT_SUCCESS);
400 }
401 }
402 .EE
403 .\" SRC END
404 .SH SEE ALSO
405 .ad l
406 .nh
407 .BR lscpu (1),
408 .BR nproc (1),
409 .BR taskset (1),
410 .BR clone (2),
411 .BR getcpu (2),
412 .BR getpriority (2),
413 .BR gettid (2),
414 .BR nice (2),
415 .BR sched_get_priority_max (2),
416 .BR sched_get_priority_min (2),
417 .BR sched_getscheduler (2),
418 .BR sched_setscheduler (2),
419 .BR setpriority (2),
420 .BR CPU_SET (3),
421 .BR get_nprocs (3),
422 .BR pthread_setaffinity_np (3),
423 .BR sched_getcpu (3),
424 .BR capabilities (7),
425 .BR cpuset (7),
426 .BR sched (7),
427 .BR numactl (8)