]>
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 | |
153 | This field contains flags controlling scheduling behavior. | |
154 | Only one such flag is currently defined: | |
155 | .BR SCHED_FLAG_RESET_ON_FORK . | |
156 | As a result of including this flag, children created by | |
157 | .BR fork (2) | |
158 | do not inherit privileged scheduling policies. | |
159 | See | |
160 | .BR sched (7) | |
161 | for details. | |
162 | .TP | |
163 | .I sched_nice | |
164 | This field specifies the nice value to be set when specifying | |
165 | .IR sched_policy | |
166 | as | |
167 | .BR SCHED_OTHER | |
168 | or | |
169 | .BR SCHED_BATCH . | |
170 | The nice value is a number in the range \-20 (high priority) | |
171 | to +19 (low priority); see | |
9b7b2ea5 | 172 | .BR sched (7). |
225d97f2 MK |
173 | .TP |
174 | .I sched_priority | |
175 | This field specifies the static priority to be set when specifying | |
176 | .IR sched_policy | |
177 | as | |
178 | .BR SCHED_FIFO | |
179 | or | |
180 | .BR SCHED_RR . | |
181 | The allowed range of priorities for these policies can be determined using | |
182 | .BR sched_get_priority_min (2) | |
183 | and | |
184 | .BR sched_get_priority_max (2). | |
185 | For other policies, this field must be specified as 0. | |
186 | .TP | |
187 | .I sched_runtime | |
188 | This field specifies the "Runtime" parameter for deadline scheduling. | |
189 | The value is expressed in nanoseconds. | |
190 | This field, and the next two fields, | |
191 | are used only for | |
0da5e58a | 192 | .BR SCHED_DEADLINE |
225d97f2 MK |
193 | scheduling; for further details, see |
194 | .BR sched (7). | |
195 | .TP | |
196 | .I sched_deadline | |
197 | This field specifies the "Deadline" parameter for deadline scheduling. | |
198 | The value is expressed in nanoseconds. | |
199 | .TP | |
200 | .I sched_period | |
201 | This field specifies the "Period" parameter for deadline scheduling. | |
202 | The value is expressed in nanoseconds. | |
203 | .PP | |
204 | The | |
205 | .I flags | |
206 | argument is provided to allow for future extensions to the interface; | |
207 | in the current implementation it must be specified as 0. | |
208 | .\" | |
209 | .\" | |
210 | .SS sched_getattr() | |
211 | The | |
212 | .BR sched_getattr () | |
213 | system call fetches the scheduling policy and the | |
214 | associated attributes for the thread whose ID is specified in | |
215 | .IR pid . | |
216 | If | |
217 | .I pid | |
218 | equals zero, | |
219 | the scheduling policy and attributes of the calling thread | |
220 | will be retrieved. | |
efeece04 | 221 | .PP |
225d97f2 MK |
222 | The |
223 | .I size | |
224 | argument should be set to the size of the | |
225 | .I sched_attr | |
226 | structure as known to user space. | |
227 | The value must be at least as large as the size of the initially published | |
228 | .I sched_attr | |
229 | structure, or the call fails with the error | |
230 | .BR EINVAL . | |
efeece04 | 231 | .PP |
225d97f2 MK |
232 | The retrieved scheduling attributes are placed in the fields of the |
233 | .I sched_attr | |
234 | structure pointed to by | |
235 | .IR attr . | |
236 | The kernel sets | |
237 | .I attr.size | |
238 | to the size of its | |
239 | .I sched_attr | |
240 | structure. | |
efeece04 | 241 | .PP |
225d97f2 MK |
242 | If the caller-provided |
243 | .I attr | |
244 | buffer is larger than the kernel's | |
245 | .I sched_attr | |
246 | structure, | |
247 | the additional bytes in the user-space structure are not touched. | |
248 | If the caller-provided structure is smaller than the kernel | |
249 | .I sched_attr | |
250 | structure and the kernel needs to return values outside the provided space, | |
251 | .BR sched_getattr () | |
252 | fails with the error | |
253 | .BR E2BIG . | |
254 | As with | |
255 | .BR sched_setattr (), | |
256 | these semantics allow for future extensibility of the interface. | |
efeece04 | 257 | .PP |
225d97f2 MK |
258 | The |
259 | .I flags | |
260 | argument is provided to allow for future extensions to the interface; | |
261 | in the current implementation it must be specified as 0. | |
262 | .SH RETURN VALUE | |
263 | On success, | |
264 | .BR sched_setattr () | |
265 | and | |
266 | .BR sched_getattr () | |
267 | return 0. | |
268 | On error, \-1 is returned, and | |
269 | .I errno | |
270 | is set to indicate the cause of the error. | |
271 | .SH ERRORS | |
272 | .BR sched_getattr () | |
273 | and | |
274 | .BR sched_setattr () | |
275 | can both fail for the following reasons: | |
276 | .TP | |
277 | .B EINVAL | |
278 | .I attr | |
279 | is NULL; or | |
280 | .I pid | |
281 | is negative; or | |
282 | .I flags | |
283 | is not zero. | |
284 | .TP | |
285 | .B ESRCH | |
286 | The thread whose ID is | |
287 | .I pid | |
288 | could not be found. | |
289 | .PP | |
290 | In addition, | |
291 | .BR sched_getattr () | |
292 | can fail for the following reasons: | |
293 | .TP | |
294 | .B E2BIG | |
295 | The buffer specified by | |
296 | .I size | |
297 | and | |
298 | .I attr | |
299 | is too small. | |
300 | .TP | |
301 | .B EINVAL | |
302 | .I size | |
303 | is invalid; that is, it is smaller than the initial version of the | |
304 | .I sched_attr | |
305 | structure (48 bytes) or larger than the system page size. | |
306 | .PP | |
307 | In addition, | |
308 | .BR sched_setattr () | |
309 | can fail for the following reasons: | |
310 | .TP | |
311 | .B E2BIG | |
312 | The buffer specified by | |
313 | .I size | |
314 | and | |
315 | .I attr | |
316 | is larger than the kernel structure, | |
317 | and one or more of the excess bytes is nonzero. | |
318 | .TP | |
319 | .B EBUSY | |
320 | .B SCHED_DEADLINE | |
321 | admission control failure, see | |
322 | .BR sched (7). | |
323 | .TP | |
324 | .B EINVAL | |
325 | .I attr.sched_policy | |
326 | is not one of the recognized policies; | |
327 | .I attr.sched_flags | |
328 | contains a flag other than | |
329 | .BR SCHED_FLAG_RESET_ON_FORK ; | |
330 | or | |
331 | .I attr.sched_priority | |
332 | is invalid; or | |
333 | .I attr.sched_policy | |
334 | is | |
335 | .BR SCHED_DEADLINE | |
336 | and the deadline scheduling parameters in | |
337 | .I attr | |
338 | are invalid. | |
339 | .TP | |
340 | .B EPERM | |
341 | The caller does not have appropriate privileges. | |
342 | .TP | |
343 | .B EPERM | |
4a6f17b5 MK |
344 | The CPU affinity mask of the thread specified by |
345 | .I pid | |
225d97f2 MK |
346 | does not include all CPUs in the system |
347 | (see | |
348 | .BR sched_setaffinity (2)). | |
349 | .SH VERSIONS | |
350 | These system calls first appeared in Linux 3.14. | |
bea08fec | 351 | .\" FIXME . Add glibc version |
225d97f2 MK |
352 | .SH CONFORMING TO |
353 | These system calls are nonstandard Linux extensions. | |
354 | .SH NOTES | |
355 | .BR sched_setattr () | |
356 | provides a superset of the functionality of | |
357 | .BR sched_setscheduler (2), | |
358 | .BR sched_setparam (2), | |
359 | .BR nice (2), | |
360 | and (other than the ability to set the priority of all processes | |
361 | belonging to a specified user or all processes in a specified group) | |
362 | .BR setpriority (2). | |
363 | Analogously, | |
1b05b97a | 364 | .BR sched_getattr () |
225d97f2 MK |
365 | provides a superset of the functionality of |
366 | .BR sched_getscheduler (2), | |
367 | .BR sched_getparam (2), | |
368 | and (partially) | |
369 | .BR getpriority (2). | |
370 | .SH BUGS | |
371 | In Linux versions up to | |
bea08fec | 372 | .\" FIXME . patch sent to Peter Zijlstra |
225d97f2 MK |
373 | 3.15, |
374 | .BR sched_settattr () | |
375 | failed with the error | |
376 | .BR EFAULT | |
377 | instead of | |
378 | .BR E2BIG | |
379 | for the case described in ERRORS. | |
380 | .\" In Linux versions up to up 3.15, | |
bea08fec | 381 | .\" FIXME . patch from Peter Zijlstra pending |
225d97f2 MK |
382 | .\" .BR sched_setattr () |
383 | .\" allowed a negative | |
384 | .\" .I attr.sched_policy | |
385 | .\" value. | |
386 | .SH SEE ALSO | |
387 | .ad l | |
388 | .nh | |
ac30de07 | 389 | .BR chrt (1), |
225d97f2 MK |
390 | .BR nice (2), |
391 | .BR sched_get_priority_max (2), | |
392 | .BR sched_get_priority_min (2), | |
393 | .BR sched_getaffinity (2), | |
225d97f2 | 394 | .BR sched_getparam (2), |
03768726 | 395 | .BR sched_getscheduler (2), |
225d97f2 MK |
396 | .BR sched_rr_get_interval (2), |
397 | .BR sched_setaffinity (2), | |
225d97f2 | 398 | .BR sched_setparam (2), |
03768726 | 399 | .BR sched_setscheduler (2), |
225d97f2 MK |
400 | .BR sched_yield (2), |
401 | .BR setpriority (2), | |
402 | .BR pthread_getschedparam (3), | |
403 | .BR pthread_setschedparam (3), | |
404 | .BR pthread_setschedprio (3), | |
405 | .BR capabilities (7), | |
406 | .BR cpuset (7), | |
407 | .BR sched (7) | |
408 | .ad |