Debian Codegraph @

upstream/debian-unstable/man2/sched_setscheduler.2

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