man2/sched_setscheduler.2

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\"
  26 .TH SCHED_SETSCHEDULER 2 2015-08-08 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 sched_setscheduler, sched_getscheduler \-
  29 set and get scheduling policy/parameters
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sched.h>
  33 .sp
  34 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
  35 .br
  36 .BI "                       const struct sched_param *" param );
  37 .sp
  38 .BI "int sched_getscheduler(pid_t " pid );
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR sched_setscheduler ()
  43 system call
  44 sets both the scheduling policy and parameters for the
  45 thread whose ID is specified in \fIpid\fP.
  46 If \fIpid\fP equals zero, the
  47 scheduling policy and parameters of the calling thread will be set.
  48
  49 The scheduling parameters are specified in the
  50 .I param
  51 argument, which is a pointer to a structure of the following form:
  52
  53 .nf
  54 .in +4n
  55 struct sched_param {
  56     ...
  57     int sched_priority;
  58     ...
  59 };
  60 .in
  61 .fi
  62
  63 In the current implementation, the structure contains only one field,
  64 .IR sched_priority .
  65 The interpretation of
  66 .I param
  67 depends on the selected policy.
  68
  69 Currently, Linux supports the following "normal"
  70 (i.e., non-real-time) scheduling policies as values that may be specified in
  71 .IR policy :
  72 .TP 14
  73 .BR SCHED_OTHER
  74 the standard round-robin time-sharing policy;
  75 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  76 .\" SCHED_NORMAL.
  77 .TP
  78 .BR SCHED_BATCH
  79 for "batch" style execution of processes; and
  80 .TP
  81 .BR SCHED_IDLE
  82 for running
  83 .I very
  84 low priority background jobs.
  85 .PP
  86 For each of the above policies,
  87 .IR param\->sched_priority
  88 must be 0.
  89
  90 Various "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 For the rules governing when a process may use these policies, see
  94 .BR sched (7).
  95 The real-time policies that may be specified in
  96 .IR policy
  97 are:
  98 .TP 14
  99 .BR SCHED_FIFO
 100 a first-in, first-out policy; and
 101 .TP
 102 .BR SCHED_RR
 103 a round-robin policy.
 104 .PP
 105 For each of the above policies,
 106 .IR param\->sched_priority
 107 specifies a scheduling priority for the thread.
 108 This is a number in the range returned by calling
 109 .BR sched_get_priority_min (2)
 110 and
 111 .BR sched_get_priority_max (2)
 112 with the specified
 113 .IR policy .
 114 On Linux, these system calls return, respectively, 1 and 99.
 115
 116 Since Linux 2.6.32, the
 117 .B SCHED_RESET_ON_FORK
 118 flag can be ORed in
 119 .I policy
 120 when calling
 121 .BR sched_setscheduler ().
 122 As a result of including this flag, children created by
 123 .BR fork (2)
 124 do not inherit privileged scheduling policies.
 125 See
 126 .BR sched (7)
 127 for details.
 128
 129 .BR sched_getscheduler ()
 130 returns the current scheduling policy of the thread
 131 identified by \fIpid\fP.
 132 If \fIpid\fP equals zero, the policy of the
 133 calling thread will be retrieved.
 134 .SH RETURN VALUE
 135 On success,
 136 .BR sched_setscheduler ()
 137 returns zero.
 138 On success,
 139 .BR sched_getscheduler ()
 140 returns the policy for the thread (a nonnegative integer).
 141 On error, both calls return \-1, and
 142 .I errno
 143 is set appropriately.
 144 .SH ERRORS
 145 .TP
 146 .B EINVAL
 147 Invalid arguments:
 148 .I pid
 149 is negative or
 150 .I param
 151 is NULL.
 152 .TP
 153 .B EINVAL
 154 .RB ( sched_setscheduler ())
 155 .I policy
 156 is not one of the recognized policies.
 157 .TP
 158 .B EINVAL
 159 .RB ( sched_setscheduler ())
 160 .I param
 161 does not make sense for the specified
 162 .IR policy .
 163 .TP
 164 .B EPERM
 165 The calling thread does not have appropriate privileges.
 166 .TP
 167 .B ESRCH
 168 The thread whose ID is \fIpid\fP could not be found.
 169 .SH CONFORMING TO
 170 POSIX.1-2001, POSIX.1-2008 (but see BUGS below).
 171 The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific.
 172 .SH NOTES
 173 Further details of the semantics of all of the above "normal"
 174 and "real-time" scheduling policies can be found in the
 175 .BR sched (7)
 176 manual page.
 177 That page also describes an additional policy,
 178 .BR SCHED_DEADLINE ,
 179 which is settable only via
 180 .BR sched_setattr (2).
 181
 182 POSIX systems on which
 183 .BR sched_setscheduler ()
 184 and
 185 .BR sched_getscheduler ()
 186 are available define
 187 .B _POSIX_PRIORITY_SCHEDULING
 188 in \fI<unistd.h>\fP.
 189
 190 POSIX.1 does not detail the permissions that an unprivileged
 191 thread requires in order to call
 192 .BR sched_setscheduler (),
 193 and details vary across systems.
 194 For example, the Solaris 7 manual page says that
 195 the real or effective user ID of the caller must
 196 match the real user ID or the save set-user-ID of the target.
 197 .PP
 198 The scheduling policy and parameters are in fact per-thread
 199 attributes on Linux.
 200 The value returned from a call to
 201 .BR gettid (2)
 202 can be passed in the argument
 203 .IR pid .
 204 Specifying
 205 .I pid
 206 as 0 will operate on the attributes of the calling thread,
 207 and passing the value returned from a call to
 208 .BR getpid (2)
 209 will operate on the attributes of the main thread of the thread group.
 210 (If you are using the POSIX threads API, then use
 211 .BR pthread_setschedparam (3),
 212 .BR pthread_getschedparam (3),
 213 and
 214 .BR pthread_setschedprio (3),
 215 instead of the
 216 .BR sched_* (2)
 217 system calls.)
 218 .SH BUGS
 219 POSIX.1 says that on success,
 220 .BR sched_setscheduler ()
 221 should return the previous scheduling policy.
 222 Linux
 223 .BR sched_setscheduler ()
 224 does not conform to this requirement,
 225 since it always returns 0 on success.
 226 .SH SEE ALSO
 227 .ad l
 228 .nh
 229 .BR chrt (1),
 230 .BR nice (2),
 231 .BR sched_get_priority_max (2),
 232 .BR sched_get_priority_min (2),
 233 .BR sched_getaffinity (2),
 234 .BR sched_getattr (2),
 235 .BR sched_getparam (2),
 236 .BR sched_rr_get_interval (2),
 237 .BR sched_setaffinity (2),
 238 .BR sched_setattr (2),
 239 .BR sched_setparam (2),
 240 .BR sched_yield (2),
 241 .BR setpriority (2),
 242 .BR capabilities (7),
 243 .BR cpuset (7),
 244 .BR sched (7)
 245 .ad