1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH PTHREAD_SETSCHEDPARAM 3 2021-03-22 "Linux" "Linux Programmer's Manual"
8 pthread_setschedparam, pthread_getschedparam \- set/get
9 scheduling policy and parameters of a thread
12 .RI ( libpthread ", " \-lpthread )
15 .B #include <pthread.h>
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 );
24 .BR pthread_setschedparam ()
25 function sets the scheduling policy and parameters of the thread
29 specifies the new scheduling policy for
31 The supported values for
33 and their semantics, are described in
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
39 The structure pointed to by
41 specifies the new scheduling parameters for
43 Scheduling parameters are maintained in the following structure:
48 int sched_priority; /* Scheduling priority */
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
59 .BR pthread_getschedparam ()
60 function returns the scheduling policy and parameters of the thread
62 in the buffers pointed to by
67 The returned priority value is that set by the most recent
68 .BR pthread_setschedparam (),
69 .BR pthread_setschedprio (3),
71 .BR pthread_create (3)
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)
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.
86 On success, these functions return 0;
87 on error, they return a nonzero error number.
89 .BR pthread_setschedparam ()
90 fails, the scheduling policy and parameters of
94 Both of these functions can fail with the following error:
101 .BR pthread_setschedparam ()
102 may additionally fail with the following errors:
106 is not a recognized policy, or
108 does not make sense for the
112 The caller does not have appropriate privileges
113 to set the specified scheduling policy and parameters.
115 POSIX.1 also documents an
117 ("attempt was made to set the policy or scheduling parameters
118 to an unsupported value") error for
119 .BR pthread_setschedparam ().
121 .\" Available since glibc 2.0
123 For an explanation of the terms used in this section, see
131 Interface Attribute Value
133 .BR pthread_setschedparam (),
134 .BR pthread_getschedparam ()
135 T} Thread safety MT-Safe
141 POSIX.1-2001, POSIX.1-2008.
143 For a description of the permissions required to, and the effect of,
144 changing a thread's scheduling policy and priority,
145 and details of the permitted ranges for priorities
146 in each scheduling policy, see
149 The program below demonstrates the use of
150 .BR pthread_setschedparam ()
152 .BR pthread_getschedparam (),
153 as well as the use of a number of other scheduling-related
156 In the following run, the main thread sets its scheduling policy to
158 with a priority of 10,
159 and initializes a thread attributes object with
160 a scheduling policy attribute of
162 and a scheduling priority attribute of 20.
163 The program then sets (using
164 .BR pthread_attr_setinheritsched (3))
165 the inherit scheduler attribute of the thread attributes object to
166 .BR PTHREAD_EXPLICIT_SCHED ,
167 meaning that threads created using this attributes object should
168 take their scheduling attributes from the thread attributes object.
169 The program then creates a thread using the thread attributes object,
170 and that thread displays its scheduling policy and priority.
174 $ \fBsu\fP # Need privilege to set real\-time scheduling policies
176 # \fB./a.out \-mf10 \-ar20 \-i e\fP
177 Scheduler settings of main thread
178 policy=SCHED_FIFO, priority=10
180 Scheduler settings in \(aqattr\(aq
181 policy=SCHED_RR, priority=20
182 inheritsched is EXPLICIT
184 Scheduler attributes of new thread
185 policy=SCHED_RR, priority=20
189 In the above output, one can see that the scheduling policy and priority
190 were taken from the values specified in the thread attributes object.
192 The next run is the same as the previous,
193 except that the inherit scheduler attribute is set to
194 .BR PTHREAD_INHERIT_SCHED ,
195 meaning that threads created using the thread attributes object should
196 ignore the scheduling attributes specified in the attributes object
197 and instead take their scheduling attributes from the creating thread.
201 # \fB./a.out \-mf10 \-ar20 \-i i\fP
202 Scheduler settings of main thread
203 policy=SCHED_FIFO, priority=10
205 Scheduler settings in \(aqattr\(aq
206 policy=SCHED_RR, priority=20
207 inheritsched is INHERIT
209 Scheduler attributes of new thread
210 policy=SCHED_FIFO, priority=10
214 In the above output, one can see that the scheduling policy and priority
215 were taken from the creating thread,
216 rather than the thread attributes object.
218 Note that if we had omitted the
220 option, the output would have been the same, since
221 .B PTHREAD_INHERIT_SCHED
222 is the default for the inherit scheduler attribute.
226 /* pthreads_sched_test.c */
234 #define handle_error_en(en, msg) \e
235 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
238 usage(char *prog_name, char *msg)
243 fprintf(stderr, "Usage: %s [options]\en", prog_name);
244 fprintf(stderr, "Options are:\en");
245 #define fpe(msg) fprintf(stderr, "\et%s", msg); /* Shorter */
246 fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
247 fpe(" thread attributes object\en");
248 fpe(" <policy> can be\en");
249 fpe(" f SCHED_FIFO\en");
250 fpe(" r SCHED_RR\en");
251 fpe(" o SCHED_OTHER\en");
252 fpe("\-A Use default thread attributes object\en");
253 fpe("\-i {e|i} Set inherit scheduler attribute to\en");
254 fpe(" \(aqexplicit\(aq or \(aqinherit\(aq\en");
255 fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
256 fpe(" main thread before pthread_create() call\en");
261 get_policy(char p, int *policy)
264 case \(aqf\(aq: *policy = SCHED_FIFO; return 1;
265 case \(aqr\(aq: *policy = SCHED_RR; return 1;
266 case \(aqo\(aq: *policy = SCHED_OTHER; return 1;
272 display_sched_attr(int policy, struct sched_param *param)
274 printf(" policy=%s, priority=%d\en",
275 (policy == SCHED_FIFO) ? "SCHED_FIFO" :
276 (policy == SCHED_RR) ? "SCHED_RR" :
277 (policy == SCHED_OTHER) ? "SCHED_OTHER" :
279 param\->sched_priority);
283 display_thread_sched_attr(char *msg)
286 struct sched_param param;
288 s = pthread_getschedparam(pthread_self(), &policy, ¶m);
290 handle_error_en(s, "pthread_getschedparam");
292 printf("%s\en", msg);
293 display_sched_attr(policy, ¶m);
297 thread_start(void *arg)
299 display_thread_sched_attr("Scheduler attributes of new thread");
305 main(int argc, char *argv[])
307 int s, opt, inheritsched, use_null_attrib, policy;
310 pthread_attr_t *attrp;
311 char *attr_sched_str, *main_sched_str, *inheritsched_str;
312 struct sched_param param;
314 /* Process command\-line options. */
317 attr_sched_str = NULL;
318 main_sched_str = NULL;
319 inheritsched_str = NULL;
321 while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
323 case \(aqa\(aq: attr_sched_str = optarg; break;
324 case \(aqA\(aq: use_null_attrib = 1; break;
325 case \(aqi\(aq: inheritsched_str = optarg; break;
326 case \(aqm\(aq: main_sched_str = optarg; break;
327 default: usage(argv[0], "Unrecognized option\en");
331 if (use_null_attrib &&
332 (inheritsched_str != NULL || attr_sched_str != NULL))
333 usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\en");
335 /* Optionally set scheduling attributes of main thread,
336 and display the attributes. */
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)\en");
341 param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
343 s = pthread_setschedparam(pthread_self(), policy, ¶m);
345 handle_error_en(s, "pthread_setschedparam");
348 display_thread_sched_attr("Scheduler settings of main thread");
351 /* Initialize thread attributes object according to options. */
355 if (!use_null_attrib) {
356 s = pthread_attr_init(&attr);
358 handle_error_en(s, "pthread_attr_init");
362 if (inheritsched_str != NULL) {
363 if (inheritsched_str[0] == \(aqe\(aq)
364 inheritsched = PTHREAD_EXPLICIT_SCHED;
365 else if (inheritsched_str[0] == \(aqi\(aq)
366 inheritsched = PTHREAD_INHERIT_SCHED;
368 usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\en");
370 s = pthread_attr_setinheritsched(&attr, inheritsched);
372 handle_error_en(s, "pthread_attr_setinheritsched");
375 if (attr_sched_str != NULL) {
376 if (!get_policy(attr_sched_str[0], &policy))
378 "Bad policy for \(aqattr\(aq (\-a)\en");
379 param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
381 s = pthread_attr_setschedpolicy(&attr, policy);
383 handle_error_en(s, "pthread_attr_setschedpolicy");
384 s = pthread_attr_setschedparam(&attr, ¶m);
386 handle_error_en(s, "pthread_attr_setschedparam");
389 /* If we initialized a thread attributes object, display
390 the scheduling attributes that were set in the object. */
393 s = pthread_attr_getschedparam(&attr, ¶m);
395 handle_error_en(s, "pthread_attr_getschedparam");
396 s = pthread_attr_getschedpolicy(&attr, &policy);
398 handle_error_en(s, "pthread_attr_getschedpolicy");
400 printf("Scheduler settings in \(aqattr\(aq\en");
401 display_sched_attr(policy, ¶m);
403 s = pthread_attr_getinheritsched(&attr, &inheritsched);
404 printf(" inheritsched is %s\en",
405 (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
406 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
411 /* Create a thread that will display its scheduling attributes. */
413 s = pthread_create(&thread, attrp, &thread_start, NULL);
415 handle_error_en(s, "pthread_create");
417 /* Destroy unneeded thread attributes object. */
419 if (!use_null_attrib) {
420 s = pthread_attr_destroy(&attr);
422 handle_error_en(s, "pthread_attr_destroy");
425 s = pthread_join(thread, NULL);
427 handle_error_en(s, "pthread_join");
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),