diff options
Diffstat (limited to 'man2/sched_setattr.2')
| -rw-r--r-- | man2/sched_setattr.2 | 447 |
1 files changed, 0 insertions, 447 deletions
diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 deleted file mode 100644 index fd92a86b2..000000000 --- a/man2/sched_setattr.2 +++ /dev/null @@ -1,447 +0,0 @@ -.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> -.\" and Copyright (C) 2014 Peter Zijlstra <peterz@infradead.org> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH sched_setattr 2 (date) "Linux man-pages (unreleased)" -.SH NAME -sched_setattr, sched_getattr \- -set and get scheduling policy and attributes -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.BR "#include <sched.h>" " /* Definition of " SCHED_* " constants */" -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.B #include <unistd.h> -.PP -.BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr , -.BI " unsigned int " flags ); -.BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr , -.BI " unsigned int " size ", unsigned int " flags ); -.fi -.\" FIXME . Add feature test macro requirements -.PP -.IR Note : -glibc provides no wrappers for these system calls, -necessitating the use of -.BR syscall (2). -.SH DESCRIPTION -.SS sched_setattr() -The -.BR sched_setattr () -system call sets the scheduling policy and -associated attributes for the thread whose ID is specified in -.IR pid . -If -.I pid -equals zero, -the scheduling policy and attributes of the calling thread will be set. -.PP -Currently, Linux supports the following "normal" -(i.e., non-real-time) scheduling policies as values that may be specified in -.IR policy : -.TP 14 -.B SCHED_OTHER -the standard round-robin time-sharing policy; -.\" In the 2.6 kernel sources, SCHED_OTHER is actually called -.\" SCHED_NORMAL. -.TP -.B SCHED_BATCH -for "batch" style execution of processes; and -.TP -.B SCHED_IDLE -for running -.I very -low priority background jobs. -.PP -Various "real-time" policies are also supported, -for special time-critical applications that need precise control over -the way in which runnable threads are selected for execution. -For the rules governing when a process may use these policies, see -.BR sched (7). -The real-time policies that may be specified in -.I policy -are: -.TP 14 -.B SCHED_FIFO -a first-in, first-out policy; and -.TP -.B SCHED_RR -a round-robin policy. -.PP -Linux also provides the following policy: -.TP 14 -.B SCHED_DEADLINE -a deadline scheduling policy; see -.BR sched (7) -for details. -.PP -The -.I attr -argument is a pointer to a structure that defines -the new scheduling policy and attributes for the specified thread. -This structure has the following form: -.PP -.in +4n -.EX -struct sched_attr { - u32 size; /* Size of this structure */ - u32 sched_policy; /* Policy (SCHED_*) */ - u64 sched_flags; /* Flags */ - s32 sched_nice; /* Nice value (SCHED_OTHER, - SCHED_BATCH) */ - u32 sched_priority; /* Static priority (SCHED_FIFO, - SCHED_RR) */ - /* Remaining fields are for SCHED_DEADLINE */ - u64 sched_runtime; - u64 sched_deadline; - u64 sched_period; -}; -.EE -.in -.PP -The fields of the -.I sched_attr -structure are as follows: -.TP -.B size -This field should be set to the size of the structure in bytes, as in -.IR "sizeof(struct sched_attr)" . -If the provided structure is smaller than the kernel structure, -any additional fields are assumed to be '0'. -If the provided structure is larger than the kernel structure, -the kernel verifies that all additional fields are 0; -if they are not, -.BR sched_setattr () -fails with the error -.B E2BIG -and updates -.I size -to contain the size of the kernel structure. -.IP -The above behavior when the size of the user-space -.I sched_attr -structure does not match the size of the kernel structure -allows for future extensibility of the interface. -Malformed applications that pass oversize structures -won't break in the future if the size of the kernel -.I sched_attr -structure is increased. -In the future, -it could also allow applications that know about a larger user-space -.I sched_attr -structure to determine whether they are running on an older kernel -that does not support the larger structure. -.TP -.I sched_policy -This field specifies the scheduling policy, as one of the -.B SCHED_* -values listed above. -.TP -.I sched_flags -This field contains zero or more of the following flags -that are ORed together to control scheduling behavior: -.RS -.TP -.B SCHED_FLAG_RESET_ON_FORK -Children created by -.BR fork (2) -do not inherit privileged scheduling policies. -See -.BR sched (7) -for details. -.TP -.BR SCHED_FLAG_RECLAIM " (since Linux 4.13)" -.\" 2d4283e9d583a3ee8cfb1cbb9c1270614df4c29d -This flag allows a -.B SCHED_DEADLINE -thread to reclaim bandwidth unused by other real-time threads. -.\" Bandwidth reclaim is done via the GRUB algorithm; see -.\" Documentation/scheduler/sched-deadline.txt -.TP -.BR SCHED_FLAG_DL_OVERRUN " (since Linux 4.16)" -.\" commit 34be39305a77b8b1ec9f279163c7cdb6cc719b91 -This flag allows an application to get informed about run-time overruns in -.B SCHED_DEADLINE -threads. -Such overruns may be caused by (for example) coarse execution time accounting -or incorrect parameter assignment. -Notification takes the form of a -.B SIGXCPU -signal which is generated on each overrun. -.IP -This -.B SIGXCPU -signal is -.I process-directed -(see -.BR signal (7)) -rather than thread-directed. -This is probably a bug. -On the one hand, -.BR sched_setattr () -is being used to set a per-thread attribute. -On the other hand, if the process-directed signal is delivered to -a thread inside the process other than the one that had a run-time overrun, -the application has no way of knowing which thread overran. -.RE -.TP -.I sched_nice -This field specifies the nice value to be set when specifying -.I sched_policy -as -.B SCHED_OTHER -or -.BR SCHED_BATCH . -The nice value is a number in the range \-20 (high priority) -to +19 (low priority); see -.BR sched (7). -.TP -.I sched_priority -This field specifies the static priority to be set when specifying -.I sched_policy -as -.B SCHED_FIFO -or -.BR SCHED_RR . -The allowed range of priorities for these policies can be determined using -.BR sched_get_priority_min (2) -and -.BR sched_get_priority_max (2). -For other policies, this field must be specified as 0. -.TP -.I sched_runtime -This field specifies the "Runtime" parameter for deadline scheduling. -The value is expressed in nanoseconds. -This field, and the next two fields, -are used only for -.B SCHED_DEADLINE -scheduling; for further details, see -.BR sched (7). -.TP -.I sched_deadline -This field specifies the "Deadline" parameter for deadline scheduling. -The value is expressed in nanoseconds. -.TP -.I sched_period -This field specifies the "Period" parameter for deadline scheduling. -The value is expressed in nanoseconds. -.PP -The -.I flags -argument is provided to allow for future extensions to the interface; -in the current implementation it must be specified as 0. -.\" -.\" -.SS sched_getattr() -The -.BR sched_getattr () -system call fetches the scheduling policy and the -associated attributes for the thread whose ID is specified in -.IR pid . -If -.I pid -equals zero, -the scheduling policy and attributes of the calling thread -will be retrieved. -.PP -The -.I size -argument should be set to the size of the -.I sched_attr -structure as known to user space. -The value must be at least as large as the size of the initially published -.I sched_attr -structure, or the call fails with the error -.BR EINVAL . -.PP -The retrieved scheduling attributes are placed in the fields of the -.I sched_attr -structure pointed to by -.IR attr . -The kernel sets -.I attr.size -to the size of its -.I sched_attr -structure. -.PP -If the caller-provided -.I attr -buffer is larger than the kernel's -.I sched_attr -structure, -the additional bytes in the user-space structure are not touched. -If the caller-provided structure is smaller than the kernel -.I sched_attr -structure, the kernel will silently not return any values which would be stored -outside the provided space. -As with -.BR sched_setattr (), -these semantics allow for future extensibility of the interface. -.PP -The -.I flags -argument is provided to allow for future extensions to the interface; -in the current implementation it must be specified as 0. -.SH RETURN VALUE -On success, -.BR sched_setattr () -and -.BR sched_getattr () -return 0. -On error, \-1 is returned, and -.I errno -is set to indicate the error. -.SH ERRORS -.BR sched_getattr () -and -.BR sched_setattr () -can both fail for the following reasons: -.TP -.B EINVAL -.I attr -is NULL; or -.I pid -is negative; or -.I flags -is not zero. -.TP -.B ESRCH -The thread whose ID is -.I pid -could not be found. -.PP -In addition, -.BR sched_getattr () -can fail for the following reasons: -.TP -.B E2BIG -The buffer specified by -.I size -and -.I attr -is too small. -.TP -.B EINVAL -.I size -is invalid; that is, it is smaller than the initial version of the -.I sched_attr -structure (48 bytes) or larger than the system page size. -.PP -In addition, -.BR sched_setattr () -can fail for the following reasons: -.TP -.B E2BIG -The buffer specified by -.I size -and -.I attr -is larger than the kernel structure, -and one or more of the excess bytes is nonzero. -.TP -.B EBUSY -.B SCHED_DEADLINE -admission control failure, see -.BR sched (7). -.TP -.B EINVAL -.I attr.sched_policy -is not one of the recognized policies; -.I attr.sched_flags -contains a flag other than -.BR SCHED_FLAG_RESET_ON_FORK ; -or -.I attr.sched_priority -is invalid; or -.I attr.sched_policy -is -.B SCHED_DEADLINE -and the deadline scheduling parameters in -.I attr -are invalid. -.TP -.B EPERM -The caller does not have appropriate privileges. -.TP -.B EPERM -The CPU affinity mask of the thread specified by -.I pid -does not include all CPUs in the system -(see -.BR sched_setaffinity (2)). -.SH STANDARDS -Linux. -.SH HISTORY -Linux 3.14. -.\" FIXME . Add glibc version -.SH NOTES -glibc does not provide wrappers for these system calls; call them using -.BR syscall (2). -.PP -.BR sched_setattr () -provides a superset of the functionality of -.BR sched_setscheduler (2), -.BR sched_setparam (2), -.BR nice (2), -and (other than the ability to set the priority of all processes -belonging to a specified user or all processes in a specified group) -.BR setpriority (2). -Analogously, -.BR sched_getattr () -provides a superset of the functionality of -.BR sched_getscheduler (2), -.BR sched_getparam (2), -and (partially) -.BR getpriority (2). -.SH BUGS -In Linux versions up to -.\" FIXME . patch sent to Peter Zijlstra -3.15, -.BR sched_setattr () -failed with the error -.B EFAULT -instead of -.B E2BIG -for the case described in ERRORS. -.PP -Up to Linux 5.3, -.BR sched_getattr () -failed with the error -.B EFBIG -if the in-kernel -.I sched_attr -structure was larger than the -.I size -passed by user space. -.\" In Linux versions up to up 3.15, -.\" FIXME . patch from Peter Zijlstra pending -.\" .BR sched_setattr () -.\" allowed a negative -.\" .I attr.sched_policy -.\" value. -.SH SEE ALSO -.ad l -.nh -.BR chrt (1), -.BR nice (2), -.BR sched_get_priority_max (2), -.BR sched_get_priority_min (2), -.BR sched_getaffinity (2), -.BR sched_getparam (2), -.BR sched_getscheduler (2), -.BR sched_rr_get_interval (2), -.BR sched_setaffinity (2), -.BR sched_setparam (2), -.BR sched_setscheduler (2), -.BR sched_yield (2), -.BR setpriority (2), -.BR pthread_getschedparam (3), -.BR pthread_setschedparam (3), -.BR pthread_setschedprio (3), -.BR capabilities (7), -.BR cpuset (7), -.BR sched (7) -.ad |