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 2017-09-15 "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 .PP
  34 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
  35 .BI "                       const struct sched_param *" param );
  36 .PP
  37 .BI "int sched_getscheduler(pid_t " pid );
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR sched_setscheduler ()
  42 system call
  43 sets both the scheduling policy and parameters for the
  44 thread whose ID is specified in \fIpid\fP.
  45 If \fIpid\fP equals zero, the
  46 scheduling policy and parameters of the calling thread will be set.
  47 .PP
  48 The scheduling parameters are specified in the
  49 .I param
  50 argument, which is a pointer to a structure of the following form:
  51 .PP
  52 .in +4n
  53 .EX
  54 struct sched_param {
  55     ...
  56     int sched_priority;
  57     ...
  58 };
  59 .EE
  60 .in
  61 .PP
  62 In the current implementation, the structure contains only one field,
  63 .IR sched_priority .
  64 The interpretation of
  65 .I param
  66 depends on the selected policy.
  67 .PP
  68 Currently, Linux supports the following "normal"
  69 (i.e., non-real-time) scheduling policies as values that may be specified in
  70 .IR policy :
  71 .TP 14
  72 .BR SCHED_OTHER
  73 the standard round-robin time-sharing policy;
  74 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  75 .\" SCHED_NORMAL.
  76 .TP
  77 .BR SCHED_BATCH
  78 for "batch" style execution of processes; and
  79 .TP
  80 .BR SCHED_IDLE
  81 for running
  82 .I very
  83 low priority background jobs.
  84 .PP
  85 For each of the above policies,
  86 .IR param\->sched_priority
  87 must be 0.
  88 .PP
  89 Various "real-time" policies are also supported,
  90 for special time-critical applications that need precise control over
  91 the way in which runnable threads are selected for execution.
  92 For the rules governing when a process may use these policies, see
  93 .BR sched (7).
  94 The real-time policies that may be specified in
  95 .IR policy
  96 are:
  97 .TP 14
  98 .BR SCHED_FIFO
  99 a first-in, first-out policy; and
 100 .TP
 101 .BR SCHED_RR
 102 a round-robin policy.
 103 .PP
 104 For each of the above policies,
 105 .IR param\->sched_priority
 106 specifies a scheduling priority for the thread.
 107 This is a number in the range returned by calling
 108 .BR sched_get_priority_min (2)
 109 and
 110 .BR sched_get_priority_max (2)
 111 with the specified
 112 .IR policy .
 113 On Linux, these system calls return, respectively, 1 and 99.
 114 .PP
 115 Since Linux 2.6.32, the
 116 .B SCHED_RESET_ON_FORK
 117 flag can be ORed in
 118 .I policy
 119 when calling
 120 .BR sched_setscheduler ().
 121 As a result of including this flag, children created by
 122 .BR fork (2)
 123 do not inherit privileged scheduling policies.
 124 See
 125 .BR sched (7)
 126 for details.
 127 .PP
 128 .BR sched_getscheduler ()
 129 returns the current scheduling policy of the thread
 130 identified by \fIpid\fP.
 131 If \fIpid\fP equals zero, the policy of the
 132 calling thread will be retrieved.
 133 .SH RETURN VALUE
 134 On success,
 135 .BR sched_setscheduler ()
 136 returns zero.
 137 On success,
 138 .BR sched_getscheduler ()
 139 returns the policy for the thread (a nonnegative integer).
 140 On error, both calls return \-1, and
 141 .I errno
 142 is set appropriately.
 143 .SH ERRORS
 144 .TP
 145 .B EINVAL
 146 Invalid arguments:
 147 .I pid
 148 is negative or
 149 .I param
 150 is NULL.
 151 .TP
 152 .B EINVAL
 153 .RB ( sched_setscheduler ())
 154 .I policy
 155 is not one of the recognized policies.
 156 .TP
 157 .B EINVAL
 158 .RB ( sched_setscheduler ())
 159 .I param
 160 does not make sense for the specified
 161 .IR policy .
 162 .TP
 163 .B EPERM
 164 The calling thread does not have appropriate privileges.
 165 .TP
 166 .B ESRCH
 167 The thread whose ID is \fIpid\fP could not be found.
 168 .SH CONFORMING TO
 169 POSIX.1-2001, POSIX.1-2008 (but see BUGS below).
 170 The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific.
 171 .SH NOTES
 172 Further details of the semantics of all of the above "normal"
 173 and "real-time" scheduling policies can be found in the
 174 .BR sched (7)
 175 manual page.
 176 That page also describes an additional policy,
 177 .BR SCHED_DEADLINE ,
 178 which is settable only via
 179 .BR sched_setattr (2).
 180 .PP
 181 POSIX systems on which
 182 .BR sched_setscheduler ()
 183 and
 184 .BR sched_getscheduler ()
 185 are available define
 186 .B _POSIX_PRIORITY_SCHEDULING
 187 in \fI<unistd.h>\fP.
 188 .PP
 189 POSIX.1 does not detail the permissions that an unprivileged
 190 thread requires in order to call
 191 .BR sched_setscheduler (),
 192 and details vary across systems.
 193 For example, the Solaris 7 manual page says that
 194 the real or effective user ID of the caller must
 195 match the real user ID or the save set-user-ID of the target.
 196 .PP
 197 The scheduling policy and parameters are in fact per-thread
 198 attributes on Linux.
 199 The value returned from a call to
 200 .BR gettid (2)
 201 can be passed in the argument
 202 .IR pid .
 203 Specifying
 204 .I pid
 205 as 0 will operate on the attributes of the calling thread,
 206 and passing the value returned from a call to
 207 .BR getpid (2)
 208 will operate on the attributes of the main thread of the thread group.
 209 (If you are using the POSIX threads API, then use
 210 .BR pthread_setschedparam (3),
 211 .BR pthread_getschedparam (3),
 212 and
 213 .BR pthread_setschedprio (3),
 214 instead of the
 215 .BR sched_* (2)
 216 system calls.)
 217 .SH BUGS
 218 POSIX.1 says that on success,
 219 .BR sched_setscheduler ()
 220 should return the previous scheduling policy.
 221 Linux
 222 .BR sched_setscheduler ()
 223 does not conform to this requirement,
 224 since it always returns 0 on success.
 225 .SH SEE ALSO
 226 .ad l
 227 .nh
 228 .BR chrt (1),
 229 .BR nice (2),
 230 .BR sched_get_priority_max (2),
 231 .BR sched_get_priority_min (2),
 232 .BR sched_getaffinity (2),
 233 .BR sched_getattr (2),
 234 .BR sched_getparam (2),
 235 .BR sched_rr_get_interval (2),
 236 .BR sched_setaffinity (2),
 237 .BR sched_setattr (2),
 238 .BR sched_setparam (2),
 239 .BR sched_yield (2),
 240 .BR setpriority (2),
 241 .BR capabilities (7),
 242 .BR cpuset (7),
 243 .BR sched (7)
 244 .ad