1SCHED_SETATTR(2)           Linux Programmer's Manual          SCHED_SETATTR(2)
2
3
4

NAME

6       sched_setattr,  sched_getattr  -  set  and  get  scheduling  policy and
7       attributes
8

SYNOPSIS

10       #include <sched.h>
11
12       int sched_setattr(pid_t pid, struct sched_attr *attr,
13                         unsigned int flags);
14
15       int sched_getattr(pid_t pid, struct sched_attr *attr,
16                         unsigned int size, unsigned int flags);
17

DESCRIPTION

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

RETURN VALUE

178       On success, sched_setattr() and sched_getattr() return 0.  On error, -1
179       is returned, and errno is set to indicate the cause of the error.
180

ERRORS

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

VERSIONS

216       These system calls first appeared in Linux 3.14.
217

CONFORMING TO

219       These system calls are nonstandard Linux extensions.
220

NOTES

222       sched_setattr()   provides   a   superset   of   the  functionality  of
223       sched_setscheduler(2), sched_setparam(2), nice(2), and (other than  the
224       ability  to  set the priority of all processes belonging to a specified
225       user or all processes in a  specified  group)  setpriority(2).   Analo‐
226       gously,  sched_getattr()  provides  a  superset of the functionality of
227       sched_getscheduler(2),  sched_getparam(2),  and  (partially)  getprior‐
228       ity(2).
229

BUGS

231       In  Linux  versions  up  to 3.15, sched_setattr() failed with the error
232       EFAULT instead of E2BIG for the case described in ERRORS.
233

SEE ALSO

235       chrt(1), nice(2), sched_get_priority_max(2), sched_get_priority_min(2),
236       sched_getaffinity(2), sched_getparam(2), sched_getscheduler(2),
237       sched_rr_get_interval(2), sched_setaffinity(2), sched_setparam(2),
238       sched_setscheduler(2), sched_yield(2), setpriority(2),
239       pthread_getschedparam(3), pthread_setschedparam(3),
240       pthread_setschedprio(3), capabilities(7), cpuset(7), sched(7)
241

COLOPHON

243       This  page  is  part of release 5.07 of the Linux man-pages project.  A
244       description of the project, information about reporting bugs,  and  the
245       latest     version     of     this    page,    can    be    found    at
246       https://www.kernel.org/doc/man-pages/.
247
248
249
250Linux                             2019-03-06                  SCHED_SETATTR(2)
Impressum