original/man2/sched_setscheduler.2

   1 .\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999
   2 .\" and Copyright (C) 2007 Carsten Emde <Carsten.Emde@osadl.org>
   3 .\" and Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   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
  22 .\" License along with this manual; if not, see
  23 .\" <http://www.gnu.org/licenses/>.
  24 .\" %%%LICENSE_END
  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.
  31 .\" Modified, 25 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  32 .\"     Corrected description of queue placement by sched_setparam() and
  33 .\"             sched_setscheduler()
  34 .\"     A couple of grammar clean-ups
  35 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\" 2005-03-23, mtk, Added description of SCHED_BATCH.
  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.
  40 .\" 2008-05-07, mtk; Rewrote and restructured various parts of the page to
  41 .\"     improve readability.
  42 .\" 2010-06-19, mtk, documented SCHED_RESET_ON_FORK
  43 .\"
  44 .\" Worth looking at: http://rt.wiki.kernel.org/index.php
  45 .\"
  46 .TH SCHED_SETSCHEDULER 2 2013-09-17 "Linux" "Linux Programmer's Manual"
  47 .SH NAME
  48 sched_setscheduler, sched_getscheduler \-
  49 set and get scheduling policy/parameters
  50 .SH SYNOPSIS
  51 .nf
  52 .B #include <sched.h>
  53 .sp
  54 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
  55 .br
  56 .BI "                       const struct sched_param *" param );
  57 .sp
  58 .BI "int sched_getscheduler(pid_t " pid );
  59 .sp
  60 \fBstruct sched_param {
  61     ...
  62     int \fIsched_priority\fB;
  63     ...
  64 };
  65 .fi
  66 .SH DESCRIPTION
  67 .BR sched_setscheduler ()
  68 sets both the scheduling policy and the associated parameters for the
  69 thread whose ID is specified in \fIpid\fP.
  70 If \fIpid\fP equals zero, the
  71 scheduling policy and parameters of the calling thread will be set.
  72 The interpretation of
  73 the argument \fIparam\fP depends on the selected policy.
  74 Currently, Linux supports the following "normal"
  75 (i.e., non-real-time) scheduling policies:
  76 .TP 14
  77 .BR SCHED_OTHER
  78 the standard round-robin time-sharing policy;
  79 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  80 .\" SCHED_NORMAL.
  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
  92 the way in which runnable threads are selected for execution:
  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.
 101
 102 .BR sched_getscheduler ()
 103 queries the scheduling policy currently applied to the thread
 104 identified by \fIpid\fP.
 105 If \fIpid\fP equals zero, the policy of the
 106 calling thread will be retrieved.
 107 .\"
 108 .SS Scheduling policies
 109 The scheduler is the kernel component that decides which runnable thread
 110 will be executed by the CPU next.
 111 Each thread has an associated scheduling policy and a \fIstatic\fP
 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
 116 policy and static priority of all threads on the system.
 117
 118 For threads scheduled under one of the normal scheduling policies
 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).
 122
 123 Processes scheduled under one of the real-time policies
 124 (\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a
 125 \fIsched_priority\fP value in the range 1 (low) to 99 (high).
 126 (As the numbers imply, real-time threads always have higher priority
 127 than normal threads.)
 128 Note well: POSIX.1-2001 requires an implementation to support only a
 129 minimum 32 distinct priority levels for the real-time policies,
 130 and some systems supply just this minimum.
 131 Portable programs should use
 132 .BR sched_get_priority_min (2)
 133 and
 134 .BR sched_get_priority_max (2)
 135 to find the range of priorities supported for a particular policy.
 136
 137 Conceptually, the scheduler maintains a list of runnable
 138 threads for each possible \fIsched_priority\fP value.
 139 In order to determine which thread runs next, the scheduler looks for
 140 the nonempty list with the highest static priority and selects the
 141 thread at the head of this list.
 142
 143 A thread's scheduling policy determines
 144 where it will be inserted into the list of threads
 145 with equal static priority and how it will move inside this list.
 146
 147 All scheduling is preemptive: if a thread with a higher static
 148 priority becomes ready to run, the currently running thread
 149 will be preempted and
 150 returned to the wait list for its static priority level.
 151 The scheduling policy determines the
 152 ordering only within the list of runnable threads with equal static
 153 priority.
 154 .SS SCHED_FIFO: First in-first out scheduling
 155 \fBSCHED_FIFO\fP can be used only with static priorities higher than
 156 0, which means that when a \fBSCHED_FIFO\fP threads becomes runnable,
 157 it will always immediately preempt any currently running
 158 \fBSCHED_OTHER\fP, \fBSCHED_BATCH\fP, or \fBSCHED_IDLE\fP thread.
 159 \fBSCHED_FIFO\fP is a simple scheduling
 160 algorithm without time slicing.
 161 For threads scheduled under the
 162 \fBSCHED_FIFO\fP policy, the following rules apply:
 163 .IP * 3
 164 A \fBSCHED_FIFO\fP thread that has been preempted by another thread of
 165 higher priority will stay at the head of the list for its priority and
 166 will resume execution as soon as all threads of higher priority are
 167 blocked again.
 168 .IP *
 169 When a \fBSCHED_FIFO\fP thread becomes runnable, it
 170 will be inserted at the end of the list for its priority.
 171 .IP *
 172 A call to
 173 .BR sched_setscheduler ()
 174 or
 175 .BR sched_setparam (2)
 176 will put the
 177 \fBSCHED_FIFO\fP (or \fBSCHED_RR\fP) thread identified by
 178 \fIpid\fP at the start of the list if it was runnable.
 179 As a consequence, it may preempt the currently running thread if
 180 it has the same priority.
 181 (POSIX.1-2001 specifies that the thread should go to the end
 182 of the list.)
 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
 185 .IP *
 186 A thread calling
 187 .BR sched_yield (2)
 188 will be put at the end of the list.
 189 .PP
 190 No other events will move a thread
 191 scheduled under the \fBSCHED_FIFO\fP policy in the wait list of
 192 runnable threads with equal static priority.
 193
 194 A \fBSCHED_FIFO\fP
 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
 197 .BR sched_yield (2).
 198 .SS SCHED_RR: Round-robin scheduling
 199 \fBSCHED_RR\fP is a simple enhancement of \fBSCHED_FIFO\fP.
 200 Everything
 201 described above for \fBSCHED_FIFO\fP also applies to \fBSCHED_RR\fP,
 202 except that each thread is allowed to run only for a maximum time
 203 quantum.
 204 If a \fBSCHED_RR\fP thread has been running for a time
 205 period equal to or longer than the time quantum, it will be put at the
 206 end of the list for its priority.
 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
 210 its round-robin time quantum.
 211 The length of the time quantum can be
 212 retrieved using
 213 .BR sched_rr_get_interval (2).
 214 .\" On Linux 2.4, the length of the RR interval is influenced
 215 .\" by the process nice value -- MTK
 216 .\"
 217 .SS SCHED_OTHER: Default Linux time-sharing scheduling
 218 \fBSCHED_OTHER\fP can be used at only static priority 0.
 219 \fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is
 220 intended for all threads that do not require the special
 221 real-time mechanisms.
 222 The thread to run is chosen from the static
 223 priority 0 list based on a \fIdynamic\fP priority that is determined only
 224 inside this list.
 225 The dynamic priority is based on the nice value (set by
 226 .BR nice (2)
 227 or
 228 .BR setpriority (2))
 229 and increased for each time quantum the thread is ready to run,
 230 but denied to run by the scheduler.
 231 This ensures fair progress among all \fBSCHED_OTHER\fP threads.
 232 .\"
 233 .SS SCHED_BATCH: Scheduling batch processes
 234 (Since Linux 2.6.16.)
 235 \fBSCHED_BATCH\fP can be used only at static priority 0.
 236 This policy is similar to \fBSCHED_OTHER\fP in that it schedules
 237 the thread according to its dynamic priority
 238 (based on the nice value).
 239 The difference is that this policy
 240 will cause the scheduler to always assume
 241 that the thread is CPU-intensive.
 242 Consequently, the scheduler will apply a small scheduling
 243 penalty with respect to wakeup behaviour,
 244 so that this thread is mildly disfavored in scheduling decisions.
 245
 246 .\" The following paragraph is drawn largely from the text that
 247 .\" accompanied Ingo Molnar's patch for the implementation of
 248 .\" SCHED_BATCH.
 249 .\" commit b0a9499c3dd50d333e2aedb7e894873c58da3785
 250 This policy is useful for workloads that are noninteractive,
 251 but do not want to lower their nice value,
 252 and for workloads that want a deterministic scheduling policy without
 253 interactivity causing extra preemptions (between the workload's tasks).
 254 .\"
 255 .SS SCHED_IDLE: Scheduling very low priority jobs
 256 (Since Linux 2.6.23.)
 257 \fBSCHED_IDLE\fP can be used only at static priority 0;
 258 the process nice value has no influence for this policy.
 259
 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 .\"
 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
 289 If the calling thread has a scheduling policy of
 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 *
 297 If the calling process has a negative nice value,
 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,
 303 it can be reset only if the thread has the
 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 .\"
 314 .SS Privileges and resource limits
 315 In Linux kernels before 2.6.12, only privileged
 316 .RB ( CAP_SYS_NICE )
 317 threads can set a nonzero static priority (i.e., set a real-time
 318 scheduling policy).
 319 The only change that an unprivileged thread can make is to set the
 320 .B SCHED_OTHER
 321 policy, and this can be done only if the effective user ID of the caller of
 322 .BR sched_setscheduler ()
 323 matches the real or effective user ID of the target thread
 324 (i.e., the thread specified by
 325 .IR pid )
 326 whose policy is being changed.
 327
 328 Since Linux 2.6.12, the
 329 .B RLIMIT_RTPRIO
 330 resource limit defines a ceiling on an unprivileged thread's
 331 static priority for the
 332 .B SCHED_RR
 333 and
 334 .B SCHED_FIFO
 335 policies.
 336 The rules for changing scheduling policy and priority are as follows:
 337 .IP * 3
 338 If an unprivileged thread has a nonzero
 339 .B RLIMIT_RTPRIO
 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
 342 value higher than the maximum of its current priority and its
 343 .B RLIMIT_RTPRIO
 344 soft limit.
 345 .IP *
 346 If the
 347 .B RLIMIT_RTPRIO
 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 *
 351 Subject to the same rules,
 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.
 355 .IP *
 356 Special rules apply for the
 357 .BR SCHED_IDLE .
 358 In Linux kernels before 2.6.39,
 359 an unprivileged thread operating under this policy cannot
 360 change its policy, regardless of the value of its
 361 .BR RLIMIT_RTPRIO
 362 resource limit.
 363 In Linux kernels since 2.6.39,
 364 .\" commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8
 365 an unprivileged thread can switch to either the
 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)).
 373 .PP
 374 Privileged
 375 .RB ( CAP_SYS_NICE )
 376 threads ignore the
 377 .B RLIMIT_RTPRIO
 378 limit; as with older kernels,
 379 they can make arbitrary changes to scheduling policy and priority.
 380 See
 381 .BR getrlimit (2)
 382 for further information on
 383 .BR RLIMIT_RTPRIO .
 384 .SS Response time
 385 A blocked high priority thread waiting for the I/O has a certain
 386 response time before it is scheduled again.
 387 The device driver writer
 388 can greatly reduce this response time by using a "slow interrupt"
 389 interrupt handler.
 390 .\" as described in
 391 .\" .BR request_irq (9).
 392 .SS Miscellaneous
 393 Child processes inherit the scheduling policy and parameters across a
 394 .BR fork (2).
 395 The scheduling policy and parameters are preserved across
 396 .BR execve (2).
 397
 398 Memory locking is usually needed for real-time processes to avoid
 399 paging delays; this can be done with
 400 .BR mlock (2)
 401 or
 402 .BR mlockall (2).
 403
 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
 406 priority forever, a software developer should always keep available on
 407 the console a shell scheduled under a higher static priority than the
 408 tested application.
 409 This will allow an emergency kill of tested
 410 real-time applications that do not block or terminate as expected.
 411 See also the description of the
 412 .BR RLIMIT_RTTIME
 413 resource limit in
 414 .BR getrlimit (2).
 415
 416 POSIX systems on which
 417 .BR sched_setscheduler ()
 418 and
 419 .BR sched_getscheduler ()
 420 are available define
 421 .B _POSIX_PRIORITY_SCHEDULING
 422 in \fI<unistd.h>\fP.
 423 .SH RETURN VALUE
 424 On success,
 425 .BR sched_setscheduler ()
 426 returns zero.
 427 On success,
 428 .BR sched_getscheduler ()
 429 returns the policy for the thread (a nonnegative integer).
 430 On error, \-1 is returned, and
 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,
 437 \fIparam\fP is NULL,
 438 or \fIparam\fP does not make sense for the \fIpolicy\fP.
 439 .TP
 440 .B EPERM
 441 The calling thread does not have appropriate privileges.
 442 .TP
 443 .B ESRCH
 444 The thread whose ID is \fIpid\fP could not be found.
 445 .SH CONFORMING TO
 446 POSIX.1-2001 (but see BUGS below).
 447 The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific.
 448 .SH NOTES
 449 POSIX.1 does not detail the permissions that an unprivileged
 450 thread requires in order to call
 451 .BR sched_setscheduler (),
 452 and details vary across systems.
 453 For example, the Solaris 7 manual page says that
 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.
 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.)
 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
 488 .\" FIXME . Probably this text will need some minor tweaking
 489 .\" by about the time of 2.6.30; ask Carsten Emde about this then.
 490 From kernel version 2.6.18 onward, however, Linux is gradually
 491 becoming equipped with real-time capabilities,
 492 most of which are derived from the former
 493 .I realtime-preempt
 494 patches developed by Ingo Molnar, Thomas Gleixner,
 495 Steven Rostedt, and others.
 496 Until the patches have been completely merged into the
 497 mainline kernel
 498 (this is expected to be around kernel version 2.6.30),
 499 they must be installed to achieve the best real-time performance.
 500 These patches are named:
 501 .in +4n
 502 .nf
 503
 504 patch-\fIkernelversion\fP-rt\fIpatchversion\fP
 505 .fi
 506 .in
 507 .PP
 508 and can be downloaded from
 509 .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/
 510 .UE .
 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
 517 .B CONFIG_PREEMPT_DESKTOP
 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
 523 .B CONFIG_PREEMPT_RT
 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 ()
 529 are then used to run a thread
 530 with true real-time priority and a minimum worst-case scheduling latency.
 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.
 539 .SH SEE ALSO
 540 .ad l
 541 .nh
 542 .BR chrt (1),
 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),
 558 .BR capabilities (7),
 559 .BR cpuset (7)
 560 .ad
 561 .PP
 562 .I Programming for the real world \- POSIX.4
 563 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0.
 564 .PP
 565 The Linux kernel source file
 566 .I Documentation/scheduler/sched-rt-group.txt
 567 .SH COLOPHON
 568 This page is part of release 3.65 of the Linux
 569 .I man-pages
 570 project.
 571 A description of the project,
 572 and information about reporting bugs,
 573 can be found at
 574 \%http://www.kernel.org/doc/man\-pages/.