summaryrefslogtreecommitdiffstats
path: root/man2/sched_setscheduler.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/sched_setscheduler.2')
-rw-r--r--man2/sched_setscheduler.2232
1 files changed, 232 insertions, 0 deletions
diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2
new file mode 100644
index 0000000..20ad5c2
--- /dev/null
+++ b/man2/sched_setscheduler.2
@@ -0,0 +1,232 @@
+.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH sched_setscheduler 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+sched_setscheduler, sched_getscheduler \-
+set and get scheduling policy/parameters
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sched.h>
+.PP
+.BI "int sched_setscheduler(pid_t " pid ", int " policy ,
+.BI " const struct sched_param *" param );
+.BI "int sched_getscheduler(pid_t " pid );
+.fi
+.SH DESCRIPTION
+The
+.BR sched_setscheduler ()
+system call
+sets both the scheduling policy and parameters for the
+thread whose ID is specified in \fIpid\fP.
+If \fIpid\fP equals zero, the
+scheduling policy and parameters of the calling thread will be set.
+.PP
+The scheduling parameters are specified in the
+.I param
+argument, which is a pointer to a structure of the following form:
+.PP
+.in +4n
+.EX
+struct sched_param {
+ ...
+ int sched_priority;
+ ...
+};
+.EE
+.in
+.PP
+In the current implementation, the structure contains only one field,
+.IR sched_priority .
+The interpretation of
+.I param
+depends on the selected policy.
+.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
+For each of the above policies,
+.I param\->sched_priority
+must be 0.
+.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
+For each of the above policies,
+.I param\->sched_priority
+specifies a scheduling priority for the thread.
+This is a number in the range returned by calling
+.BR sched_get_priority_min (2)
+and
+.BR sched_get_priority_max (2)
+with the specified
+.IR policy .
+On Linux, these system calls return, respectively, 1 and 99.
+.PP
+Since Linux 2.6.32, the
+.B SCHED_RESET_ON_FORK
+flag can be ORed in
+.I policy
+when calling
+.BR sched_setscheduler ().
+As a result of including this flag, children created by
+.BR fork (2)
+do not inherit privileged scheduling policies.
+See
+.BR sched (7)
+for details.
+.PP
+.BR sched_getscheduler ()
+returns the current scheduling policy of the thread
+identified by \fIpid\fP.
+If \fIpid\fP equals zero, the policy of the
+calling thread will be retrieved.
+.SH RETURN VALUE
+On success,
+.BR sched_setscheduler ()
+returns zero.
+On success,
+.BR sched_getscheduler ()
+returns the policy for the thread (a nonnegative integer).
+On error, both calls return \-1, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+Invalid arguments:
+.I pid
+is negative or
+.I param
+is NULL.
+.TP
+.B EINVAL
+.RB ( sched_setscheduler ())
+.I policy
+is not one of the recognized policies.
+.TP
+.B EINVAL
+.RB ( sched_setscheduler ())
+.I param
+does not make sense for the specified
+.IR policy .
+.TP
+.B EPERM
+The calling thread does not have appropriate privileges.
+.TP
+.B ESRCH
+The thread whose ID is \fIpid\fP could not be found.
+.SH VERSIONS
+POSIX.1 does not detail the permissions that an unprivileged
+thread requires in order to call
+.BR sched_setscheduler (),
+and details vary across systems.
+For example, the Solaris 7 manual page says that
+the real or effective user ID of the caller must
+match the real user ID or the save set-user-ID of the target.
+.PP
+The scheduling policy and parameters are in fact per-thread
+attributes on Linux.
+The value returned from a call to
+.BR gettid (2)
+can be passed in the argument
+.IR pid .
+Specifying
+.I pid
+as 0 will operate on the attributes of the calling thread,
+and passing the value returned from a call to
+.BR getpid (2)
+will operate on the attributes of the main thread of the thread group.
+(If you are using the POSIX threads API, then use
+.BR pthread_setschedparam (3),
+.BR pthread_getschedparam (3),
+and
+.BR pthread_setschedprio (3),
+instead of the
+.BR sched_* (2)
+system calls.)
+.SH STANDARDS
+POSIX.1-2008 (but see BUGS below).
+.PP
+.B SCHED_BATCH
+and
+.B SCHED_IDLE
+are Linux-specific.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+Further details of the semantics of all of the above "normal"
+and "real-time" scheduling policies can be found in the
+.BR sched (7)
+manual page.
+That page also describes an additional policy,
+.BR SCHED_DEADLINE ,
+which is settable only via
+.BR sched_setattr (2).
+.PP
+POSIX systems on which
+.BR sched_setscheduler ()
+and
+.BR sched_getscheduler ()
+are available define
+.B _POSIX_PRIORITY_SCHEDULING
+in \fI<unistd.h>\fP.
+.SH BUGS
+POSIX.1 says that on success,
+.BR sched_setscheduler ()
+should return the previous scheduling policy.
+Linux
+.BR sched_setscheduler ()
+does not conform to this requirement,
+since it always returns 0 on success.
+.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_getattr (2),
+.BR sched_getparam (2),
+.BR sched_rr_get_interval (2),
+.BR sched_setaffinity (2),
+.BR sched_setattr (2),
+.BR sched_setparam (2),
+.BR sched_yield (2),
+.BR setpriority (2),
+.BR capabilities (7),
+.BR cpuset (7),
+.BR sched (7)
+.ad