Debian Codegraph @

upstream/debian-trixie/man2/sched_setattr.2

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