]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999 |
cf9c27a6 | 2 | .\" and Copyright (C) 2007 Carsten Emde <Carsten.Emde@osadl.org> |
a3a22b7f | 3 | .\" and Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
1dd72f9c | 5 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
6 | .\" This is free documentation; you can redistribute it and/or |
7 | .\" modify it under the terms of the GNU General Public License as | |
8 | .\" published by the Free Software Foundation; either version 2 of | |
9 | .\" the License, or (at your option) any later version. | |
10 | .\" | |
11 | .\" The GNU General Public License's references to "object code" | |
12 | .\" and "executables" are to be interpreted as the output of any | |
13 | .\" document formatting or typesetting system, including | |
14 | .\" intermediate and printed output. | |
15 | .\" | |
16 | .\" This manual is distributed in the hope that it will be useful, | |
17 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 | .\" GNU General Public License for more details. | |
20 | .\" | |
21 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
22 | .\" License along with this manual; if not, see |
23 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" 1996-04-01 Tom Bjorkholm <tomb@mydata.se> | |
27 | .\" First version written | |
28 | .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> | |
29 | .\" revision | |
30 | .\" 1999-08-18 David A. Wheeler <dwheeler@ida.org> added Note. | |
c11b1abf | 31 | .\" Modified, 25 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com> |
c13182ef | 32 | .\" Corrected description of queue placement by sched_setparam() and |
fea681da MK |
33 | .\" sched_setscheduler() |
34 | .\" A couple of grammar clean-ups | |
c11b1abf | 35 | .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
92c37d8c | 36 | .\" 2005-03-23, mtk, Added description of SCHED_BATCH. |
cf9c27a6 MK |
37 | .\" 2007-07-10, Carsten Emde <Carsten.Emde@osadl.org> |
38 | .\" Add text on real-time features that are currently being | |
39 | .\" added to the mainline kernel. | |
a1d5601b | 40 | .\" 2008-05-07, mtk; Rewrote and restructured various parts of the page to |
a3a22b7f | 41 | .\" improve readability. |
93414d35 | 42 | .\" 2010-06-19, mtk, documented SCHED_RESET_ON_FORK |
fea681da | 43 | .\" |
9b6ba4d8 | 44 | .\" Worth looking at: http://rt.wiki.kernel.org/index.php |
3787794c | 45 | .\" |
48b6f086 | 46 | .TH SCHED_SETSCHEDULER 2 2013-09-17 "Linux" "Linux Programmer's Manual" |
fea681da MK |
47 | .SH NAME |
48 | sched_setscheduler, sched_getscheduler \- | |
a3a22b7f | 49 | set and get scheduling policy/parameters |
fea681da | 50 | .SH SYNOPSIS |
92c37d8c | 51 | .nf |
fea681da MK |
52 | .B #include <sched.h> |
53 | .sp | |
54 | .BI "int sched_setscheduler(pid_t " pid ", int " policy , | |
92c37d8c MK |
55 | .br |
56 | .BI " const struct sched_param *" param ); | |
fea681da MK |
57 | .sp |
58 | .BI "int sched_getscheduler(pid_t " pid ); | |
59 | .sp | |
fea681da | 60 | \fBstruct sched_param { |
92c37d8c MK |
61 | ... |
62 | int \fIsched_priority\fB; | |
63 | ... | |
fea681da | 64 | }; |
fea681da MK |
65 | .fi |
66 | .SH DESCRIPTION | |
e511ffb6 | 67 | .BR sched_setscheduler () |
fea681da | 68 | sets both the scheduling policy and the associated parameters for the |
81bd66da | 69 | thread whose ID is specified in \fIpid\fP. |
c13182ef | 70 | If \fIpid\fP equals zero, the |
81bd66da | 71 | scheduling policy and parameters of the calling thread will be set. |
c13182ef | 72 | The interpretation of |
c126cfd6 | 73 | the argument \fIparam\fP depends on the selected policy. |
4e592516 MK |
74 | Currently, Linux supports the following "normal" |
75 | (i.e., non-real-time) scheduling policies: | |
a3a22b7f | 76 | .TP 14 |
a1d5601b MK |
77 | .BR SCHED_OTHER |
78 | the standard round-robin time-sharing policy; | |
c13182ef | 79 | .\" In the 2.6 kernel sources, SCHED_OTHER is actually called |
92c37d8c | 80 | .\" SCHED_NORMAL. |
a3a22b7f MK |
81 | .TP |
82 | .BR SCHED_BATCH | |
83 | for "batch" style execution of processes; and | |
84 | .TP | |
85 | .BR SCHED_IDLE | |
86 | for running | |
87 | .I very | |
88 | low priority background jobs. | |
89 | .PP | |
90 | The following "real-time" policies are also supported, | |
91 | for special time-critical applications that need precise control over | |
81bd66da | 92 | the way in which runnable threads are selected for execution: |
a3a22b7f MK |
93 | .TP 14 |
94 | .BR SCHED_FIFO | |
95 | a first-in, first-out policy; and | |
96 | .TP | |
97 | .BR SCHED_RR | |
98 | a round-robin policy. | |
99 | .PP | |
100 | The semantics of each of these policies are detailed below. | |
fea681da | 101 | |
e511ffb6 | 102 | .BR sched_getscheduler () |
81bd66da | 103 | queries the scheduling policy currently applied to the thread |
c13182ef MK |
104 | identified by \fIpid\fP. |
105 | If \fIpid\fP equals zero, the policy of the | |
81bd66da | 106 | calling thread will be retrieved. |
a3a22b7f | 107 | .\" |
c634028a | 108 | .SS Scheduling policies |
81bd66da | 109 | The scheduler is the kernel component that decides which runnable thread |
c13182ef | 110 | will be executed by the CPU next. |
81bd66da | 111 | Each thread has an associated scheduling policy and a \fIstatic\fP |
a3a22b7f MK |
112 | scheduling priority, \fIsched_priority\fP; these are the settings |
113 | that are modified by | |
114 | .BR sched_setscheduler (). | |
115 | The scheduler makes it decisions based on knowledge of the scheduling | |
81bd66da | 116 | policy and static priority of all threads on the system. |
fea681da | 117 | |
81bd66da | 118 | For threads scheduled under one of the normal scheduling policies |
a3a22b7f MK |
119 | (\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), |
120 | \fIsched_priority\fP is not used in scheduling | |
121 | decisions (it must be specified as 0). | |
92c37d8c | 122 | |
a1d5601b | 123 | Processes scheduled under one of the real-time policies |
a3a22b7f MK |
124 | (\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a |
125 | \fIsched_priority\fP value in the range 1 (low) to 99 (high). | |
81bd66da MK |
126 | (As the numbers imply, real-time threads always have higher priority |
127 | than normal threads.) | |
33a0ccb2 | 128 | Note well: POSIX.1-2001 requires an implementation to support only a |
a3a22b7f | 129 | minimum 32 distinct priority levels for the real-time policies, |
6c74a966 | 130 | and some systems supply just this minimum. |
a3a22b7f | 131 | Portable programs should use |
60a90ecd MK |
132 | .BR sched_get_priority_min (2) |
133 | and | |
134 | .BR sched_get_priority_max (2) | |
a3a22b7f | 135 | to find the range of priorities supported for a particular policy. |
fea681da | 136 | |
a3a22b7f | 137 | Conceptually, the scheduler maintains a list of runnable |
81bd66da MK |
138 | threads for each possible \fIsched_priority\fP value. |
139 | In order to determine which thread runs next, the scheduler looks for | |
aa796481 | 140 | the nonempty list with the highest static priority and selects the |
81bd66da | 141 | thread at the head of this list. |
a3a22b7f | 142 | |
81bd66da MK |
143 | A thread's scheduling policy determines |
144 | where it will be inserted into the list of threads | |
a3a22b7f MK |
145 | with equal static priority and how it will move inside this list. |
146 | ||
81bd66da MK |
147 | All scheduling is preemptive: if a thread with a higher static |
148 | priority becomes ready to run, the currently running thread | |
a3a22b7f MK |
149 | will be preempted and |
150 | returned to the wait list for its static priority level. | |
33a0ccb2 | 151 | The scheduling policy determines the |
81bd66da | 152 | ordering only within the list of runnable threads with equal static |
fea681da | 153 | priority. |
c634028a | 154 | .SS SCHED_FIFO: First in-first out scheduling |
33a0ccb2 | 155 | \fBSCHED_FIFO\fP can be used only with static priorities higher than |
81bd66da | 156 | 0, which means that when a \fBSCHED_FIFO\fP threads becomes runnable, |
92c37d8c | 157 | it will always immediately preempt any currently running |
81bd66da | 158 | \fBSCHED_OTHER\fP, \fBSCHED_BATCH\fP, or \fBSCHED_IDLE\fP thread. |
5917ad3d | 159 | \fBSCHED_FIFO\fP is a simple scheduling |
c13182ef | 160 | algorithm without time slicing. |
81bd66da | 161 | For threads scheduled under the |
a3a22b7f MK |
162 | \fBSCHED_FIFO\fP policy, the following rules apply: |
163 | .IP * 3 | |
81bd66da | 164 | A \fBSCHED_FIFO\fP thread that has been preempted by another thread of |
fea681da | 165 | higher priority will stay at the head of the list for its priority and |
81bd66da | 166 | will resume execution as soon as all threads of higher priority are |
c13182ef | 167 | blocked again. |
a3a22b7f | 168 | .IP * |
81bd66da | 169 | When a \fBSCHED_FIFO\fP thread becomes runnable, it |
c13182ef | 170 | will be inserted at the end of the list for its priority. |
a3a22b7f | 171 | .IP * |
c13182ef | 172 | A call to |
60a90ecd MK |
173 | .BR sched_setscheduler () |
174 | or | |
175 | .BR sched_setparam (2) | |
176 | will put the | |
81bd66da | 177 | \fBSCHED_FIFO\fP (or \fBSCHED_RR\fP) thread identified by |
fea681da | 178 | \fIpid\fP at the start of the list if it was runnable. |
81bd66da | 179 | As a consequence, it may preempt the currently running thread if |
fea681da | 180 | it has the same priority. |
81bd66da | 181 | (POSIX.1-2001 specifies that the thread should go to the end |
fea681da | 182 | of the list.) |
81bd66da MK |
183 | .\" In 2.2.x and 2.4.x, the thread is placed at the front of the queue |
184 | .\" In 2.0.x, the Right Thing happened: the thread went to the back -- MTK | |
a3a22b7f | 185 | .IP * |
81bd66da | 186 | A thread calling |
60a90ecd | 187 | .BR sched_yield (2) |
a3a22b7f MK |
188 | will be put at the end of the list. |
189 | .PP | |
81bd66da | 190 | No other events will move a thread |
5917ad3d | 191 | scheduled under the \fBSCHED_FIFO\fP policy in the wait list of |
81bd66da | 192 | runnable threads with equal static priority. |
a3a22b7f | 193 | |
5917ad3d | 194 | A \fBSCHED_FIFO\fP |
81bd66da MK |
195 | thread runs until either it is blocked by an I/O request, it is |
196 | preempted by a higher priority thread, or it calls | |
60a90ecd | 197 | .BR sched_yield (2). |
c634028a | 198 | .SS SCHED_RR: Round-robin scheduling |
5917ad3d | 199 | \fBSCHED_RR\fP is a simple enhancement of \fBSCHED_FIFO\fP. |
c13182ef | 200 | Everything |
5917ad3d | 201 | described above for \fBSCHED_FIFO\fP also applies to \fBSCHED_RR\fP, |
81bd66da | 202 | except that each thread is allowed to run only for a maximum time |
c13182ef | 203 | quantum. |
81bd66da | 204 | If a \fBSCHED_RR\fP thread has been running for a time |
fea681da | 205 | period equal to or longer than the time quantum, it will be put at the |
c13182ef | 206 | end of the list for its priority. |
81bd66da MK |
207 | A \fBSCHED_RR\fP thread that has |
208 | been preempted by a higher priority thread and subsequently resumes | |
209 | execution as a running thread will complete the unexpired portion of | |
c634028a | 210 | its round-robin time quantum. |
c13182ef | 211 | The length of the time quantum can be |
60a90ecd MK |
212 | retrieved using |
213 | .BR sched_rr_get_interval (2). | |
fea681da MK |
214 | .\" On Linux 2.4, the length of the RR interval is influenced |
215 | .\" by the process nice value -- MTK | |
af800319 | 216 | .\" |
fea681da | 217 | .SS SCHED_OTHER: Default Linux time-sharing scheduling |
33a0ccb2 | 218 | \fBSCHED_OTHER\fP can be used at only static priority 0. |
5917ad3d | 219 | \fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is |
81bd66da | 220 | intended for all threads that do not require the special |
c13182ef | 221 | real-time mechanisms. |
81bd66da | 222 | The thread to run is chosen from the static |
a3a22b7f | 223 | priority 0 list based on a \fIdynamic\fP priority that is determined only |
c13182ef | 224 | inside this list. |
a3a22b7f | 225 | The dynamic priority is based on the nice value (set by |
60a90ecd MK |
226 | .BR nice (2) |
227 | or | |
228 | .BR setpriority (2)) | |
81bd66da | 229 | and increased for each time quantum the thread is ready to run, |
a3a22b7f | 230 | but denied to run by the scheduler. |
81bd66da | 231 | This ensures fair progress among all \fBSCHED_OTHER\fP threads. |
a3a22b7f | 232 | .\" |
92c37d8c MK |
233 | .SS SCHED_BATCH: Scheduling batch processes |
234 | (Since Linux 2.6.16.) | |
33a0ccb2 | 235 | \fBSCHED_BATCH\fP can be used only at static priority 0. |
6958017f | 236 | This policy is similar to \fBSCHED_OTHER\fP in that it schedules |
81bd66da | 237 | the thread according to its dynamic priority |
6958017f MK |
238 | (based on the nice value). |
239 | The difference is that this policy | |
240 | will cause the scheduler to always assume | |
81bd66da | 241 | that the thread is CPU-intensive. |
92c37d8c | 242 | Consequently, the scheduler will apply a small scheduling |
c00194ab | 243 | penalty with respect to wakeup behaviour, |
81bd66da | 244 | so that this thread is mildly disfavored in scheduling decisions. |
a3a22b7f | 245 | |
c13182ef MK |
246 | .\" The following paragraph is drawn largely from the text that |
247 | .\" accompanied Ingo Molnar's patch for the implementation of | |
92c37d8c | 248 | .\" SCHED_BATCH. |
4d66746f | 249 | .\" commit b0a9499c3dd50d333e2aedb7e894873c58da3785 |
24b74457 | 250 | This policy is useful for workloads that are noninteractive, |
c13182ef MK |
251 | but do not want to lower their nice value, |
252 | and for workloads that want a deterministic scheduling policy without | |
92c37d8c | 253 | interactivity causing extra preemptions (between the workload's tasks). |
c00194ab MK |
254 | .\" |
255 | .SS SCHED_IDLE: Scheduling very low priority jobs | |
256 | (Since Linux 2.6.23.) | |
33a0ccb2 | 257 | \fBSCHED_IDLE\fP can be used only at static priority 0; |
c00194ab | 258 | the process nice value has no influence for this policy. |
a3a22b7f | 259 | |
c00194ab MK |
260 | This policy is intended for running jobs at extremely low |
261 | priority (lower even than a +19 nice value with the | |
262 | .B SCHED_OTHER | |
263 | or | |
264 | .B SCHED_BATCH | |
265 | policies). | |
266 | .\" | |
93414d35 MK |
267 | .SS Resetting scheduling policy for child processes |
268 | Since Linux 2.6.32, the | |
269 | .B SCHED_RESET_ON_FORK | |
270 | flag can be ORed in | |
271 | .I policy | |
272 | when calling | |
273 | .BR sched_setscheduler (). | |
274 | As a result of including this flag, children created by | |
275 | .BR fork (2) | |
276 | do not inherit privileged scheduling policies. | |
277 | This feature is intended for media-playback applications, | |
278 | and can be used to prevent applications evading the | |
279 | .BR RLIMIT_RTTIME | |
280 | resource limit (see | |
281 | .BR getrlimit (2)) | |
282 | by creating multiple child processes. | |
283 | ||
284 | More precisely, if the | |
285 | .BR SCHED_RESET_ON_FORK | |
286 | flag is specified, | |
287 | the following rules apply for subsequently created children: | |
288 | .IP * 3 | |
81bd66da | 289 | If the calling thread has a scheduling policy of |
93414d35 MK |
290 | .B SCHED_FIFO |
291 | or | |
292 | .BR SCHED_RR , | |
293 | the policy is reset to | |
294 | .BR SCHED_OTHER | |
295 | in child processes. | |
296 | .IP * | |
038dff66 | 297 | If the calling process has a negative nice value, |
93414d35 MK |
298 | the nice value is reset to zero in child processes. |
299 | .PP | |
300 | After the | |
301 | .BR SCHED_RESET_ON_FORK | |
302 | flag has been enabled, | |
81bd66da | 303 | it can be reset only if the thread has the |
93414d35 MK |
304 | .BR CAP_SYS_NICE |
305 | capability. | |
306 | This flag is disabled in child processes created by | |
307 | .BR fork (2). | |
308 | ||
309 | The | |
310 | .B SCHED_RESET_ON_FORK | |
311 | flag is visible in the policy value returned by | |
312 | .BR sched_getscheduler () | |
313 | .\" | |
fd04afa8 | 314 | .SS Privileges and resource limits |
fd04afa8 MK |
315 | In Linux kernels before 2.6.12, only privileged |
316 | .RB ( CAP_SYS_NICE ) | |
81bd66da | 317 | threads can set a nonzero static priority (i.e., set a real-time |
a3a22b7f | 318 | scheduling policy). |
81bd66da | 319 | The only change that an unprivileged thread can make is to set the |
afdee10d | 320 | .B SCHED_OTHER |
33a0ccb2 | 321 | policy, and this can be done only if the effective user ID of the caller of |
e511ffb6 | 322 | .BR sched_setscheduler () |
81bd66da MK |
323 | matches the real or effective user ID of the target thread |
324 | (i.e., the thread specified by | |
afdee10d MK |
325 | .IR pid ) |
326 | whose policy is being changed. | |
327 | ||
fd04afa8 MK |
328 | Since Linux 2.6.12, the |
329 | .B RLIMIT_RTPRIO | |
81bd66da | 330 | resource limit defines a ceiling on an unprivileged thread's |
a3a22b7f | 331 | static priority for the |
fd04afa8 MK |
332 | .B SCHED_RR |
333 | and | |
0daa9e92 | 334 | .B SCHED_FIFO |
fd04afa8 | 335 | policies. |
4e592516 | 336 | The rules for changing scheduling policy and priority are as follows: |
5b775090 | 337 | .IP * 3 |
81bd66da | 338 | If an unprivileged thread has a nonzero |
afdee10d | 339 | .B RLIMIT_RTPRIO |
c13182ef MK |
340 | soft limit, then it can change its scheduling policy and priority, |
341 | subject to the restriction that the priority cannot be set to a | |
4e592516 | 342 | value higher than the maximum of its current priority and its |
afdee10d MK |
343 | .B RLIMIT_RTPRIO |
344 | soft limit. | |
4e592516 | 345 | .IP * |
c13182ef | 346 | If the |
afdee10d | 347 | .B RLIMIT_RTPRIO |
4e592516 MK |
348 | soft limit is 0, then the only permitted changes are to lower the priority, |
349 | or to switch to a non-real-time policy. | |
350 | .IP * | |
c13182ef | 351 | Subject to the same rules, |
81bd66da MK |
352 | another unprivileged thread can also make these changes, |
353 | as long as the effective user ID of the thread making the change | |
354 | matches the real or effective user ID of the target thread. | |
4e592516 MK |
355 | .IP * |
356 | Special rules apply for the | |
7f98857a MK |
357 | .BR SCHED_IDLE . |
358 | In Linux kernels before 2.6.39, | |
81bd66da | 359 | an unprivileged thread operating under this policy cannot |
4e592516 MK |
360 | change its policy, regardless of the value of its |
361 | .BR RLIMIT_RTPRIO | |
362 | resource limit. | |
7f98857a MK |
363 | In Linux kernels since 2.6.39, |
364 | .\" commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8 | |
81bd66da | 365 | an unprivileged thread can switch to either the |
7f98857a MK |
366 | .BR SCHED_BATCH |
367 | or the | |
368 | .BR SCHED_NORMAL | |
369 | policy so long as its nice value falls within the range permitted by its | |
370 | .BR RLIMIT_NICE | |
371 | resource limit (see | |
372 | .BR getrlimit (2)). | |
4e592516 MK |
373 | .PP |
374 | Privileged | |
375 | .RB ( CAP_SYS_NICE ) | |
81bd66da | 376 | threads ignore the |
4e592516 MK |
377 | .B RLIMIT_RTPRIO |
378 | limit; as with older kernels, | |
379 | they can make arbitrary changes to scheduling policy and priority. | |
fd04afa8 MK |
380 | See |
381 | .BR getrlimit (2) | |
382 | for further information on | |
383 | .BR RLIMIT_RTPRIO . | |
fea681da | 384 | .SS Response time |
81bd66da | 385 | A blocked high priority thread waiting for the I/O has a certain |
c13182ef MK |
386 | response time before it is scheduled again. |
387 | The device driver writer | |
fea681da MK |
388 | can greatly reduce this response time by using a "slow interrupt" |
389 | interrupt handler. | |
390 | .\" as described in | |
391 | .\" .BR request_irq (9). | |
fea681da | 392 | .SS Miscellaneous |
a3a22b7f | 393 | Child processes inherit the scheduling policy and parameters across a |
0bfa087b | 394 | .BR fork (2). |
a3a22b7f | 395 | The scheduling policy and parameters are preserved across |
ddb51c37 | 396 | .BR execve (2). |
fea681da | 397 | |
c13182ef | 398 | Memory locking is usually needed for real-time processes to avoid |
a3a22b7f | 399 | paging delays; this can be done with |
0bfa087b | 400 | .BR mlock (2) |
c13182ef | 401 | or |
0bfa087b | 402 | .BR mlockall (2). |
fea681da | 403 | |
81bd66da MK |
404 | Since a nonblocking infinite loop in a thread scheduled under |
405 | \fBSCHED_FIFO\fP or \fBSCHED_RR\fP will block all threads with lower | |
fea681da MK |
406 | priority forever, a software developer should always keep available on |
407 | the console a shell scheduled under a higher static priority than the | |
c13182ef MK |
408 | tested application. |
409 | This will allow an emergency kill of tested | |
afdee10d | 410 | real-time applications that do not block or terminate as expected. |
a3a22b7f MK |
411 | See also the description of the |
412 | .BR RLIMIT_RTTIME | |
413 | resource limit in | |
414 | .BR getrlimit (2). | |
fea681da MK |
415 | |
416 | POSIX systems on which | |
e511ffb6 | 417 | .BR sched_setscheduler () |
fea681da | 418 | and |
e511ffb6 | 419 | .BR sched_getscheduler () |
fea681da | 420 | are available define |
f25eaea8 | 421 | .B _POSIX_PRIORITY_SCHEDULING |
c84371c6 | 422 | in \fI<unistd.h>\fP. |
47297adb | 423 | .SH RETURN VALUE |
fea681da | 424 | On success, |
e511ffb6 | 425 | .BR sched_setscheduler () |
c13182ef | 426 | returns zero. |
fea681da | 427 | On success, |
e511ffb6 | 428 | .BR sched_getscheduler () |
81bd66da | 429 | returns the policy for the thread (a nonnegative integer). |
92c37d8c | 430 | On error, \-1 is returned, and |
fea681da MK |
431 | .I errno |
432 | is set appropriately. | |
433 | .SH ERRORS | |
434 | .TP | |
435 | .B EINVAL | |
436 | The scheduling \fIpolicy\fP is not one of the recognized policies, | |
91e1b56b | 437 | \fIparam\fP is NULL, |
c126cfd6 | 438 | or \fIparam\fP does not make sense for the \fIpolicy\fP. |
fea681da MK |
439 | .TP |
440 | .B EPERM | |
81bd66da | 441 | The calling thread does not have appropriate privileges. |
fea681da MK |
442 | .TP |
443 | .B ESRCH | |
81bd66da | 444 | The thread whose ID is \fIpid\fP could not be found. |
47297adb | 445 | .SH CONFORMING TO |
d61ff56a | 446 | POSIX.1-2001 (but see BUGS below). |
c00194ab | 447 | The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific. |
92c37d8c | 448 | .SH NOTES |
97bc0094 | 449 | POSIX.1 does not detail the permissions that an unprivileged |
81bd66da | 450 | thread requires in order to call |
f902bebc | 451 | .BR sched_setscheduler (), |
97bc0094 MK |
452 | and details vary across systems. |
453 | For example, the Solaris 7 manual page says that | |
81bd66da MK |
454 | the real or effective user ID of the caller must |
455 | match the real user ID or the save set-user-ID of the target. | |
d5999511 MK |
456 | .PP |
457 | The scheduling policy and parameters are in fact per-thread | |
458 | attributes on Linux. | |
459 | The value returned from a call to | |
460 | .BR gettid (2) | |
461 | can be passed in the argument | |
462 | .IR pid . | |
463 | Specifying | |
464 | .I pid | |
465 | as 0 will operate on the attribute for the calling thread, | |
466 | and passing the value returned from a call to | |
467 | .BR getpid (2) | |
468 | will operate on the attribute for the main thread of the thread group. | |
469 | (If you are using the POSIX threads API, then use | |
470 | .BR pthread_setschedparam (3), | |
471 | .BR pthread_getschedparam (3), | |
472 | and | |
473 | .BR pthread_setschedprio (3), | |
474 | instead of the | |
475 | .BR sched_* (2) | |
476 | system calls.) | |
cf9c27a6 MK |
477 | .PP |
478 | Originally, Standard Linux was intended as a general-purpose operating | |
479 | system being able to handle background processes, interactive | |
480 | applications, and less demanding real-time applications (applications that | |
481 | need to usually meet timing deadlines). | |
482 | Although the Linux kernel 2.6 | |
483 | allowed for kernel preemption and the newly introduced O(1) scheduler | |
484 | ensures that the time needed to schedule is fixed and deterministic | |
485 | irrespective of the number of active tasks, true real-time computing | |
486 | was not possible up to kernel version 2.6.17. | |
487 | .SS Real-time features in the mainline Linux kernel | |
c5871a7d | 488 | .\" FIXME . Probably this text will need some minor tweaking |
435ecb8e | 489 | .\" by about the time of 2.6.30; ask Carsten Emde about this then. |
5fab2e7c | 490 | From kernel version 2.6.18 onward, however, Linux is gradually |
cf9c27a6 MK |
491 | becoming equipped with real-time capabilities, |
492 | most of which are derived from the former | |
83ea1eee | 493 | .I realtime-preempt |
435ecb8e MK |
494 | patches developed by Ingo Molnar, Thomas Gleixner, |
495 | Steven Rostedt, and others. | |
bf1c0ede | 496 | Until the patches have been completely merged into the |
cf9c27a6 | 497 | mainline kernel |
9b6ba4d8 | 498 | (this is expected to be around kernel version 2.6.30), |
b77e081d | 499 | they must be installed to achieve the best real-time performance. |
cf9c27a6 | 500 | These patches are named: |
088a639b | 501 | .in +4n |
cf9c27a6 | 502 | .nf |
97bc0094 | 503 | |
cf9c27a6 MK |
504 | patch-\fIkernelversion\fP-rt\fIpatchversion\fP |
505 | .fi | |
506 | .in | |
fea681da | 507 | .PP |
cf9c27a6 | 508 | and can be downloaded from |
608bf950 SK |
509 | .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ |
510 | .UE . | |
cf9c27a6 MK |
511 | |
512 | Without the patches and prior to their full inclusion into the mainline | |
513 | kernel, the kernel configuration offers only the three preemption classes | |
514 | .BR CONFIG_PREEMPT_NONE , | |
515 | .BR CONFIG_PREEMPT_VOLUNTARY , | |
516 | and | |
0daa9e92 | 517 | .B CONFIG_PREEMPT_DESKTOP |
cf9c27a6 MK |
518 | which respectively provide no, some, and considerable |
519 | reduction of the worst-case scheduling latency. | |
520 | ||
521 | With the patches applied or after their full inclusion into the mainline | |
522 | kernel, the additional configuration item | |
0daa9e92 | 523 | .B CONFIG_PREEMPT_RT |
cf9c27a6 MK |
524 | becomes available. |
525 | If this is selected, Linux is transformed into a regular | |
526 | real-time operating system. | |
527 | The FIFO and RR scheduling policies that can be selected using | |
528 | .BR sched_setscheduler () | |
81bd66da | 529 | are then used to run a thread |
cf9c27a6 | 530 | with true real-time priority and a minimum worst-case scheduling latency. |
d61ff56a MK |
531 | .SH BUGS |
532 | POSIX says that on success, | |
533 | .BR sched_setscheduler () | |
534 | should return the previous scheduling policy. | |
535 | Linux | |
536 | .BR sched_setscheduler () | |
537 | does not conform to this requirement, | |
538 | since it always returns 0 on success. | |
47297adb | 539 | .SH SEE ALSO |
ca8a0bd2 MK |
540 | .ad l |
541 | .nh | |
f9c94e46 | 542 | .BR chrt (1), |
fea681da MK |
543 | .BR getpriority (2), |
544 | .BR mlock (2), | |
545 | .BR mlockall (2), | |
546 | .BR munlock (2), | |
547 | .BR munlockall (2), | |
548 | .BR nice (2), | |
549 | .BR sched_get_priority_max (2), | |
550 | .BR sched_get_priority_min (2), | |
551 | .BR sched_getaffinity (2), | |
552 | .BR sched_getparam (2), | |
553 | .BR sched_rr_get_interval (2), | |
554 | .BR sched_setaffinity (2), | |
555 | .BR sched_setparam (2), | |
556 | .BR sched_yield (2), | |
557 | .BR setpriority (2), | |
a18e2edb MK |
558 | .BR capabilities (7), |
559 | .BR cpuset (7) | |
ab13a138 | 560 | .ad |
fea681da MK |
561 | .PP |
562 | .I Programming for the real world \- POSIX.4 | |
173fe7e7 | 563 | by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. |
ea6100ea | 564 | .PP |
6a213bc2 | 565 | The Linux kernel source file |
ea6100ea | 566 | .I Documentation/scheduler/sched-rt-group.txt |