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