Debian Codegraph @

upstream/debian-unstable/man2/sched_setattr.2

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright 2014, Peter Zijlstra <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH sched_setattr 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 sched_setattr, sched_getattr \-
10 set and get scheduling policy and attributes
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <sched.h>" " /* Definition of " SCHED_* " constants */"
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr ,
21 .BI " unsigned int " flags );
22 .BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr ,
23 .BI " unsigned int " size ", unsigned int " flags );
24 .fi
25 .\" FIXME . Add feature test macro requirements
26 .P
27 .IR Note :
28 glibc provides no wrappers for these system calls,
29 necessitating the use of
30 .BR syscall (2).
31 .SH DESCRIPTION
32 .SS sched_setattr()
33 The
34 .BR sched_setattr ()
35 system call sets the scheduling policy and
36 associated attributes for the thread whose ID is specified in
37 .IR pid .
38 If
39 .I pid
40 equals zero,
41 the scheduling policy and attributes of the calling thread will be set.
42 .P
43 Currently, Linux supports the following "normal"
44 (i.e., non-real-time) scheduling policies as values that may be specified in
45 .IR policy :
46 .TP 14
47 .B SCHED_OTHER
48 the standard round-robin time-sharing policy;
49 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
50 .\" SCHED_NORMAL.
51 .TP
52 .B SCHED_BATCH
53 for "batch" style execution of processes;
54 and
55 .TP
56 .B SCHED_IDLE
57 for running
58 .I very
59 low priority background jobs.
60 .P
61 Various "real-time" policies are also supported,
62 for special time-critical applications that need precise control over
63 the way in which runnable threads are selected for execution.
64 For the rules governing when a process may use these policies, see
65 .BR sched (7).
66 The real-time policies that may be specified in
67 .I policy
68 are:
69 .TP 14
70 .B SCHED_FIFO
71 a first-in, first-out policy;
72 and
73 .TP
74 .B SCHED_RR
75 a round-robin policy.
76 .P
77 Linux also provides the following policy:
78 .TP 14
79 .B SCHED_DEADLINE
80 a deadline scheduling policy;
81 see
82 .BR sched (7)
83 for details.
84 .P
85 The
86 .I attr
87 argument is a pointer to a structure that defines
88 the new scheduling policy and attributes for the specified thread.
89 This structure has the following form:
90 .P
91 .in +4n
92 .EX
93 struct sched_attr {
94 u32 size; /* Size of this structure */
95 u32 sched_policy; /* Policy (SCHED_*) */
96 u64 sched_flags; /* Flags */
97 s32 sched_nice; /* Nice value (SCHED_OTHER,
98 SCHED_BATCH) */
99 u32 sched_priority; /* Static priority (SCHED_FIFO,
100 SCHED_RR) */
101 /* For SCHED_DEADLINE */
102 u64 sched_runtime;
103 u64 sched_deadline;
104 u64 sched_period;
105 \&
106 /* Utilization hints */
107 u32 sched_util_min;
108 u32 sched_util_max;
109 };
110 .EE
111 .in
112 .P
113 The fields of the
114 .I sched_attr
115 structure are as follows:
116 .TP
117 .B size
118 This field should be set to the size of the structure in bytes, as in
119 .IR "sizeof(struct sched_attr)" .
120 If the provided structure is smaller than the kernel structure,
121 any additional fields are assumed to be '0'.
122 If the provided structure is larger than the kernel structure,
123 the kernel verifies that all additional fields are 0;
124 if they are not,
125 .BR sched_setattr ()
126 fails with the error
127 .B E2BIG
128 and updates
129 .I size
130 to contain the size of the kernel structure.
131 .IP
132 The above behavior when the size of the user-space
133 .I sched_attr
134 structure does not match the size of the kernel structure
135 allows for future extensibility of the interface.
136 Malformed applications that pass oversize structures
137 won't break in the future if the size of the kernel
138 .I sched_attr
139 structure is increased.
140 In the future,
141 it could also allow applications that know about a larger user-space
142 .I sched_attr
143 structure to determine whether they are running on an older kernel
144 that does not support the larger structure.
145 .TP
146 .I sched_policy
147 This field specifies the scheduling policy, as one of the
148 .B SCHED_*
149 values listed above.
150 .TP
151 .I sched_flags
152 This field contains zero or more of the following flags
153 that are ORed together to control scheduling behavior:
154 .RS
155 .TP
156 .B SCHED_FLAG_RESET_ON_FORK
157 Children created by
158 .BR fork (2)
159 do not inherit privileged scheduling policies.
160 See
161 .BR sched (7)
162 for details.
163 .TP
164 .BR SCHED_FLAG_RECLAIM " (since Linux 4.13)"
165 .\" 2d4283e9d583a3ee8cfb1cbb9c1270614df4c29d
166 This flag allows a
167 .B SCHED_DEADLINE
168 thread to reclaim bandwidth unused by other real-time threads.
169 .\" Bandwidth reclaim is done via the GRUB algorithm; see
170 .\" Documentation/scheduler/sched-deadline.rst
171 .TP
172 .BR SCHED_FLAG_DL_OVERRUN " (since Linux 4.16)"
173 .\" commit 34be39305a77b8b1ec9f279163c7cdb6cc719b91
174 This flag allows an application to get informed about run-time overruns in
175 .B SCHED_DEADLINE
176 threads.
177 Such overruns may be caused by (for example) coarse execution time accounting
178 or incorrect parameter assignment.
179 Notification takes the form of a
180 .B SIGXCPU
181 signal which is generated on each overrun.
182 .IP
183 This
184 .B SIGXCPU
185 signal is
186 .I process-directed
187 (see
188 .BR signal (7))
189 rather than thread-directed.
190 This is probably a bug.
191 On the one hand,
192 .BR sched_setattr ()
193 is being used to set a per-thread attribute.
194 On the other hand, if the process-directed signal is delivered to
195 a thread inside the process other than the one that had a run-time overrun,
196 the application has no way of knowing which thread overran.
197 .TP
198 .B SCHED_FLAG_UTIL_CLAMP_MIN
199 .TQ
200 .BR SCHED_FLAG_UTIL_CLAMP_MAX " (both since Linux 5.3)"
201 These flags indicate that the
202 .I
203 sched_util_min
204 or
205 .I
206 sched_util_max
207 fields, respectively, are present,
208 representing the expected minimum and maximum utilization of the thread.
209 .IP
210 The utilization attributes provide the scheduler with boundaries
211 within which it should schedule the thread,
212 potentially informing its decisions
213 regarding task placement and frequency selection.
214 .RE
215 .TP
216 .I sched_nice
217 This field specifies the nice value to be set when specifying
218 .I sched_policy
219 as
220 .B SCHED_OTHER
221 or
222 .BR SCHED_BATCH .
223 The nice value is a number in the range \-20 (high priority)
224 to +19 (low priority);
225 see
226 .BR sched (7).
227 .TP
228 .I sched_priority
229 This field specifies the static priority to be set when specifying
230 .I sched_policy
231 as
232 .B SCHED_FIFO
233 or
234 .BR SCHED_RR .
235 The allowed range of priorities for these policies can be determined using
236 .BR sched_get_priority_min (2)
237 and
238 .BR sched_get_priority_max (2).
239 For other policies, this field must be specified as 0.
240 .TP
241 .I sched_runtime
242 This field specifies the "Runtime" parameter for deadline scheduling.
243 The value is expressed in nanoseconds.
244 This field, and the next two fields,
245 are used only for
246 .B SCHED_DEADLINE
247 scheduling;
248 for further details,
249 see
250 .BR sched (7).
251 .TP
252 .I sched_deadline
253 This field specifies the "Deadline" parameter for deadline scheduling.
254 The value is expressed in nanoseconds.
255 .TP
256 .I sched_period
257 This field specifies the "Period" parameter for deadline scheduling.
258 The value is expressed in nanoseconds.
259 .TP
260 .I sched_util_min
261 .TQ
262 .IR sched_util_max " (both since Linux 5.3)"
263 These fields specify the expected minimum and maximum utilization, respectively.
264 They are ignored unless their corresponding
265 .B SCHED_FLAG_UTIL_CLAMP_MIN
266 or
267 .B SCHED_FLAG_UTIL_CLAMP_MAX
268 is set in
269 .IR sched_flags .
270 .IP
271 Utilization is a value in the range [0, 1024], representing the percentage of
272 CPU time used by a task when running at the maximum frequency
273 on the highest capacity CPU of the system.
274 This is a fixed point representation, where 1024 corresponds to 100%,
275 and 0 corresponds to 0%.
276 For example,
277 a 20% utilization task is
278 a task running for 2ms every 10ms at maximum frequency and is represented by a
279 utilization value of
280 .IR 0.2\~*\~1024\~=\~205 .
281 .IP
282 A task with a minimum utilization value larger than 0 is more likely
283 scheduled on a CPU with a capacity big enough to fit the specified value.
284 A task with a maximum utilization value smaller than 1024 is more likely
285 scheduled on a CPU with no more capacity than the specified value.
286 .IP
287 A task utilization boundary can be reset by setting its field to
288 .B UINT32_MAX
289 (since Linux 5.11).
290 .P
291 The
292 .I flags
293 argument is provided to allow for future extensions to the interface;
294 in the current implementation it must be specified as 0.
295 .\"
296 .\"
297 .SS sched_getattr()
298 The
299 .BR sched_getattr ()
300 system call fetches the scheduling policy and the
301 associated attributes for the thread whose ID is specified in
302 .IR pid .
303 If
304 .I pid
305 equals zero,
306 the scheduling policy and attributes of the calling thread
307 will be retrieved.
308 .P
309 The
310 .I size
311 argument should be set to the size of the
312 .I sched_attr
313 structure as known to user space.
314 The value must be at least as large as the size of the initially published
315 .I sched_attr
316 structure, or the call fails with the error
317 .BR EINVAL .
318 .P
319 The retrieved scheduling attributes are placed in the fields of the
320 .I sched_attr
321 structure pointed to by
322 .IR attr .
323 The kernel sets
324 .I attr.size
325 to the size of its
326 .I sched_attr
327 structure.
328 .P
329 If the caller-provided
330 .I attr
331 buffer is larger than the kernel's
332 .I sched_attr
333 structure,
334 the additional bytes in the user-space structure are not touched.
335 If the caller-provided structure is smaller than the kernel
336 .I sched_attr
337 structure, the kernel will silently not return any values which would be stored
338 outside the provided space.
339 As with
340 .BR sched_setattr (),
341 these semantics allow for future extensibility of the interface.
342 .P
343 The
344 .I flags
345 argument is provided to allow for future extensions to the interface;
346 in the current implementation it must be specified as 0.
347 .SH RETURN VALUE
348 On success,
349 .BR sched_setattr ()
350 and
351 .BR sched_getattr ()
352 return 0.
353 On error, \-1 is returned, and
354 .I errno
355 is set to indicate the error.
356 .SH ERRORS
357 .BR sched_getattr ()
358 and
359 .BR sched_setattr ()
360 can both fail for the following reasons:
361 .TP
362 .B EINVAL
363 .I attr
364 is NULL;
365 or
366 .I pid
367 is negative;
368 or
369 .I flags
370 is not zero.
371 .TP
372 .B ESRCH
373 The thread whose ID is
374 .I pid
375 could not be found.
376 .P
377 In addition,
378 .BR sched_getattr ()
379 can fail for the following reasons:
380 .TP
381 .B E2BIG
382 The buffer specified by
383 .I size
384 and
385 .I attr
386 is too small.
387 .TP
388 .B EINVAL
389 .I size
390 is invalid;
391 that is,
392 it is smaller than the initial version of the
393 .I sched_attr
394 structure (48 bytes) or larger than the system page size.
395 .P
396 In addition,
397 .BR sched_setattr ()
398 can fail for the following reasons:
399 .TP
400 .B E2BIG
401 The buffer specified by
402 .I size
403 and
404 .I attr
405 is larger than the kernel structure,
406 and one or more of the excess bytes is nonzero.
407 .TP
408 .B EBUSY
409 .B SCHED_DEADLINE
410 admission control failure, see
411 .BR sched (7).
412 .TP
413 .B EINVAL
414 .I attr.sched_policy
415 is not one of the recognized policies.
416 .TP
417 .B EINVAL
418 .I attr.sched_flags
419 contains a flag other than
420 .BR SCHED_FLAG_RESET_ON_FORK .
421 .TP
422 .B EINVAL
423 .I attr.sched_priority
424 is invalid.
425 .TP
426 .B EINVAL
427 .I attr.sched_policy
428 is
429 .BR SCHED_DEADLINE ,
430 and the deadline scheduling parameters in
431 .I attr
432 are invalid.
433 .TP
434 .B EINVAL
435 .I attr.sched_flags
436 contains
437 .B SCHED_FLAG_UTIL_CLAMP_MIN
438 or
439 .BR SCHED_FLAG_UTIL_CLAMP_MAX ,
440 and
441 .I attr.sched_util_min
442 or
443 .I attr.sched_util_max
444 are out of bounds.
445 .TP
446 .B EOPNOTSUPP
447 .B SCHED_FLAG_UTIL_CLAMP
448 was provided, but the kernel was not built with
449 .B CONFIG_UCLAMP_TASK
450 support.
451 .TP
452 .B EPERM
453 The caller does not have appropriate privileges.
454 .TP
455 .B EPERM
456 The CPU affinity mask of the thread specified by
457 .I pid
458 does not include all CPUs in the system
459 (see
460 .BR sched_setaffinity (2)).
461 .SH STANDARDS
462 Linux.
463 .SH HISTORY
464 Linux 3.14.
465 .\" FIXME . Add glibc version
466 .SH NOTES
467 glibc does not provide wrappers for these system calls;
468 call them using
469 .BR syscall (2).
470 .P
471 .BR sched_setattr ()
472 provides a superset of the functionality of
473 .BR sched_setscheduler (2),
474 .BR sched_setparam (2),
475 .BR nice (2),
476 and (other than the ability to set the priority of all processes
477 belonging to a specified user or all processes in a specified group)
478 .BR setpriority (2).
479 Analogously,
480 .BR sched_getattr ()
481 provides a superset of the functionality of
482 .BR sched_getscheduler (2),
483 .BR sched_getparam (2),
484 and (partially)
485 .BR getpriority (2).
486 .SH BUGS
487 In Linux versions up to
488 .\" FIXME . patch sent to Peter Zijlstra
489 3.15,
490 .BR sched_setattr ()
491 failed with the error
492 .B EFAULT
493 instead of
494 .B E2BIG
495 for the case described in ERRORS.
496 .P
497 Up to Linux 5.3,
498 .BR sched_getattr ()
499 failed with the error
500 .B EFBIG
501 if the in-kernel
502 .I sched_attr
503 structure was larger than the
504 .I size
505 passed by user space.
506 .\" In Linux versions up to up 3.15,
507 .\" FIXME . patch from Peter Zijlstra pending
508 .\" .BR sched_setattr ()
509 .\" allowed a negative
510 .\" .I attr.sched_policy
511 .\" value.
512 .SH SEE ALSO
513 .ad l
514 .nh
515 .BR chrt (1),
516 .BR nice (2),
517 .BR sched_get_priority_max (2),
518 .BR sched_get_priority_min (2),
519 .BR sched_getaffinity (2),
520 .BR sched_getparam (2),
521 .BR sched_getscheduler (2),
522 .BR sched_rr_get_interval (2),
523 .BR sched_setaffinity (2),
524 .BR sched_setparam (2),
525 .BR sched_setscheduler (2),
526 .BR sched_yield (2),
527 .BR setpriority (2),
528 .BR pthread_getschedparam (3),
529 .BR pthread_setschedparam (3),
530 .BR pthread_setschedprio (3),
531 .BR capabilities (7),
532 .BR cpuset (7),
533 .BR sched (7)
534 .ad