man2/sched_setscheduler.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999
   4 .\"
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, write to the Free
  22 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  23 .\" USA.
  24 .\"
  25 .\" 1996-04-01 Tom Bjorkholm <tomb@mydata.se>
  26 .\"            First version written
  27 .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
  28 .\"            revision
  29 .\" 1999-08-18 David A. Wheeler <dwheeler@ida.org> added Note.
  30 .\" Modified, 25 Jun 2002, Michael Kerrisk <mtk-manpages@gmx.net>
  31 .\"     Corrected description of queue placement by sched_setparam() and
  32 .\"             sched_setscheduler()
  33 .\"     A couple of grammar clean-ups
  34 .\" Modified 2004-05-27 by Michael Kerrisk <mtk-manpages@gmx.net>
  35 .\" 2005-03-23, mtk, Added description of SCHED_BATCH.
  36 .\"
  37 .TH SETSCHEDULER 2 2006-03-23 "Linux 2.6.16" "Linux Programmer's Manual"
  38 .SH NAME
  39 sched_setscheduler, sched_getscheduler \-
  40 set and get scheduling algorithm/parameters
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <sched.h>
  44 .sp
  45 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
  46 .br
  47 .BI "                       const struct sched_param *" param );
  48 .sp
  49 .BI "int sched_getscheduler(pid_t " pid );
  50 .sp
  51 \fBstruct sched_param {
  52     ...
  53     int \fIsched_priority\fB;
  54     ...
  55 };
  56 .fi
  57 .SH DESCRIPTION
  58 .BR sched_setscheduler ()
  59 sets both the scheduling policy and the associated parameters for the
  60 process identified by \fIpid\fP.
  61 If \fIpid\fP equals zero, the
  62 scheduler of the calling process will be set.
  63 The interpretation of
  64 the parameter \fIparam\fP depends on the selected policy.
  65 Currently, the
  66 following three scheduling policies are supported under Linux:
  67 .IR SCHED_FIFO ,
  68 .IR SCHED_RR ,
  69 .IR SCHED_OTHER ,
  70 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  71 .\" SCHED_NORMAL.
  72 and
  73 .IR SCHED_BATCH ;
  74 their respective semantics are described below.
  75
  76 .BR sched_getscheduler ()
  77 queries the scheduling policy currently applied to the process
  78 identified by \fIpid\fP.
  79 If \fIpid\fP equals zero, the policy of the
  80 calling process will be retrieved.
  81 .SS Scheduling Policies
  82 The scheduler is the kernel part that decides which runnable process
  83 will be executed by the CPU next.
  84 The Linux scheduler offers three
  85 different scheduling policies, one for normal processes and two for
  86 real-time applications.
  87 A static priority value \fIsched_priority\fP
  88 is assigned to each process and this value can be changed only via
  89 system calls.
  90 Conceptually, the scheduler maintains a list of runnable
  91 processes for each possible \fIsched_priority\fP value, and
  92 \fIsched_priority\fP can have a value in the range 0 to 99.
  93 In order
  94 to determine the process that runs next, the Linux scheduler looks for
  95 the non-empty list with the highest static priority and takes the
  96 process at the head of this list.
  97 The scheduling policy determines for
  98 each process, where it will be inserted into the list of processes
  99 with equal static priority and how it will move inside this list.
 100
 101 \fISCHED_OTHER\fP is the default universal time-sharing scheduler
 102 policy used by most processes.
 103 \fISCHED_BATCH\fP is intended for "batch" style execution of processes.
 104 \fISCHED_FIFO\fP and \fISCHED_RR\fP are
 105 intended for special time-critical applications that need precise
 106 control over the way in which runnable processes are selected for
 107 execution.
 108
 109 Processes scheduled with \fISCHED_OTHER\fP or \fISCHED_BATCH\fP
 110 must be assigned the static priority 0.
 111 Processes scheduled under \fISCHED_FIFO\fP or
 112 \fISCHED_RR\fP can have a static priority in the range 1 to 99.
 113 The system calls \fBsched_get_priority_min\fP() and
 114 \fBsched_get_priority_max\fP() can be used to find out the valid
 115 priority range for a scheduling policy in a portable way on all
 116 POSIX.1-2001 conforming systems.
 117
 118 All scheduling is preemptive: If a process with a higher static
 119 priority gets ready to run, the current process will be preempted and
 120 returned into its wait list.
 121 The scheduling policy only determines the
 122 ordering within the list of runnable processes with equal static
 123 priority.
 124 .SS SCHED_FIFO: First In-First Out scheduling
 125 \fISCHED_FIFO\fP can only be used with static priorities higher than
 126 0, which means that when a \fISCHED_FIFO\fP processes becomes runnable,
 127 it will always immediately preempt any currently running
 128 \fISCHED_OTHER\fP or \fISCHED_BATCH\fP process.
 129 \fISCHED_FIFO\fP is a simple scheduling
 130 algorithm without time slicing.
 131 For processes scheduled under the
 132 \fISCHED_FIFO\fP policy, the following rules are applied: A
 133 \fISCHED_FIFO\fP process that has been preempted by another process of
 134 higher priority will stay at the head of the list for its priority and
 135 will resume execution as soon as all processes of higher priority are
 136 blocked again.
 137 When a \fISCHED_FIFO\fP process becomes runnable, it
 138 will be inserted at the end of the list for its priority.
 139 A call to
 140 \fBsched_setscheduler\fP() or \fBsched_setparam\fP() will put the
 141 \fISCHED_FIFO\fP (or \fISCHED_RR\fP) process identified by
 142 \fIpid\fP at the start of the list if it was runnable.
 143 As a consequence, it may preempt the currently running process if
 144 it has the same priority.
 145 (POSIX.1-2001 specifies that the process should go to the end
 146 of the list.)
 147 .\" In 2.2.x and 2.4.x, the process is placed at the front of the queue
 148 .\" In 2.0.x, the Right Thing happened: the process went to the back -- MTK
 149 A process calling \fBsched_yield\fP() will be
 150 put at the end of the list.
 151 No other events will move a process
 152 scheduled under the \fISCHED_FIFO\fP policy in the wait list of
 153 runnable processes with equal static priority.
 154 A \fISCHED_FIFO\fP
 155 process runs until either it is blocked by an I/O request, it is
 156 preempted by a higher priority process, or it calls \fBsched_yield\fP().
 157 .SS SCHED_RR: Round Robin scheduling
 158 \fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP.
 159 Everything
 160 described above for \fISCHED_FIFO\fP also applies to \fISCHED_RR\fP,
 161 except that each process is only allowed to run for a maximum time
 162 quantum.
 163 If a \fISCHED_RR\fP process has been running for a time
 164 period equal to or longer than the time quantum, it will be put at the
 165 end of the list for its priority.
 166 A \fISCHED_RR\fP process that has
 167 been preempted by a higher priority process and subsequently resumes
 168 execution as a running process will complete the unexpired portion of
 169 its round robin time quantum.
 170 The length of the time quantum can be
 171 retrieved using \fBsched_rr_get_interval\fP(2).
 172 .\" On Linux 2.4, the length of the RR interval is influenced
 173 .\" by the process nice value -- MTK
 174 .\"
 175 .SS SCHED_OTHER: Default Linux time-sharing scheduling
 176 \fISCHED_OTHER\fP can only be used at static priority 0.
 177 \fISCHED_OTHER\fP is the standard Linux time-sharing scheduler that is
 178 intended for all processes that do not require special static priority
 179 real-time mechanisms.
 180 The process to run is chosen from the static
 181 priority 0 list based on a dynamic priority that is determined only
 182 inside this list.
 183 The dynamic priority is based on the nice level (set
 184 by \fBnice\fP(2) or \fBsetpriority\fP(2)) and increased for
 185 each time quantum the process is ready to run, but denied to run by
 186 the scheduler.
 187 This ensures fair progress among all \fISCHED_OTHER\fP
 188 processes.
 189 .SS SCHED_BATCH: Scheduling batch processes
 190 (Since Linux 2.6.16.)
 191 \fISCHED_BATCH\fP can only be used at static priority 0.
 192 This policy is similar to \fISCHED_OTHER\fP, except that
 193 this policy will cause the scheduler to always assume
 194 that the process is CPU-intensive.
 195 Consequently, the scheduler will apply a small scheduling
 196 penalty so that this process is mildly disfavoured in scheduling
 197 decisions.
 198 .\" The following paragraph is drawn largely from the text that
 199 .\" accompanied Ingo Molnar's patch for the implementation of
 200 .\" SCHED_BATCH.
 201 This policy is useful for workloads that are non-interactive,
 202 but do not want to lower their nice value,
 203 and for workloads that want a deterministic scheduling policy without
 204 interactivity causing extra preemptions (between the workload's tasks).
 205 .SS Privileges and resource limits
 206 .\" FIXME make some general statement about Unix implementations
 207 .\" A process calling
 208 .\" .BR sched_setscheduler
 209 .\" needs an effective user ID equal to the real user ID or effective
 210 .\" user ID of the process identified by
 211 .\" .IR pid ,
 212 .\" or it must be privileged (Linux: have the
 213 .\" .B CAP_SYS_NICE
 214 .\" capability).
 215 .\"
 216 In Linux kernels before 2.6.12, only privileged
 217 .RB ( CAP_SYS_NICE )
 218 processes can set a non-zero static priority.
 219 The only change that an unprivileged process can make is to set the
 220 .B SCHED_OTHER
 221 policy, and this can only be done if the effective user ID of the caller of
 222 .BR sched_setscheduler ()
 223 matches the real or effective user ID of the target process
 224 (i.e., the process specified by
 225 .IR pid )
 226 whose policy is being changed.
 227
 228 Since Linux 2.6.12, the
 229 .B RLIMIT_RTPRIO
 230 resource limit defines a ceiling on an unprivileged process's
 231 priority for the
 232 .B SCHED_RR
 233 and
 234 .BR SCHED_FIFO
 235 policies.
 236 If an unprivileged process has a non-zero
 237 .B RLIMIT_RTPRIO
 238 soft limit, then it can change its scheduling policy and priority,
 239 subject to the restriction that the priority cannot be set to a
 240 value higher than the
 241 .B RLIMIT_RTPRIO
 242 soft limit.
 243 If the
 244 .B RLIMIT_RTPRIO
 245 soft limit is 0, then the only permitted change is to lower the priority.
 246 Subject to the same rules,
 247 another unprivileged process can also make these changes,
 248 as long as the effective user ID of the process making the change
 249 matches the real or effective user ID of the target process.
 250 See
 251 .BR getrlimit (2)
 252 for further information on
 253 .BR RLIMIT_RTPRIO .
 254 Privileged
 255 .RB ( CAP_SYS_NICE )
 256 processes ignore this limit; as with older kernels,
 257 they can make arbitrary changes to scheduling policy and priority.
 258 .SS Response time
 259 A blocked high priority process waiting for the I/O has a certain
 260 response time before it is scheduled again.
 261 The device driver writer
 262 can greatly reduce this response time by using a "slow interrupt"
 263 interrupt handler.
 264 .\" as described in
 265 .\" .BR request_irq (9).
 266 .SS Miscellaneous
 267 Child processes inherit the scheduling algorithm and parameters across a
 268 .BR fork ().
 269 The scheduling algorithm and parameters are preserved across
 270 .BR execve (2).
 271
 272 Memory locking is usually needed for real-time processes to avoid
 273 paging delays, this can be done with
 274 .BR mlock ()
 275 or
 276 .BR mlockall ().
 277
 278 As a non-blocking end-less loop in a process scheduled under
 279 \fISCHED_FIFO\fP or \fISCHED_RR\fP will block all processes with lower
 280 priority forever, a software developer should always keep available on
 281 the console a shell scheduled under a higher static priority than the
 282 tested application.
 283 This will allow an emergency kill of tested
 284 real-time applications that do not block or terminate as expected.
 285
 286 POSIX systems on which
 287 .BR sched_setscheduler ()
 288 and
 289 .BR sched_getscheduler ()
 290 are available define
 291 .I _POSIX_PRIORITY_SCHEDULING
 292 in <unistd.h>.
 293 .SH "RETURN VALUE"
 294 On success,
 295 .BR sched_setscheduler ()
 296 returns zero.
 297 On success,
 298 .BR sched_getscheduler ()
 299 returns the policy for the process (a non-negative integer).
 300 On error, \-1 is returned, and
 301 .I errno
 302 is set appropriately.
 303 .SH ERRORS
 304 .TP
 305 .B EINVAL
 306 The scheduling \fIpolicy\fP is not one of the recognized policies,
 307 or the parameter \fIparam\fP does not make sense for the \fIpolicy\fP.
 308 .TP
 309 .B EPERM
 310 The calling process does not have appropriate privileges.
 311 .TP
 312 .B ESRCH
 313 The process whose ID is \fIpid\fP could not be found.
 314 .SH "CONFORMING TO"
 315 POSIX.1-2001.
 316 The \fISCHED_BATCH\fP policy is Linux specific.
 317 .SH NOTES
 318 Standard Linux is a general-purpose operating system
 319 and can handle background processes,
 320 interactive applications, and soft real-time applications
 321 (applications that need to usually meet timing deadlines).
 322 This man page is directed at these kinds of applications.
 323 .PP
 324 Standard Linux is
 325 .I not
 326 designed to support
 327 hard real-time applications, that is, applications in which deadlines
 328 (often much shorter than a second) must be guaranteed or the system
 329 will fail catastrophically.
 330 Like all general-purpose operating systems, Linux
 331 is designed to maximize average case performance
 332 instead of worst case performance.
 333 Linux's worst case performance for
 334 interrupt handling is much poorer than its average case, its various
 335 kernel locks (such as for SMP) produce long maximum wait times, and
 336 many of its performance improvement techniques decrease average time by
 337 increasing worst-case time.
 338 For most situations, that's what you want, but
 339 if you truly are developing a hard real-time application,
 340 consider using hard real-time extensions to Linux such as
 341 RTLinux (http://www.rtlinux.org) or RTAI (http://www.rtai.org)
 342 or use a different operating system
 343 designed specifically for hard real-time applications.
 344 .SH "SEE ALSO"
 345 .BR getpriority (2),
 346 .BR mlock (2),
 347 .BR mlockall (2),
 348 .BR munlock (2),
 349 .BR munlockall (2),
 350 .BR nice (2),
 351 .BR sched_get_priority_max (2),
 352 .BR sched_get_priority_min (2),
 353 .BR sched_getaffinity (2),
 354 .BR sched_getparam (2),
 355 .BR sched_rr_get_interval (2),
 356 .BR sched_setaffinity (2),
 357 .BR sched_setparam (2),
 358 .BR sched_yield (2),
 359 .BR setpriority (2),
 360 .BR capabilities (7)
 361 .PP
 362 .I Programming for the real world \- POSIX.4
 363 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0