man2/sched_setattr.2

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 2014 Peter Zijlstra <peterz@infradead.org>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH SCHED_SETATTR 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 sched_setattr, sched_getattr \-
  29 set and get scheduling policy and attributes
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sched.h>
  33 .PP
  34 .BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr ,
  35 .BI "                  unsigned int " flags );
  36 .PP
  37 .BI "int sched_getattr(pid_t " pid ", struct sched_attr *" attr ,
  38 .BI "                  unsigned int " size ", unsigned int " flags );
  39 .fi
  40 .\" FIXME . Add feature test macro requirements
  41 .SH DESCRIPTION
  42 .SS sched_setattr()
  43 The
  44 .BR sched_setattr ()
  45 system call sets the scheduling policy and
  46 associated attributes for the thread whose ID is specified in
  47 .IR pid .
  48 If
  49 .I pid
  50 equals zero,
  51 the scheduling policy and attributes of the calling thread will be set.
  52 .PP
  53 Currently, Linux supports the following "normal"
  54 (i.e., non-real-time) scheduling policies as values that may be specified in
  55 .IR policy :
  56 .TP 14
  57 .BR SCHED_OTHER
  58 the standard round-robin time-sharing policy;
  59 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  60 .\" SCHED_NORMAL.
  61 .TP
  62 .BR SCHED_BATCH
  63 for "batch" style execution of processes; and
  64 .TP
  65 .BR SCHED_IDLE
  66 for running
  67 .I very
  68 low priority background jobs.
  69 .PP
  70 Various "real-time" policies are also supported,
  71 for special time-critical applications that need precise control over
  72 the way in which runnable threads are selected for execution.
  73 For the rules governing when a process may use these policies, see
  74 .BR sched (7).
  75 The real-time policies that may be specified in
  76 .IR policy
  77 are:
  78 .TP 14
  79 .BR SCHED_FIFO
  80 a first-in, first-out policy; and
  81 .TP
  82 .BR SCHED_RR
  83 a round-robin policy.
  84 .PP
  85 Linux also provides the following policy:
  86 .TP 14
  87 .B SCHED_DEADLINE
  88 a deadline scheduling policy; see
  89 .BR sched (7)
  90 for details.
  91 .PP
  92 The
  93 .I attr
  94 argument is a pointer to a structure that defines
  95 the new scheduling policy and attributes for the specified thread.
  96 This structure has the following form:
  97 .PP
  98 .in +4n
  99 .EX
 100 struct sched_attr {
 101     u32 size;              /* Size of this structure */
 102     u32 sched_policy;      /* Policy (SCHED_*) */
 103     u64 sched_flags;       /* Flags */
 104     s32 sched_nice;        /* Nice value (SCHED_OTHER,
 105                               SCHED_BATCH) */
 106     u32 sched_priority;    /* Static priority (SCHED_FIFO,
 107                               SCHED_RR) */
 108     /* Remaining fields are for SCHED_DEADLINE */
 109     u64 sched_runtime;
 110     u64 sched_deadline;
 111     u64 sched_period;
 112 };
 113 .EE
 114 .in
 115 .PP
 116 The fields of this structure are as follows:
 117 .TP
 118 .B size
 119 This field should be set to the size of the structure in bytes, as in
 120 .IR "sizeof(struct sched_attr)" .
 121 If the provided structure is smaller than the kernel structure,
 122 any additional fields are assumed to be '0'.
 123 If the provided structure is larger than the kernel structure,
 124 the kernel verifies that all additional fields are 0;
 125 if they are not,
 126 .BR sched_setattr ()
 127 fails with the error
 128 .BR E2BIG
 129 and updates
 130 .I size
 131 to contain the size of the kernel structure.
 132 .IP
 133 The above behavior when the size of the user-space
 134 .I sched_attr
 135 structure does not match the size of the kernel structure
 136 allows for future extensibility of the interface.
 137 Malformed applications that pass oversize structures
 138 won't break in the future if the size of the kernel
 139 .I sched_attr
 140 structure is increased.
 141 In the future,
 142 it could also allow applications that know about a larger user-space
 143 .I sched_attr
 144 structure to determine whether they are running on an older kernel
 145 that does not support the larger structure.
 146 .TP
 147 .I sched_policy
 148 This field specifies the scheduling policy, as one of the
 149 .BR SCHED_*
 150 values listed above.
 151 .TP
 152 .I sched_flags
 153 This field contains contains zero or more of the following flags
 154 that are ORed together to control scheduling behavior:
 155 .RS
 156 .TP
 157 .BR SCHED_FLAG_RESET_ON_FORK
 158 Children created by
 159 .BR fork (2)
 160 do not inherit privileged scheduling policies.
 161 See
 162 .BR sched (7)
 163 for details.
 164 .TP
 165 .BR SCHED_FLAG_RECLAIM " (since Linux 4.13)"
 166 .\" 2d4283e9d583a3ee8cfb1cbb9c1270614df4c29d
 167 This flag allows a
 168 .BR SCHED_DEADLINE
 169 thread to reclaim bandwidth unused by other real-time threads.
 170 .\" Bandwidth reclaim is done via the GRUB algorithm; see
 171 .\" Documentation/scheduler/sched-deadline.txt
 172 .TP
 173 .BR SCHED_FLAG_DL_OVERRUN " (since Linux 4.16)"
 174 .\" commit 34be39305a77b8b1ec9f279163c7cdb6cc719b91
 175 This flag allows an application to get informed about run-time overruns in
 176 .BR SCHED_DEADLINE
 177 threads.
 178 Such overruns may be caused by (for example) coarse execution time accounting
 179 or incorrect parameter assignment.
 180 Notification takes the form of a
 181 .B SIGXCPU
 182 signal which is generated on each overrun.
 183 .IP
 184 This
 185 .BR SIGXCPU
 186 signal is
 187 .I process-directed
 188 (see
 189 .BR signal (7))
 190 rather than thread-directed.
 191 This is probably a bug.
 192 On the one hand,
 193 .BR sched_setattr ()
 194 is being used to set a per-thread attribute.
 195 On the other hand, if the process-directed signal is delivered to
 196 a thread inside the process other than the one that had a run-time overrun,
 197 the application has no way of knowing which thread overran.
 198 .RE
 199 .TP
 200 .I sched_nice
 201 This field specifies the nice value to be set when specifying
 202 .IR sched_policy
 203 as
 204 .BR SCHED_OTHER
 205 or
 206 .BR SCHED_BATCH .
 207 The nice value is a number in the range \-20 (high priority)
 208 to +19 (low priority); see
 209 .BR sched (7).
 210 .TP
 211 .I sched_priority
 212 This field specifies the static priority to be set when specifying
 213 .IR sched_policy
 214 as
 215 .BR SCHED_FIFO
 216 or
 217 .BR SCHED_RR .
 218 The allowed range of priorities for these policies can be determined using
 219 .BR sched_get_priority_min (2)
 220 and
 221 .BR sched_get_priority_max (2).
 222 For other policies, this field must be specified as 0.
 223 .TP
 224 .I sched_runtime
 225 This field specifies the "Runtime" parameter for deadline scheduling.
 226 The value is expressed in nanoseconds.
 227 This field, and the next two fields,
 228 are used only for
 229 .BR SCHED_DEADLINE
 230 scheduling; for further details, see
 231 .BR sched (7).
 232 .TP
 233 .I sched_deadline
 234 This field specifies the "Deadline" parameter for deadline scheduling.
 235 The value is expressed in nanoseconds.
 236 .TP
 237 .I sched_period
 238 This field specifies the "Period" parameter for deadline scheduling.
 239 The value is expressed in nanoseconds.
 240 .PP
 241 The
 242 .I flags
 243 argument is provided to allow for future extensions to the interface;
 244 in the current implementation it must be specified as 0.
 245 .\"
 246 .\"
 247 .SS sched_getattr()
 248 The
 249 .BR sched_getattr ()
 250 system call fetches the scheduling policy and the
 251 associated attributes for the thread whose ID is specified in
 252 .IR pid .
 253 If
 254 .I pid
 255 equals zero,
 256 the scheduling policy and attributes of the calling thread
 257 will be retrieved.
 258 .PP
 259 The
 260 .I size
 261 argument should be set to the size of the
 262 .I sched_attr
 263 structure as known to user space.
 264 The value must be at least as large as the size of the initially published
 265 .I sched_attr
 266 structure, or the call fails with the error
 267 .BR EINVAL .
 268 .PP
 269 The retrieved scheduling attributes are placed in the fields of the
 270 .I sched_attr
 271 structure pointed to by
 272 .IR attr .
 273 The kernel sets
 274 .I attr.size
 275 to the size of its
 276 .I sched_attr
 277 structure.
 278 .PP
 279 If the caller-provided
 280 .I attr
 281 buffer is larger than the kernel's
 282 .I sched_attr
 283 structure,
 284 the additional bytes in the user-space structure are not touched.
 285 If the caller-provided structure is smaller than the kernel
 286 .I sched_attr
 287 structure and the kernel needs to return values outside the provided space,
 288 .BR sched_getattr ()
 289 fails with the error
 290 .BR E2BIG .
 291 As with
 292 .BR sched_setattr (),
 293 these semantics allow for future extensibility of the interface.
 294 .PP
 295 The
 296 .I flags
 297 argument is provided to allow for future extensions to the interface;
 298 in the current implementation it must be specified as 0.
 299 .SH RETURN VALUE
 300 On success,
 301 .BR sched_setattr ()
 302 and
 303 .BR sched_getattr ()
 304 return 0.
 305 On error, \-1 is returned, and
 306 .I errno
 307 is set to indicate the cause of the error.
 308 .SH ERRORS
 309 .BR sched_getattr ()
 310 and
 311 .BR sched_setattr ()
 312 can both fail for the following reasons:
 313 .TP
 314 .B EINVAL
 315 .I attr
 316 is NULL; or
 317 .I pid
 318 is negative; or
 319 .I flags
 320 is not zero.
 321 .TP
 322 .B ESRCH
 323 The thread whose ID is
 324 .I pid
 325 could not be found.
 326 .PP
 327 In addition,
 328 .BR sched_getattr ()
 329 can fail for the following reasons:
 330 .TP
 331 .B E2BIG
 332 The buffer specified by
 333 .I size
 334 and
 335 .I attr
 336 is too small.
 337 .TP
 338 .B EINVAL
 339 .I size
 340 is invalid; that is, it is smaller than the initial version of the
 341 .I sched_attr
 342 structure (48 bytes) or larger than the system page size.
 343 .PP
 344 In addition,
 345 .BR sched_setattr ()
 346 can fail for the following reasons:
 347 .TP
 348 .B E2BIG
 349 The buffer specified by
 350 .I size
 351 and
 352 .I attr
 353 is larger than the kernel structure,
 354 and one or more of the excess bytes is nonzero.
 355 .TP
 356 .B EBUSY
 357 .B SCHED_DEADLINE
 358 admission control failure, see
 359 .BR sched (7).
 360 .TP
 361 .B EINVAL
 362 .I attr.sched_policy
 363 is not one of the recognized policies;
 364 .I attr.sched_flags
 365 contains a flag other than
 366 .BR SCHED_FLAG_RESET_ON_FORK ;
 367 or
 368 .I attr.sched_priority
 369 is invalid; or
 370 .I attr.sched_policy
 371 is
 372 .BR SCHED_DEADLINE
 373 and the deadline scheduling parameters in
 374 .I attr
 375 are invalid.
 376 .TP
 377 .B EPERM
 378 The caller does not have appropriate privileges.
 379 .TP
 380 .B EPERM
 381 The CPU affinity mask of the thread specified by
 382 .I pid
 383 does not include all CPUs in the system
 384 (see
 385 .BR sched_setaffinity (2)).
 386 .SH VERSIONS
 387 These system calls first appeared in Linux 3.14.
 388 .\" FIXME . Add glibc version
 389 .SH CONFORMING TO
 390 These system calls are nonstandard Linux extensions.
 391 .SH NOTES
 392 .BR sched_setattr ()
 393 provides a superset of the functionality of
 394 .BR sched_setscheduler (2),
 395 .BR sched_setparam (2),
 396 .BR nice (2),
 397 and (other than the ability to set the priority of all processes
 398 belonging to a specified user or all processes in a specified group)
 399 .BR setpriority (2).
 400 Analogously,
 401 .BR sched_getattr ()
 402 provides a superset of the functionality of
 403 .BR sched_getscheduler (2),
 404 .BR sched_getparam (2),
 405 and (partially)
 406 .BR getpriority (2).
 407 .SH BUGS
 408 In Linux versions up to
 409 .\" FIXME . patch sent to Peter Zijlstra
 410 3.15,
 411 .BR sched_settattr ()
 412 failed with the error
 413 .BR EFAULT
 414 instead of
 415 .BR E2BIG
 416 for the case described in ERRORS.
 417 .\" In Linux versions up to up 3.15,
 418 .\" FIXME . patch from Peter Zijlstra pending
 419 .\" .BR sched_setattr ()
 420 .\" allowed a negative
 421 .\" .I attr.sched_policy
 422 .\" value.
 423 .SH SEE ALSO
 424 .ad l
 425 .nh
 426 .BR chrt (1),
 427 .BR nice (2),
 428 .BR sched_get_priority_max (2),
 429 .BR sched_get_priority_min (2),
 430 .BR sched_getaffinity (2),
 431 .BR sched_getparam (2),
 432 .BR sched_getscheduler (2),
 433 .BR sched_rr_get_interval (2),
 434 .BR sched_setaffinity (2),
 435 .BR sched_setparam (2),
 436 .BR sched_setscheduler (2),
 437 .BR sched_yield (2),
 438 .BR setpriority (2),
 439 .BR pthread_getschedparam (3),
 440 .BR pthread_setschedparam (3),
 441 .BR pthread_setschedprio (3),
 442 .BR capabilities (7),
 443 .BR cpuset (7),
 444 .BR sched (7)
 445 .ad