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