]>
Commit | Line | Data |
---|---|---|
270d15a2 | 1 | .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da | 4 | .\" |
fea681da | 5 | .\" |
45186a5d | 6 | .TH SCHED_SETSCHEDULER 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
7 | .SH NAME |
8 | sched_setscheduler, sched_getscheduler \- | |
a3a22b7f | 9 | set and get scheduling policy/parameters |
4f20eb75 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
8fc3b2cf | 12 | .RI ( libc ", " \-lc ) |
fea681da | 13 | .SH SYNOPSIS |
92c37d8c | 14 | .nf |
fea681da | 15 | .B #include <sched.h> |
68e4db0a | 16 | .PP |
fea681da | 17 | .BI "int sched_setscheduler(pid_t " pid ", int " policy , |
92c37d8c | 18 | .BI " const struct sched_param *" param ); |
fea681da | 19 | .BI "int sched_getscheduler(pid_t " pid ); |
fea681da MK |
20 | .fi |
21 | .SH DESCRIPTION | |
270d15a2 | 22 | The |
e511ffb6 | 23 | .BR sched_setscheduler () |
270d15a2 MK |
24 | system call |
25 | sets both the scheduling policy and parameters for the | |
81bd66da | 26 | thread whose ID is specified in \fIpid\fP. |
c13182ef | 27 | If \fIpid\fP equals zero, the |
81bd66da | 28 | scheduling policy and parameters of the calling thread will be set. |
efeece04 | 29 | .PP |
270d15a2 MK |
30 | The scheduling parameters are specified in the |
31 | .I param | |
b9136726 | 32 | argument, which is a pointer to a structure of the following form: |
efeece04 | 33 | .PP |
270d15a2 | 34 | .in +4n |
b8302363 | 35 | .EX |
270d15a2 MK |
36 | struct sched_param { |
37 | ... | |
38 | int sched_priority; | |
39 | ... | |
40 | }; | |
b8302363 | 41 | .EE |
e646a1ba | 42 | .in |
efeece04 | 43 | .PP |
270d15a2 MK |
44 | In the current implementation, the structure contains only one field, |
45 | .IR sched_priority . | |
c13182ef | 46 | The interpretation of |
270d15a2 MK |
47 | .I param |
48 | depends on the selected policy. | |
efeece04 | 49 | .PP |
4e592516 | 50 | Currently, Linux supports the following "normal" |
270d15a2 MK |
51 | (i.e., non-real-time) scheduling policies as values that may be specified in |
52 | .IR policy : | |
a3a22b7f | 53 | .TP 14 |
1ae6b2c7 | 54 | .B SCHED_OTHER |
a1d5601b | 55 | the standard round-robin time-sharing policy; |
c13182ef | 56 | .\" In the 2.6 kernel sources, SCHED_OTHER is actually called |
92c37d8c | 57 | .\" SCHED_NORMAL. |
a3a22b7f | 58 | .TP |
1ae6b2c7 | 59 | .B SCHED_BATCH |
a3a22b7f MK |
60 | for "batch" style execution of processes; and |
61 | .TP | |
1ae6b2c7 | 62 | .B SCHED_IDLE |
a3a22b7f MK |
63 | for running |
64 | .I very | |
65 | low priority background jobs. | |
66 | .PP | |
270d15a2 | 67 | For each of the above policies, |
1ae6b2c7 | 68 | .I param\->sched_priority |
270d15a2 | 69 | must be 0. |
efeece04 | 70 | .PP |
270d15a2 | 71 | Various "real-time" policies are also supported, |
a3a22b7f | 72 | for special time-critical applications that need precise control over |
270d15a2 MK |
73 | the way in which runnable threads are selected for execution. |
74 | For the rules governing when a process may use these policies, see | |
75 | .BR sched (7). | |
76 | The real-time policies that may be specified in | |
1ae6b2c7 | 77 | .I policy |
270d15a2 | 78 | are: |
a3a22b7f | 79 | .TP 14 |
1ae6b2c7 | 80 | .B SCHED_FIFO |
a3a22b7f MK |
81 | a first-in, first-out policy; and |
82 | .TP | |
1ae6b2c7 | 83 | .B SCHED_RR |
a3a22b7f MK |
84 | a round-robin policy. |
85 | .PP | |
270d15a2 | 86 | For each of the above policies, |
1ae6b2c7 | 87 | .I param\->sched_priority |
270d15a2 | 88 | specifies a scheduling priority for the thread. |
ab3d0245 | 89 | This is a number in the range returned by calling |
60a90ecd MK |
90 | .BR sched_get_priority_min (2) |
91 | and | |
59ab8fcf | 92 | .BR sched_get_priority_max (2) |
270d15a2 MK |
93 | with the specified |
94 | .IR policy . | |
95 | On Linux, these system calls return, respectively, 1 and 99. | |
efeece04 | 96 | .PP |
93414d35 MK |
97 | Since Linux 2.6.32, the |
98 | .B SCHED_RESET_ON_FORK | |
99 | flag can be ORed in | |
100 | .I policy | |
101 | when calling | |
102 | .BR sched_setscheduler (). | |
103 | As a result of including this flag, children created by | |
104 | .BR fork (2) | |
105 | do not inherit privileged scheduling policies. | |
fd04afa8 | 106 | See |
270d15a2 MK |
107 | .BR sched (7) |
108 | for details. | |
efeece04 | 109 | .PP |
e511ffb6 | 110 | .BR sched_getscheduler () |
270d15a2 MK |
111 | returns the current scheduling policy of the thread |
112 | identified by \fIpid\fP. | |
113 | If \fIpid\fP equals zero, the policy of the | |
114 | calling thread will be retrieved. | |
47297adb | 115 | .SH RETURN VALUE |
fea681da | 116 | On success, |
e511ffb6 | 117 | .BR sched_setscheduler () |
c13182ef | 118 | returns zero. |
fea681da | 119 | On success, |
e511ffb6 | 120 | .BR sched_getscheduler () |
81bd66da | 121 | returns the policy for the thread (a nonnegative integer). |
270d15a2 | 122 | On error, both calls return \-1, and |
fea681da | 123 | .I errno |
f6a4078b | 124 | is set to indicate the error. |
fea681da MK |
125 | .SH ERRORS |
126 | .TP | |
127 | .B EINVAL | |
b61826c0 | 128 | Invalid arguments: |
94417494 | 129 | .I pid |
b61826c0 MK |
130 | is negative or |
131 | .I param | |
132 | is NULL. | |
133 | .TP | |
134 | .B EINVAL | |
6a6dd344 | 135 | .RB ( sched_setscheduler ()) |
b61826c0 MK |
136 | .I policy |
137 | is not one of the recognized policies. | |
138 | .TP | |
139 | .B EINVAL | |
6a6dd344 | 140 | .RB ( sched_setscheduler ()) |
b61826c0 MK |
141 | .I param |
142 | does not make sense for the specified | |
143 | .IR policy . | |
fea681da MK |
144 | .TP |
145 | .B EPERM | |
81bd66da | 146 | The calling thread does not have appropriate privileges. |
fea681da MK |
147 | .TP |
148 | .B ESRCH | |
81bd66da | 149 | The thread whose ID is \fIpid\fP could not be found. |
3113c7f3 | 150 | .SH STANDARDS |
428a4469 | 151 | POSIX.1-2001, POSIX.1-2008 (but see BUGS below). |
c00194ab | 152 | The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific. |
92c37d8c | 153 | .SH NOTES |
270d15a2 | 154 | Further details of the semantics of all of the above "normal" |
16109ab3 MK |
155 | and "real-time" scheduling policies can be found in the |
156 | .BR sched (7) | |
157 | manual page. | |
158 | That page also describes an additional policy, | |
159 | .BR SCHED_DEADLINE , | |
160 | which is settable only via | |
161 | .BR sched_setattr (2). | |
efeece04 | 162 | .PP |
270d15a2 MK |
163 | POSIX systems on which |
164 | .BR sched_setscheduler () | |
165 | and | |
166 | .BR sched_getscheduler () | |
167 | are available define | |
168 | .B _POSIX_PRIORITY_SCHEDULING | |
169 | in \fI<unistd.h>\fP. | |
efeece04 | 170 | .PP |
97bc0094 | 171 | POSIX.1 does not detail the permissions that an unprivileged |
81bd66da | 172 | thread requires in order to call |
f902bebc | 173 | .BR sched_setscheduler (), |
97bc0094 MK |
174 | and details vary across systems. |
175 | For example, the Solaris 7 manual page says that | |
81bd66da MK |
176 | the real or effective user ID of the caller must |
177 | match the real user ID or the save set-user-ID of the target. | |
d5999511 MK |
178 | .PP |
179 | The scheduling policy and parameters are in fact per-thread | |
180 | attributes on Linux. | |
181 | The value returned from a call to | |
182 | .BR gettid (2) | |
183 | can be passed in the argument | |
184 | .IR pid . | |
185 | Specifying | |
186 | .I pid | |
ab3d0245 | 187 | as 0 will operate on the attributes of the calling thread, |
d5999511 MK |
188 | and passing the value returned from a call to |
189 | .BR getpid (2) | |
ab3d0245 | 190 | will operate on the attributes of the main thread of the thread group. |
d5999511 MK |
191 | (If you are using the POSIX threads API, then use |
192 | .BR pthread_setschedparam (3), | |
193 | .BR pthread_getschedparam (3), | |
194 | and | |
195 | .BR pthread_setschedprio (3), | |
196 | instead of the | |
197 | .BR sched_* (2) | |
198 | system calls.) | |
d61ff56a | 199 | .SH BUGS |
99940e05 | 200 | POSIX.1 says that on success, |
d61ff56a MK |
201 | .BR sched_setscheduler () |
202 | should return the previous scheduling policy. | |
203 | Linux | |
204 | .BR sched_setscheduler () | |
205 | does not conform to this requirement, | |
206 | since it always returns 0 on success. | |
47297adb | 207 | .SH SEE ALSO |
ca8a0bd2 MK |
208 | .ad l |
209 | .nh | |
ac30de07 | 210 | .BR chrt (1), |
fea681da MK |
211 | .BR nice (2), |
212 | .BR sched_get_priority_max (2), | |
213 | .BR sched_get_priority_min (2), | |
214 | .BR sched_getaffinity (2), | |
270d15a2 | 215 | .BR sched_getattr (2), |
fea681da MK |
216 | .BR sched_getparam (2), |
217 | .BR sched_rr_get_interval (2), | |
218 | .BR sched_setaffinity (2), | |
270d15a2 | 219 | .BR sched_setattr (2), |
fea681da MK |
220 | .BR sched_setparam (2), |
221 | .BR sched_yield (2), | |
222 | .BR setpriority (2), | |
a18e2edb | 223 | .BR capabilities (7), |
270d15a2 MK |
224 | .BR cpuset (7), |
225 | .BR sched (7) | |
ab13a138 | 226 | .ad |