Debian Codegraph @

upstream/debian-unstable/man2/sched_setaffinity.2

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