Debian Codegraph @

upstream/debian-unstable/man3/pthread_setschedparam.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_setschedparam 3 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_setschedparam, pthread_getschedparam \- set/get
9 scheduling policy and parameters of a thread
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <pthread.h>
16 .P
17 .BI "int pthread_setschedparam(pthread_t " thread ", int " policy ,
18 .BI " const struct sched_param *" param );
19 .BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy ,
20 .BI " struct sched_param *restrict " param );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR pthread_setschedparam ()
25 function sets the scheduling policy and parameters of the thread
26 .IR thread .
27 .P
28 .I policy
29 specifies the new scheduling policy for
30 .IR thread .
31 The supported values for
32 .IR policy ,
33 and their semantics, are described in
34 .BR sched (7).
35 .\" FIXME . pthread_setschedparam() places no restriction on the policy,
36 .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
37 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
38 .P
39 The structure pointed to by
40 .I param
41 specifies the new scheduling parameters for
42 .IR thread .
43 Scheduling parameters are maintained in the following structure:
44 .P
45 .in +4n
46 .EX
47 struct sched_param {
48 int sched_priority; /* Scheduling priority */
49 };
50 .EE
51 .in
52 .P
53 As can be seen, only one scheduling parameter is supported.
54 For details of the permitted ranges for scheduling priorities
55 in each scheduling policy, see
56 .BR sched (7).
57 .P
58 The
59 .BR pthread_getschedparam ()
60 function returns the scheduling policy and parameters of the thread
61 .IR thread ,
62 in the buffers pointed to by
63 .I policy
64 and
65 .IR param ,
66 respectively.
67 The returned priority value is that set by the most recent
68 .BR pthread_setschedparam (),
69 .BR pthread_setschedprio (3),
70 or
71 .BR pthread_create (3)
72 call that affected
73 .IR thread .
74 The returned priority does not reflect any temporary priority adjustments
75 as a result of calls to any priority inheritance or
76 priority ceiling functions (see, for example,
77 .BR pthread_mutexattr_setprioceiling (3)
78 and
79 .BR pthread_mutexattr_setprotocol (3)).
80 .\" FIXME . nptl/pthread_setschedparam.c has the following
81 .\" /* If the thread should have higher priority because of some
82 .\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
83 .\" Eventually (perhaps after writing the mutexattr pages), we
84 .\" may want to add something on the topic to this page.
85 .SH RETURN VALUE
86 On success, these functions return 0;
87 on error, they return a nonzero error number.
88 If
89 .BR pthread_setschedparam ()
90 fails, the scheduling policy and parameters of
91 .I thread
92 are not changed.
93 .SH ERRORS
94 Both of these functions can fail with the following error:
95 .TP
96 .B ESRCH
97 No thread with the ID
98 .I thread
99 could be found.
100 .P
101 .BR pthread_setschedparam ()
102 may additionally fail with the following errors:
103 .TP
104 .B EINVAL
105 .I policy
106 is not a recognized policy, or
107 .I param
108 does not make sense for the
109 .IR policy .
110 .TP
111 .B EPERM
112 The caller does not have appropriate privileges
113 to set the specified scheduling policy and parameters.
114 .P
115 POSIX.1 also documents an
116 .B ENOTSUP
117 ("attempt was made to set the policy or scheduling parameters
118 to an unsupported value") error for
119 .BR pthread_setschedparam ().
120 .SH ATTRIBUTES
121 For an explanation of the terms used in this section, see
122 .BR attributes (7).
123 .TS
124 allbox;
125 lbx lb lb
126 l l l.
127 Interface Attribute Value
128 T{
129 .na
130 .nh
131 .BR pthread_setschedparam (),
132 .BR pthread_getschedparam ()
133 T} Thread safety MT-Safe
134 .TE
135 .SH STANDARDS
136 POSIX.1-2008.
137 .SH HISTORY
138 glibc 2.0
139 POSIX.1-2001.
140 .SH NOTES
141 For a description of the permissions required to, and the effect of,
142 changing a thread's scheduling policy and priority,
143 and details of the permitted ranges for priorities
144 in each scheduling policy, see
145 .BR sched (7).
146 .SH EXAMPLES
147 The program below demonstrates the use of
148 .BR pthread_setschedparam ()
149 and
150 .BR pthread_getschedparam (),
151 as well as the use of a number of other scheduling-related
152 pthreads functions.
153 .P
154 In the following run, the main thread sets its scheduling policy to
155 .B SCHED_FIFO
156 with a priority of 10,
157 and initializes a thread attributes object with
158 a scheduling policy attribute of
159 .B SCHED_RR
160 and a scheduling priority attribute of 20.
161 The program then sets (using
162 .BR pthread_attr_setinheritsched (3))
163 the inherit scheduler attribute of the thread attributes object to
164 .BR PTHREAD_EXPLICIT_SCHED ,
165 meaning that threads created using this attributes object should
166 take their scheduling attributes from the thread attributes object.
167 The program then creates a thread using the thread attributes object,
168 and that thread displays its scheduling policy and priority.
169 .P
170 .in +4n
171 .EX
172 .RB $ " su" "; # Need privilege to set real-time scheduling policies"
173 Password:
174 .RB # " ./a.out \-mf10 \-ar20 \-i e" ;
175 Scheduler settings of main thread
176 policy=SCHED_FIFO, priority=10
177 \&
178 Scheduler settings in \[aq]attr\[aq]
179 policy=SCHED_RR, priority=20
180 inheritsched is EXPLICIT
181 \&
182 Scheduler attributes of new thread
183 policy=SCHED_RR, priority=20
184 .EE
185 .in
186 .P
187 In the above output, one can see that the scheduling policy and priority
188 were taken from the values specified in the thread attributes object.
189 .P
190 The next run is the same as the previous,
191 except that the inherit scheduler attribute is set to
192 .BR PTHREAD_INHERIT_SCHED ,
193 meaning that threads created using the thread attributes object should
194 ignore the scheduling attributes specified in the attributes object
195 and instead take their scheduling attributes from the creating thread.
196 .P
197 .in +4n
198 .EX
199 .RB # " ./a.out \-mf10 \-ar20 \-i i" ;
200 Scheduler settings of main thread
201 policy=SCHED_FIFO, priority=10
202 \&
203 Scheduler settings in \[aq]attr\[aq]
204 policy=SCHED_RR, priority=20
205 inheritsched is INHERIT
206 \&
207 Scheduler attributes of new thread
208 policy=SCHED_FIFO, priority=10
209 .EE
210 .in
211 .P
212 In the above output, one can see that the scheduling policy and priority
213 were taken from the creating thread,
214 rather than the thread attributes object.
215 .P
216 Note that if we had omitted the
217 .I \-i\~i
218 option, the output would have been the same, since
219 .B PTHREAD_INHERIT_SCHED
220 is the default for the inherit scheduler attribute.
221 .SS Program source
222 \&
223 .\" SRC BEGIN (pthreads_sched_test.c)
224 .EX
225 /* pthreads_sched_test.c */
226 \&
227 #include <err.h>
228 #include <errno.h>
229 #include <pthread.h>
230 #include <stdio.h>
231 #include <stdlib.h>
232 #include <unistd.h>
233 \&
234 [[noreturn]]
235 static void
236 usage(char *prog_name, char *msg)
237 {
238 if (msg != NULL)
239 fputs(msg, stderr);
240 \&
241 fprintf(stderr, "Usage: %s [options]\[rs]n", prog_name);
242 fprintf(stderr, "Options are:\[rs]n");
243 #define fpe(msg) fprintf(stderr, "\[rs]t%s", msg) /* Shorter */
244 fpe("\-a<policy><prio> Set scheduling policy and priority in\[rs]n");
245 fpe(" thread attributes object\[rs]n");
246 fpe(" <policy> can be\[rs]n");
247 fpe(" f SCHED_FIFO\[rs]n");
248 fpe(" r SCHED_RR\[rs]n");
249 fpe(" o SCHED_OTHER\[rs]n");
250 fpe("\-A Use default thread attributes object\[rs]n");
251 fpe("\-i {e|i} Set inherit scheduler attribute to\[rs]n");
252 fpe(" \[aq]explicit\[aq] or \[aq]inherit\[aq]\[rs]n");
253 fpe("\-m<policy><prio> Set scheduling policy and priority on\[rs]n");
254 fpe(" main thread before pthread_create() call\[rs]n");
255 exit(EXIT_FAILURE);
256 }
257 \&
258 static int
259 get_policy(char p, int *policy)
260 {
261 switch (p) {
262 case \[aq]f\[aq]: *policy = SCHED_FIFO; return 1;
263 case \[aq]r\[aq]: *policy = SCHED_RR; return 1;
264 case \[aq]o\[aq]: *policy = SCHED_OTHER; return 1;
265 default: return 0;
266 }
267 }
268 \&
269 static void
270 display_sched_attr(int policy, const struct sched_param *param)
271 {
272 printf(" policy=%s, priority=%d\[rs]n",
273 (policy == SCHED_FIFO) ? "SCHED_FIFO" :
274 (policy == SCHED_RR) ? "SCHED_RR" :
275 (policy == SCHED_OTHER) ? "SCHED_OTHER" :
276 "???",
277 param\->sched_priority);
278 }
279 \&
280 static void
281 display_thread_sched_attr(char *msg)
282 {
283 int policy, s;
284 struct sched_param param;
285 \&
286 s = pthread_getschedparam(pthread_self(), &policy, &param);
287 if (s != 0)
288 errc(EXIT_FAILURE, s, "pthread_getschedparam");
289 \&
290 printf("%s\[rs]n", msg);
291 display_sched_attr(policy, &param);
292 }
293 \&
294 static void *
295 thread_start(void *arg)
296 {
297 display_thread_sched_attr("Scheduler attributes of new thread");
298 \&
299 return NULL;
300 }
301 \&
302 int
303 main(int argc, char *argv[])
304 {
305 int s, opt, inheritsched, use_null_attrib, policy;
306 pthread_t thread;
307 pthread_attr_t attr;
308 pthread_attr_t *attrp;
309 char *attr_sched_str, *main_sched_str, *inheritsched_str;
310 struct sched_param param;
311 \&
312 /* Process command\-line options. */
313 \&
314 use_null_attrib = 0;
315 attr_sched_str = NULL;
316 main_sched_str = NULL;
317 inheritsched_str = NULL;
318 \&
319 while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
320 switch (opt) {
321 case \[aq]a\[aq]: attr_sched_str = optarg; break;
322 case \[aq]A\[aq]: use_null_attrib = 1; break;
323 case \[aq]i\[aq]: inheritsched_str = optarg; break;
324 case \[aq]m\[aq]: main_sched_str = optarg; break;
325 default: usage(argv[0], "Unrecognized option\[rs]n");
326 }
327 }
328 \&
329 if (use_null_attrib
330 && (inheritsched_str != NULL || attr_sched_str != NULL))
331 {
332 usage(argv[0], "Can\[aq]t specify \-A with \-i or \-a\[rs]n");
333 }
334 \&
335 /* Optionally set scheduling attributes of main thread,
336 and display the attributes. */
337 \&
338 if (main_sched_str != NULL) {
339 if (!get_policy(main_sched_str[0], &policy))
340 usage(argv[0], "Bad policy for main thread (\-m)\[rs]n");
341 param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
342 \&
343 s = pthread_setschedparam(pthread_self(), policy, &param);
344 if (s != 0)
345 errc(EXIT_FAILURE, s, "pthread_setschedparam");
346 }
347 \&
348 display_thread_sched_attr("Scheduler settings of main thread");
349 printf("\[rs]n");
350 \&
351 /* Initialize thread attributes object according to options. */
352 \&
353 attrp = NULL;
354 \&
355 if (!use_null_attrib) {
356 s = pthread_attr_init(&attr);
357 if (s != 0)
358 errc(EXIT_FAILURE, s, "pthread_attr_init");
359 attrp = &attr;
360 }
361 \&
362 if (inheritsched_str != NULL) {
363 if (inheritsched_str[0] == \[aq]e\[aq])
364 inheritsched = PTHREAD_EXPLICIT_SCHED;
365 else if (inheritsched_str[0] == \[aq]i\[aq])
366 inheritsched = PTHREAD_INHERIT_SCHED;
367 else
368 usage(argv[0], "Value for \-i must be \[aq]e\[aq] or \[aq]i\[aq]\[rs]n");
369 \&
370 s = pthread_attr_setinheritsched(&attr, inheritsched);
371 if (s != 0)
372 errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched");
373 }
374 \&
375 if (attr_sched_str != NULL) {
376 if (!get_policy(attr_sched_str[0], &policy))
377 usage(argv[0], "Bad policy for \[aq]attr\[aq] (\-a)\[rs]n");
378 param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
379 \&
380 s = pthread_attr_setschedpolicy(&attr, policy);
381 if (s != 0)
382 errc(EXIT_FAILURE, s, "pthread_attr_setschedpolicy");
383 s = pthread_attr_setschedparam(&attr, &param);
384 if (s != 0)
385 errc(EXIT_FAILURE, s, "pthread_attr_setschedparam");
386 }
387 \&
388 /* If we initialized a thread attributes object, display
389 the scheduling attributes that were set in the object. */
390 \&
391 if (attrp != NULL) {
392 s = pthread_attr_getschedparam(&attr, &param);
393 if (s != 0)
394 errc(EXIT_FAILURE, s, "pthread_attr_getschedparam");
395 s = pthread_attr_getschedpolicy(&attr, &policy);
396 if (s != 0)
397 errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy");
398 \&
399 printf("Scheduler settings in \[aq]attr\[aq]\[rs]n");
400 display_sched_attr(policy, &param);
401 \&
402 pthread_attr_getinheritsched(&attr, &inheritsched);
403 printf(" inheritsched is %s\[rs]n",
404 (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
405 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
406 "???");
407 printf("\[rs]n");
408 }
409 \&
410 /* Create a thread that will display its scheduling attributes. */
411 \&
412 s = pthread_create(&thread, attrp, &thread_start, NULL);
413 if (s != 0)
414 errc(EXIT_FAILURE, s, "pthread_create");
415 \&
416 /* Destroy unneeded thread attributes object. */
417 \&
418 if (!use_null_attrib) {
419 s = pthread_attr_destroy(&attr);
420 if (s != 0)
421 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
422 }
423 \&
424 s = pthread_join(thread, NULL);
425 if (s != 0)
426 errc(EXIT_FAILURE, s, "pthread_join");
427 \&
428 exit(EXIT_SUCCESS);
429 }
430 .EE
431 .\" SRC END
432 .SH SEE ALSO
433 .ad l
434 .nh
435 .BR getrlimit (2),
436 .BR sched_get_priority_min (2),
437 .BR pthread_attr_init (3),
438 .BR pthread_attr_setinheritsched (3),
439 .BR pthread_attr_setschedparam (3),
440 .BR pthread_attr_setschedpolicy (3),
441 .BR pthread_create (3),
442 .BR pthread_self (3),
443 .BR pthread_setschedprio (3),
444 .BR pthreads (7),
445 .BR sched (7)