sched_getattr(2)

1sched_setattr(2)              System Calls Manual             sched_setattr(2)
2
3
4

NAME

6       sched_setattr,  sched_getattr  -  set and get scheduling policy and at‐
7       tributes
8

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <sched.h>            /* Definition of SCHED_* constants */
14       #include <sys/syscall.h>      /* Definition of SYS_* constants */
15       #include <unistd.h>
16
17       int syscall(SYS_sched_setattr, pid_t pid, struct sched_attr *attr,
18                   unsigned int flags);
19       int syscall(SYS_sched_getattr, pid_t pid, struct sched_attr *attr,
20                   unsigned int size, unsigned int flags);
21
22       Note: glibc provides no wrappers for these system calls,  necessitating
23       the use of syscall(2).
24

DESCRIPTION

26   sched_setattr()
27       The  sched_setattr() system call sets the scheduling policy and associ‐
28       ated attributes for the thread whose ID is specified in  pid.   If  pid
29       equals zero, the scheduling policy and attributes of the calling thread
30       will be set.
31
32       Currently, Linux supports the following "normal" (i.e.,  non-real-time)
33       scheduling policies as values that may be specified in policy:
34
35       SCHED_OTHER   the standard round-robin time-sharing policy;
36
37       SCHED_BATCH   for "batch" style execution of processes; and
38
39       SCHED_IDLE    for running very low priority background jobs.
40
41       Various "real-time" policies are also supported, for special time-crit‐
42       ical applications that need precise  control  over  the  way  in  which
43       runnable  threads  are selected for execution.  For the rules governing
44       when a process may use these policies,  see  sched(7).   The  real-time
45       policies that may be specified in policy are:
46
47       SCHED_FIFO    a first-in, first-out policy; and
48
49       SCHED_RR      a round-robin policy.
50
51       Linux also provides the following policy:
52
53       SCHED_DEADLINE
54                     a deadline scheduling policy; see sched(7) for details.
55
56       The  attr  argument  is  a  pointer to a structure that defines the new
57       scheduling policy and attributes for the specified thread.  This struc‐
58       ture has the following form:
59
60           struct sched_attr {
61               u32 size;              /* Size of this structure */
62               u32 sched_policy;      /* Policy (SCHED_*) */
63               u64 sched_flags;       /* Flags */
64               s32 sched_nice;        /* Nice value (SCHED_OTHER,
65                                         SCHED_BATCH) */
66               u32 sched_priority;    /* Static priority (SCHED_FIFO,
67                                         SCHED_RR) */
68               /* Remaining fields are for SCHED_DEADLINE */
69               u64 sched_runtime;
70               u64 sched_deadline;
71               u64 sched_period;
72           };
73
74       The fields of the sched_attr structure are as follows:
75
76       size   This  field should be set to the size of the structure in bytes,
77              as in sizeof(struct sched_attr).  If the provided  structure  is
78              smaller than the kernel structure, any additional fields are as‐
79              sumed to be '0'.  If the provided structure is larger  than  the
80              kernel structure, the kernel verifies that all additional fields
81              are 0; if they are not, sched_setattr()  fails  with  the  error
82              E2BIG  and updates size to contain the size of the kernel struc‐
83              ture.
84
85              The above behavior when the size of  the  user-space  sched_attr
86              structure does not match the size of the kernel structure allows
87              for future extensibility of the interface.   Malformed  applica‐
88              tions that pass oversize structures won't break in the future if
89              the size of the kernel sched_attr structure  is  increased.   In
90              the  future,  it could also allow applications that know about a
91              larger user-space sched_attr structure to determine whether they
92              are  running on an older kernel that does not support the larger
93              structure.
94
95       sched_policy
96              This field specifies  the  scheduling  policy,  as  one  of  the
97              SCHED_* values listed above.
98
99       sched_flags
100              This field contains zero or more of the following flags that are
101              ORed together to control scheduling behavior:
102
103              SCHED_FLAG_RESET_ON_FORK
104                     Children created by fork(2)  do  not  inherit  privileged
105                     scheduling policies.  See sched(7) for details.
106
107              SCHED_FLAG_RECLAIM (since Linux 4.13)
108                     This flag allows a SCHED_DEADLINE thread to reclaim band‐
109                     width unused by other real-time threads.
110
111              SCHED_FLAG_DL_OVERRUN (since Linux 4.16)
112                     This flag allows an application  to  get  informed  about
113                     run-time  overruns in SCHED_DEADLINE threads.  Such over‐
114                     runs may be caused by (for example) coarse execution time
115                     accounting  or incorrect parameter assignment.  Notifica‐
116                     tion takes the form of a SIGXCPU signal which  is  gener‐
117                     ated on each overrun.
118
119                     This  SIGXCPU  signal is process-directed (see signal(7))
120                     rather than thread-directed.  This is probably a bug.  On
121                     the one hand, sched_setattr() is being used to set a per-
122                     thread attribute.  On the other hand, if the  process-di‐
123                     rected signal is delivered to a thread inside the process
124                     other than the one that had a run-time overrun,  the  ap‐
125                     plication has no way of knowing which thread overran.
126
127       sched_nice
128              This  field  specifies  the nice value to be set when specifying
129              sched_policy as SCHED_OTHER or SCHED_BATCH.  The nice value is a
130              number  in  the range -20 (high priority) to +19 (low priority);
131              see sched(7).
132
133       sched_priority
134              This field specifies the static priority to be set when specify‐
135              ing  sched_policy  as SCHED_FIFO or SCHED_RR.  The allowed range
136              of  priorities  for  these  policies  can  be  determined  using
137              sched_get_priority_min(2)  and  sched_get_priority_max(2).   For
138              other policies, this field must be specified as 0.
139
140       sched_runtime
141              This field specifies the "Runtime" parameter for deadline sched‐
142              uling.   The value is expressed in nanoseconds.  This field, and
143              the next two fields, are used only for  SCHED_DEADLINE  schedul‐
144              ing; for further details, see sched(7).
145
146       sched_deadline
147              This  field  specifies  the  "Deadline"  parameter  for deadline
148              scheduling.  The value is expressed in nanoseconds.
149
150       sched_period
151              This field specifies the "Period" parameter for deadline  sched‐
152              uling.  The value is expressed in nanoseconds.
153
154       The  flags  argument  is provided to allow for future extensions to the
155       interface; in the current implementation it must be specified as 0.
156
157   sched_getattr()
158       The sched_getattr() system call fetches the scheduling policy  and  the
159       associated  attributes for the thread whose ID is specified in pid.  If
160       pid equals zero, the scheduling policy and attributes  of  the  calling
161       thread will be retrieved.
162
163       The size argument should be set to the size of the sched_attr structure
164       as known to user space.  The value must be at least  as  large  as  the
165       size of the initially published sched_attr structure, or the call fails
166       with the error EINVAL.
167
168       The retrieved scheduling attributes are placed in  the  fields  of  the
169       sched_attr  structure pointed to by attr.  The kernel sets attr.size to
170       the size of its sched_attr structure.
171
172       If  the  caller-provided  attr  buffer  is  larger  than  the  kernel's
173       sched_attr  structure, the additional bytes in the user-space structure
174       are not touched.  If the caller-provided structure is smaller than  the
175       kernel  sched_attr  structure,  the kernel will silently not return any
176       values which would be stored  outside  the  provided  space.   As  with
177       sched_setattr(),  these semantics allow for future extensibility of the
178       interface.
179
180       The flags argument is provided to allow for future  extensions  to  the
181       interface; in the current implementation it must be specified as 0.
182

RETURN VALUE

184       On success, sched_setattr() and sched_getattr() return 0.  On error, -1
185       is returned, and errno is set to indicate the error.
186

ERRORS

188       sched_getattr() and sched_setattr() can both  fail  for  the  following
189       reasons:
190
191       EINVAL attr is NULL; or pid is negative; or flags is not zero.
192
193       ESRCH  The thread whose ID is pid could not be found.
194
195       In addition, sched_getattr() can fail for the following reasons:
196
197       E2BIG  The buffer specified by size and attr is too small.
198
199       EINVAL size is invalid; that is, it is smaller than the initial version
200              of the sched_attr structure (48 bytes) or larger than the system
201              page size.
202
203       In addition, sched_setattr() can fail for the following reasons:
204
205       E2BIG  The  buffer specified by size and attr is larger than the kernel
206              structure, and one or more of the excess bytes is nonzero.
207
208       EBUSY  SCHED_DEADLINE admission control failure, see sched(7).
209
210       EINVAL attr.sched_policy  is  not  one  of  the  recognized   policies;
211              attr.sched_flags  contains  a  flag  other  than  SCHED_FLAG_RE‐
212              SET_ON_FORK;   or    attr.sched_priority    is    invalid;    or
213              attr.sched_policy  is SCHED_DEADLINE and the deadline scheduling
214              parameters in attr are invalid.
215
216       EPERM  The caller does not have appropriate privileges.
217
218       EPERM  The CPU affinity mask of the thread specified by  pid  does  not
219              include all CPUs in the system (see sched_setaffinity(2)).
220

STANDARDS

222       Linux.
223

HISTORY

225       Linux 3.14.
226

NOTES

228       glibc does not provide wrappers for these system calls; call them using
229       syscall(2).
230
231       sched_setattr()  provides  a   superset   of   the   functionality   of
232       sched_setscheduler(2),  sched_setparam(2), nice(2), and (other than the
233       ability to set the priority of all processes belonging to  a  specified
234       user  or  all  processes  in a specified group) setpriority(2).  Analo‐
235       gously, sched_getattr() provides a superset  of  the  functionality  of
236       sched_getscheduler(2),  sched_getparam(2),  and  (partially)  getprior‐
237       ity(2).
238

BUGS

240       In Linux versions up to 3.15, sched_setattr()  failed  with  the  error
241       EFAULT instead of E2BIG for the case described in ERRORS.
242
243       Up to Linux 5.3, sched_getattr() failed with the error EFBIG if the in-
244       kernel sched_attr structure was larger than the  size  passed  by  user
245       space.
246