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