1SCHED_SETSCHEDULER(2)      Linux Programmer's Manual     SCHED_SETSCHEDULER(2)
2
3
4

NAME

6       sched_setscheduler,  sched_getscheduler  -  set and get scheduling pol‐
7       icy/parameters
8

SYNOPSIS

10       #include <sched.h>
11
12       int sched_setscheduler(pid_t pid, int policy,
13                              const struct sched_param *param);
14
15       int sched_getscheduler(pid_t pid);
16
17       struct sched_param {
18           ...
19           int sched_priority;
20           ...
21       };
22

DESCRIPTION

24       sched_setscheduler() sets both the scheduling policy and the associated
25       parameters for the process whose ID is specified in pid.  If pid equals
26       zero, the scheduling policy and parameters of the calling process  will
27       be  set.   The  interpretation  of  the  argument  param depends on the
28       selected policy.  Currently,  Linux  supports  the  following  "normal"
29       (i.e., non-real-time) scheduling policies:
30
31       SCHED_OTHER   the standard round-robin time-sharing policy;
32
33       SCHED_BATCH   for "batch" style execution of processes; and
34
35       SCHED_IDLE    for running very low priority background jobs.
36
37       The  following  "real-time"  policies  are  also supported, for special
38       time-critical applications that need precise control over  the  way  in
39       which runnable processes are selected for execution:
40
41       SCHED_FIFO    a first-in, first-out policy; and
42
43       SCHED_RR      a round-robin policy.
44
45       The semantics of each of these policies are detailed below.
46
47       sched_getscheduler() queries the scheduling policy currently applied to
48       the process identified by pid.  If pid equals zero, the policy  of  the
49       calling process will be retrieved.
50
51   Scheduling Policies
52       The  scheduler  is  the  kernel  component  that decides which runnable
53       process will be executed by the CPU next.  Each process has an  associ‐
54       ated  scheduling  policy and a static scheduling priority, sched_prior‐
55       ity; these are the settings that are modified by  sched_setscheduler().
56       The  scheduler  makes it decisions based on knowledge of the scheduling
57       policy and static priority of all processes on the system.
58
59       For processes scheduled under one of  the  normal  scheduling  policies
60       (SCHED_OTHER,  SCHED_IDLE,  SCHED_BATCH), sched_priority is not used in
61       scheduling decisions (it must be specified as 0).
62
63       Processes scheduled under one of the  real-time  policies  (SCHED_FIFO,
64       SCHED_RR)  have  a  sched_priority  value  in  the  range 1 (low) to 99
65       (high).  (As the numbers imply, real-time processes always have  higher
66       priority than normal processes.)  Note well: POSIX.1-2001 only requires
67       an implementation to support a minimum 32 distinct priority levels  for
68       the  real-time  policies,  and  some  systems supply just this minimum.
69       Portable   programs   should    use    sched_get_priority_min(2)    and
70       sched_get_priority_max(2) to find the range of priorities supported for
71       a particular policy.
72
73       Conceptually, the scheduler maintains a list of runnable processes  for
74       each  possible  sched_priority  value.   In  order  to  determine which
75       process runs next, the scheduler looks for the non-empty list with  the
76       highest  static  priority  and  selects the process at the head of this
77       list.
78
79       A process's scheduling policy determines where it will be inserted into
80       the  list  of processes with equal static priority and how it will move
81       inside this list.
82
83       All scheduling is preemptive: if a process with a higher static  prior‐
84       ity  becomes  ready  to run, the currently running process will be pre‐
85       empted and returned to the wait list for  its  static  priority  level.
86       The  scheduling  policy only determines the ordering within the list of
87       runnable processes with equal static priority.
88
89   SCHED_FIFO: First In-First Out scheduling
90       SCHED_FIFO can only be used with static priorities higher than 0, which
91       means that when a SCHED_FIFO processes becomes runnable, it will always
92       immediately preempt any currently running SCHED_OTHER, SCHED_BATCH,  or
93       SCHED_IDLE  process.  SCHED_FIFO is a simple scheduling algorithm with‐
94       out time slicing.  For processes scheduled under the SCHED_FIFO policy,
95       the following rules apply:
96
97       *  A  SCHED_FIFO  process that has been preempted by another process of
98          higher priority will stay at the head of the list for  its  priority
99          and  will resume execution as soon as all processes of higher prior‐
100          ity are blocked again.
101
102       *  When a SCHED_FIFO process becomes runnable, it will be  inserted  at
103          the end of the list for its priority.
104
105       *  A  call  to  sched_setscheduler()  or sched_setparam(2) will put the
106          SCHED_FIFO (or SCHED_RR) process identified by pid at the  start  of
107          the  list  if it was runnable.  As a consequence, it may preempt the
108          currently  running  process   if   it   has   the   same   priority.
109          (POSIX.1-2001 specifies that the process should go to the end of the
110          list.)
111
112       *  A process calling sched_yield(2) will be put at the end of the list.
113
114       No other events will move a process scheduled under the SCHED_FIFO pol‐
115       icy in the wait list of runnable processes with equal static priority.
116
117       A SCHED_FIFO process runs until either it is blocked by an I/O request,
118       it  is  preempted  by  a  higher  priority   process,   or   it   calls
119       sched_yield(2).
120
121   SCHED_RR: Round Robin scheduling
122       SCHED_RR  is  a simple enhancement of SCHED_FIFO.  Everything described
123       above for SCHED_FIFO also applies to SCHED_RR, except that each process
124       is  only  allowed  to  run  for  a maximum time quantum.  If a SCHED_RR
125       process has been running for a time period equal to or longer than  the
126       time  quantum,  it will be put at the end of the list for its priority.
127       A SCHED_RR process that has been preempted by a higher priority process
128       and  subsequently  resumes execution as a running process will complete
129       the unexpired portion of its round robin time quantum.  The  length  of
130       the time quantum can be retrieved using sched_rr_get_interval(2).
131
132   SCHED_OTHER: Default Linux time-sharing scheduling
133       SCHED_OTHER  can only be used at static priority 0.  SCHED_OTHER is the
134       standard Linux time-sharing scheduler that is  intended  for  all  pro‐
135       cesses  that  do  not  require  the  special real-time mechanisms.  The
136       process to run is chosen from the static priority 0  list  based  on  a
137       dynamic priority that is determined only inside this list.  The dynamic
138       priority is based on the nice value (set by nice(2) or  setpriority(2))
139       and  increased  for  each time quantum the process is ready to run, but
140       denied to run by the scheduler.  This ensures fair progress  among  all
141       SCHED_OTHER processes.
142
143   SCHED_BATCH: Scheduling batch processes
144       (Since  Linux 2.6.16.)  SCHED_BATCH can only be used at static priority
145       0.  This policy is similar to SCHED_OTHER  in  that  it  schedules  the
146       process  according  to  its dynamic priority (based on the nice value).
147       The difference is that this policy will cause the scheduler  to  always
148       assume  that the process is CPU-intensive.  Consequently, the scheduler
149       will apply a small scheduling penalty with respect to wakeup behaviour,
150       so that this process is mildly disfavored in scheduling decisions.
151
152       This  policy  is  useful for workloads that are non-interactive, but do
153       not want to lower their nice value,  and  for  workloads  that  want  a
154       deterministic  scheduling  policy  without  interactivity causing extra
155       preemptions (between the workload's tasks).
156
157   SCHED_IDLE: Scheduling very low priority jobs
158       (Since Linux 2.6.23.)  SCHED_IDLE can only be used at  static  priority
159       0; the process nice value has no influence for this policy.
160
161       This  policy  is  intended  for  running jobs at extremely low priority
162       (lower even than a +19 nice value with the SCHED_OTHER  or  SCHED_BATCH
163       policies).
164
165   Privileges and resource limits
166       In  Linux  kernels  before  2.6.12, only privileged (CAP_SYS_NICE) pro‐
167       cesses can set a non-zero static priority (i.e., set a real-time sched‐
168       uling  policy).   The only change that an unprivileged process can make
169       is to set the SCHED_OTHER policy, and this can  only  be  done  if  the
170       effective  user  ID  of  the caller of sched_setscheduler() matches the
171       real or effective user ID of the  target  process  (i.e.,  the  process
172       specified by pid) whose policy is being changed.
173
174       Since  Linux 2.6.12, the RLIMIT_RTPRIO resource limit defines a ceiling
175       on an unprivileged process's  static  priority  for  the  SCHED_RR  and
176       SCHED_FIFO policies.  The rules for changing scheduling policy and pri‐
177       ority are as follows:
178
179       * If an unprivileged process has a non-zero RLIMIT_RTPRIO  soft  limit,
180         then it can change its scheduling policy and priority, subject to the
181         restriction that the priority cannot be set to a  value  higher  than
182         the maximum of its current priority and its RLIMIT_RTPRIO soft limit.
183
184       * If the RLIMIT_RTPRIO soft limit is 0, then the only permitted changes
185         are to lower the priority, or to switch to a non-real-time policy.
186
187       * Subject to the same rules, another unprivileged process can also make
188         these changes, as long as the effective user ID of the process making
189         the change matches the real  or  effective  user  ID  of  the  target
190         process.
191
192       * Special rules apply for the SCHED_IDLE: an unprivileged process oper‐
193         ating under this policy cannot change its policy, regardless  of  the
194         value of its RLIMIT_RTPRIO resource limit.
195
196       Privileged  (CAP_SYS_NICE) processes ignore the RLIMIT_RTPRIO limit; as
197       with older kernels, they can make arbitrary changes to scheduling  pol‐
198       icy   and  priority.   See  getrlimit(2)  for  further  information  on
199       RLIMIT_RTPRIO.
200
201   Response time
202       A blocked high priority process waiting  for  the  I/O  has  a  certain
203       response  time  before it is scheduled again.  The device driver writer
204       can greatly reduce this response  time  by  using  a  "slow  interrupt"
205       interrupt handler.
206
207   Miscellaneous
208       Child  processes  inherit the scheduling policy and parameters across a
209       fork(2).  The scheduling policy and  parameters  are  preserved  across
210       execve(2).
211
212       Memory  locking is usually needed for real-time processes to avoid pag‐
213       ing delays; this can be done with mlock(2) or mlockall(2).
214
215       Since a  non-blocking  infinite  loop  in  a  process  scheduled  under
216       SCHED_FIFO  or  SCHED_RR  will  block all processes with lower priority
217       forever, a software developer should always keep available on the  con‐
218       sole  a  shell scheduled under a higher static priority than the tested
219       application.  This will allow an emergency  kill  of  tested  real-time
220       applications  that do not block or terminate as expected.  See also the
221       description of the RLIMIT_RTTIME resource limit in getrlimit(2).
222
223       POSIX systems on which  sched_setscheduler()  and  sched_getscheduler()
224       are available define _POSIX_PRIORITY_SCHEDULING in <unistd.h>.
225

RETURN VALUE

227       On   success,   sched_setscheduler()   returns   zero.    On   success,
228       sched_getscheduler() returns the policy for the process (a non-negative
229       integer).  On error, -1 is returned, and errno is set appropriately.
230

ERRORS

232       EINVAL The  scheduling policy is not one of the recognized policies, or
233              param does not make sense for the policy.
234
235       EPERM  The calling process does not have appropriate privileges.
236
237       ESRCH  The process whose ID is pid could not be found.
238

CONFORMING TO

240       POSIX.1-2001 (but see BUGS  below).   The  SCHED_BATCH  and  SCHED_IDLE
241       policies are Linux-specific.
242

NOTES

244       POSIX.1  does  not  detail the permissions that an unprivileged process
245       requires in order to call sched_setscheduler(), and details vary across
246       systems.   For example, the Solaris 7 manual page says that the real or
247       effective user ID of the calling process must match the real user ID or
248       the save set-user-ID of the target process.
249
250       Originally,  Standard Linux was intended as a general-purpose operating
251       system being able to handle background processes, interactive  applica‐
252       tions,  and  less  demanding  real-time applications (applications that
253       need to usually meet timing deadlines).  Although the Linux kernel  2.6
254       allowed  for  kernel preemption and the newly introduced O(1) scheduler
255       ensures that the time needed to schedule  is  fixed  and  deterministic
256       irrespective  of  the  number of active tasks, true real-time computing
257       was not possible up to kernel version 2.6.17.
258
259   Real-time features in the mainline Linux kernel
260       From kernel version 2.6.18 onwards, however, Linux is gradually  becom‐
261       ing  equipped  with  real-time  capabilities, most of which are derived
262       from the former realtime-preempt  patches  developed  by  Ingo  Molnar,
263       Thomas  Gleixner,  Steven  Rostedt, and others.  Until the patches have
264       been completely merged into the mainline kernel (this is expected to be
265       around  kernel  version  2.6.30), they must be installed to achieve the
266       best real-time performance.  These patches are named:
267
268           patch-kernelversion-rtpatchversion
269
270       and  can  be   downloaded   from   http://www.kernel.org/pub/linux/ker
271       nel/projects/rt/.
272
273       Without the patches and prior to their full inclusion into the mainline
274       kernel, the kernel  configuration  offers  only  the  three  preemption
275       classes  CONFIG_PREEMPT_NONE, CONFIG_PREEMPT_VOLUNTARY, and CONFIG_PRE‐
276       EMPT_DESKTOP which respectively  provide  no,  some,  and  considerable
277       reduction of the worst-case scheduling latency.
278
279       With  the  patches applied or after their full inclusion into the main‐
280       line  kernel,  the  additional  configuration  item   CONFIG_PREEMPT_RT
281       becomes  available.   If  this is selected, Linux is transformed into a
282       regular real-time operating system.  The FIFO and RR  scheduling  poli‐
283       cies  that  can be selected using sched_setscheduler() are then used to
284       run a process with true real-time priority  and  a  minimum  worst-case
285       scheduling latency.
286

BUGS

288       POSIX says that on success, sched_setscheduler() should return the pre‐
289       vious scheduling policy.  Linux sched_setscheduler() does  not  conform
290       to this requirement, since it always returns 0 on success.
291

SEE ALSO

293       getpriority(2),   mlock(2),   mlockall(2),  munlock(2),  munlockall(2),
294       nice(2),     sched_get_priority_max(2),      sched_get_priority_min(2),
295       sched_getaffinity(2),    sched_getparam(2),   sched_rr_get_interval(2),
296       sched_setaffinity(2),  sched_setparam(2),   sched_yield(2),   setprior‐
297       ity(2), capabilities(7), cpuset(7)
298
299       Programming  for  the  real  world  -  POSIX.4  by Bill O. Gallmeister,
300       O'Reilly & Associates, Inc., ISBN 1-56592-074-0
301
302       The  kernel  source   file   Documentation/scheduler/sched-rt-group.txt
303       (since kernel 2.6.25).
304

COLOPHON

306       This  page  is  part of release 3.22 of the Linux man-pages project.  A
307       description of the project, and information about reporting  bugs,  can
308       be found at http://www.kernel.org/doc/man-pages/.
309
310
311
312Linux                             2008-11-06             SCHED_SETSCHEDULER(2)
Impressum