Debian Codegraph @

upstream/debian-trixie/man2/sched_setscheduler.2

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