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