1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREAD_SETSCHEDPARAM 3 2014-12-31 "Linux" "Linux Programmer's Manual"
28 pthread_setschedparam, pthread_getschedparam \- set/get
29 scheduling policy and parameters of a thread
32 .B #include <pthread.h>
34 .BI "int pthread_setschedparam(pthread_t " thread ", int " policy ,
35 .BI " const struct sched_param *" param );
36 .BI "int pthread_getschedparam(pthread_t " thread ", int *" policy ,
37 .BI " struct sched_param *" param );
39 Compile and link with \fI\-pthread\fP.
43 .BR pthread_setschedparam ()
44 function sets the scheduling policy and parameters of the thread
48 specifies the new scheduling policy for
50 The supported values for
52 and their semantics, are described in
54 .\" FIXME . pthread_setschedparam() places no restriction on the policy,
55 .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
56 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
58 The structure pointed to by
60 specifies the new scheduling parameters for
62 Scheduling parameters are maintained in the following structure:
67 int sched_priority; /* Scheduling priority */
72 As can be seen, only one scheduling parameter is supported.
73 For details of the permitted ranges for scheduling priorities
74 in each scheduling policy, see
78 .BR pthread_getschedparam ()
79 function returns the scheduling policy and parameters of the thread
81 in the buffers pointed to by
86 The returned priority value is that set by the most recent
87 .BR pthread_setschedparam (),
88 .BR pthread_setschedprio (3),
90 .BR pthread_create (3)
93 The returned priority does not reflect any temporary priority adjustments
94 as a result of calls to any priority inheritance or
95 priority ceiling functions (see, for example,
96 .BR pthread_mutexattr_setprioceiling (3)
98 .BR pthread_mutexattr_setprotocol (3)).
99 .\" FIXME . nptl/pthread_setschedparam.c has the following
100 .\" /* If the thread should have higher priority because of some
101 .\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
102 .\" Eventually (perhaps after writing the mutexattr pages), we
103 .\" may want to add something on the topic to this page.
105 On success, these functions return 0;
106 on error, they return a nonzero error number.
108 .BR pthread_setschedparam ()
109 fails, the scheduling policy and parameters of
113 Both of these functions can fail with the following error:
116 No thread with the ID
120 .BR pthread_setschedparam ()
121 may additionally fail with the following errors:
125 is not a recognized policy, or
127 does not make sense for the
131 The caller does not have appropriate privileges
132 to set the specified scheduling policy and parameters.
134 POSIX.1-2001 also documents an
136 ("attempt was made to set the policy or scheduling parameters
137 to an unsupported value") error for
138 .BR pthread_setschedparam ().
140 .\" Available since glibc 2.0
142 .SS Multithreading (see pthreads(7))
144 .BR pthread_setschedparam ()
146 .BR pthread_getschedparam ()
147 functions are thread-safe.
151 For a description of the permissions required to, and the effect of,
152 changing a thread's scheduling policy and priority,
153 and details of the permitted ranges for priorities
154 in each scheduling policy, see
157 The program below demonstrates the use of
158 .BR pthread_setschedparam ()
160 .BR pthread_getschedparam (),
161 as well as the use of a number of other scheduling-related
164 In the following run, the main thread sets its scheduling policy to
166 with a priority of 10,
167 and initializes a thread attributes object with
168 a scheduling policy attribute of
170 and a scheduling priority attribute of 20.
171 The program then sets (using
172 .BR pthread_attr_setinheritsched (3))
173 the inherit scheduler attribute of the thread attributes object to
174 .BR PTHREAD_EXPLICIT_SCHED ,
175 meaning that threads created using this attributes object should
176 take their scheduling attributes from the thread attributes object.
177 The program then creates a thread using the thread attributes object,
178 and that thread displays its scheduling policy and priority.
182 $ \fBsu\fP # Need privilege to set real-time scheduling policies
184 # \fB./a.out \-mf10 \-ar20 \-i e\fP
185 Scheduler settings of main thread
186 policy=SCHED_FIFO, priority=10
188 Scheduler settings in \(aqattr\(aq
189 policy=SCHED_RR, priority=20
190 inheritsched is EXPLICIT
192 Scheduler attributes of new thread
193 policy=SCHED_RR, priority=20
197 In the above output, one can see that the scheduling policy and priority
198 were taken from the values specified in the thread attributes object.
200 The next run is the same as the previous,
201 except that the inherit scheduler attribute is set to
202 .BR PTHREAD_INHERIT_SCHED ,
203 meaning that threads created using the thread attributes object should
204 ignore the scheduling attributes specified in the attributes object
205 and instead take their scheduling attributes from the creating thread.
209 # \fB./a.out \-mf10 \-ar20 \-i i\fP
210 Scheduler settings of main thread
211 policy=SCHED_FIFO, priority=10
213 Scheduler settings in \(aqattr\(aq
214 policy=SCHED_RR, priority=20
215 inheritsched is INHERIT
217 Scheduler attributes of new thread
218 policy=SCHED_FIFO, priority=10
222 In the above output, one can see that the scheduling policy and priority
223 were taken from the creating thread,
224 rather than the thread attributes object.
226 Note that if we had omitted the
228 option, the output would have been the same, since
229 .BR PTHREAD_INHERIT_SCHED
230 is the default for the inherit scheduler attribute.
234 /* pthreads_sched_test.c */
242 #define handle_error_en(en, msg) \\
243 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
246 usage(char *prog_name, char *msg)
251 fprintf(stderr, "Usage: %s [options]\\n", prog_name);
252 fprintf(stderr, "Options are:\\n");
253 #define fpe(msg) fprintf(stderr, "\\t%s", msg); /* Shorter */
254 fpe("\-a<policy><prio> Set scheduling policy and priority in\\n");
255 fpe(" thread attributes object\\n");
256 fpe(" <policy> can be\\n");
257 fpe(" f SCHED_FIFO\\n");
258 fpe(" r SCHED_RR\\n");
259 fpe(" o SCHED_OTHER\\n");
260 fpe("\-A Use default thread attributes object\\n");
261 fpe("\-i {e|i} Set inherit scheduler attribute to\\n");
262 fpe(" \(aqexplicit\(aq or \(aqinherit\(aq\\n");
263 fpe("\-m<policy><prio> Set scheduling policy and priority on\\n");
264 fpe(" main thread before pthread_create() call\\n");
269 get_policy(char p, int *policy)
272 case \(aqf\(aq: *policy = SCHED_FIFO; return 1;
273 case \(aqr\(aq: *policy = SCHED_RR; return 1;
274 case \(aqo\(aq: *policy = SCHED_OTHER; return 1;
280 display_sched_attr(int policy, struct sched_param *param)
282 printf(" policy=%s, priority=%d\\n",
283 (policy == SCHED_FIFO) ? "SCHED_FIFO" :
284 (policy == SCHED_RR) ? "SCHED_RR" :
285 (policy == SCHED_OTHER) ? "SCHED_OTHER" :
287 param\->sched_priority);
291 display_thread_sched_attr(char *msg)
294 struct sched_param param;
296 s = pthread_getschedparam(pthread_self(), &policy, ¶m);
298 handle_error_en(s, "pthread_getschedparam");
300 printf("%s\\n", msg);
301 display_sched_attr(policy, ¶m);
305 thread_start(void *arg)
307 display_thread_sched_attr("Scheduler attributes of new thread");
313 main(int argc, char *argv[])
315 int s, opt, inheritsched, use_null_attrib, policy;
318 pthread_attr_t *attrp;
319 char *attr_sched_str, *main_sched_str, *inheritsched_str;
320 struct sched_param param;
322 /* Process command\-line options */
325 attr_sched_str = NULL;
326 main_sched_str = NULL;
327 inheritsched_str = NULL;
329 while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
331 case \(aqa\(aq: attr_sched_str = optarg; break;
332 case \(aqA\(aq: use_null_attrib = 1; break;
333 case \(aqi\(aq: inheritsched_str = optarg; break;
334 case \(aqm\(aq: main_sched_str = optarg; break;
335 default: usage(argv[0], "Unrecognized option\\n");
339 if (use_null_attrib &&
340 (inheritsched_str != NULL || attr_sched_str != NULL))
341 usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n");
343 /* Optionally set scheduling attributes of main thread,
344 and display the attributes */
346 if (main_sched_str != NULL) {
347 if (!get_policy(main_sched_str[0], &policy))
348 usage(argv[0], "Bad policy for main thread (\-m)\\n");
349 param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
351 s = pthread_setschedparam(pthread_self(), policy, ¶m);
353 handle_error_en(s, "pthread_setschedparam");
356 display_thread_sched_attr("Scheduler settings of main thread");
359 /* Initialize thread attributes object according to options */
363 if (!use_null_attrib) {
364 s = pthread_attr_init(&attr);
366 handle_error_en(s, "pthread_attr_init");
370 if (inheritsched_str != NULL) {
371 if (inheritsched_str[0] == \(aqe\(aq)
372 inheritsched = PTHREAD_EXPLICIT_SCHED;
373 else if (inheritsched_str[0] == \(aqi\(aq)
374 inheritsched = PTHREAD_INHERIT_SCHED;
376 usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n");
378 s = pthread_attr_setinheritsched(&attr, inheritsched);
380 handle_error_en(s, "pthread_attr_setinheritsched");
383 if (attr_sched_str != NULL) {
384 if (!get_policy(attr_sched_str[0], &policy))
386 "Bad policy for \(aqattr\(aq (\-a)\\n");
387 param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
389 s = pthread_attr_setschedpolicy(&attr, policy);
391 handle_error_en(s, "pthread_attr_setschedpolicy");
392 s = pthread_attr_setschedparam(&attr, ¶m);
394 handle_error_en(s, "pthread_attr_setschedparam");
397 /* If we initialized a thread attributes object, display
398 the scheduling attributes that were set in the object */
401 s = pthread_attr_getschedparam(&attr, ¶m);
403 handle_error_en(s, "pthread_attr_getschedparam");
404 s = pthread_attr_getschedpolicy(&attr, &policy);
406 handle_error_en(s, "pthread_attr_getschedpolicy");
408 printf("Scheduler settings in \(aqattr\(aq\\n");
409 display_sched_attr(policy, ¶m);
411 s = pthread_attr_getinheritsched(&attr, &inheritsched);
412 printf(" inheritsched is %s\\n",
413 (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
414 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
419 /* Create a thread that will display its scheduling attributes */
421 s = pthread_create(&thread, attrp, &thread_start, NULL);
423 handle_error_en(s, "pthread_create");
425 /* Destroy unneeded thread attributes object */
427 if (!use_null_attrib) {
428 s = pthread_attr_destroy(&attr);
430 handle_error_en(s, "pthread_attr_destroy");
433 s = pthread_join(thread, NULL);
435 handle_error_en(s, "pthread_join");
444 .BR sched_get_priority_min (2),
445 .BR pthread_attr_init (3),
446 .BR pthread_attr_setinheritsched (3),
447 .BR pthread_attr_setschedparam (3),
448 .BR pthread_attr_setschedpolicy (3),
449 .BR pthread_create (3),
450 .BR pthread_self (3),
451 .BR pthread_setschedprio (3),
455 This page is part of release 3.79 of the Linux
458 A description of the project,
459 information about reporting bugs,
460 and the latest version of this page,
462 \%http://www.kernel.org/doc/man\-pages/.