mirror of https://github.com/mkerrisk/man-pages
461 lines
12 KiB
Groff
461 lines
12 KiB
Groff
.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" and Copyright (C) 2014 Peter Zijlstra <peterz@infradead.org>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH SCHED_SETATTR 2 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sched_setattr, sched_getattr \-
|
|
set and get scheduling policy and attributes
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sched.h>
|
|
.PP
|
|
.BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr ,
|
|
.BI " unsigned int " flags );
|
|
.BI "int 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 :
|
|
There are no glibc wrappers for these system calls; see NOTES.
|
|
.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
|
|
.BR SCHED_OTHER
|
|
the standard round-robin time-sharing policy;
|
|
.\" In the 2.6 kernel sources, SCHED_OTHER is actually called
|
|
.\" SCHED_NORMAL.
|
|
.TP
|
|
.BR SCHED_BATCH
|
|
for "batch" style execution of processes; and
|
|
.TP
|
|
.BR 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
|
|
.IR policy
|
|
are:
|
|
.TP 14
|
|
.BR SCHED_FIFO
|
|
a first-in, first-out policy; and
|
|
.TP
|
|
.BR 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
|
|
.IR 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
|
|
.BR 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
|
|
.BR 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
|
|
.BR 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
|
|
.BR 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
|
|
.BR 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
|
|
.BR 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
|
|
.IR sched_policy
|
|
as
|
|
.BR 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
|
|
.IR sched_policy
|
|
as
|
|
.BR 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
|
|
.BR 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
|
|
.BR 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 VERSIONS
|
|
These system calls first appeared in Linux 3.14.
|
|
.\" FIXME . Add glibc version
|
|
.SH CONFORMING TO
|
|
These system calls are nonstandard Linux extensions.
|
|
.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
|
|
.BR EFAULT
|
|
instead of
|
|
.BR E2BIG
|
|
for the case described in ERRORS.
|
|
.PP
|
|
In Linux versions up to 5.3,
|
|
.BR sched_getattr ()
|
|
failed with the error
|
|
.BR EFBIG
|
|
if the in-kernel
|
|
.IR sched_attr
|
|
structure was larger than the
|
|
.IR 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
|