]>
Commit | Line | Data |
---|---|---|
bec63ef6 MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
bec63ef6 MK |
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. | |
8 | .\" | |
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. | |
13 | .\" | |
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 | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
bec63ef6 | 25 | .\" |
4b8c67d9 | 26 | .TH PTHREAD_SETSCHEDPARAM 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
bec63ef6 | 27 | .SH NAME |
c3665d56 | 28 | pthread_setschedparam, pthread_getschedparam \- set/get |
bec63ef6 MK |
29 | scheduling policy and parameters of a thread |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <pthread.h> | |
f90f031e | 33 | .PP |
553c7766 RV |
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 ); | |
68e4db0a | 38 | .PP |
bec63ef6 | 39 | Compile and link with \fI\-pthread\fP. |
6030f2d8 | 40 | .fi |
bec63ef6 MK |
41 | .SH DESCRIPTION |
42 | The | |
43 | .BR pthread_setschedparam () | |
44 | function sets the scheduling policy and parameters of the thread | |
45 | .IR thread . | |
847e0d88 | 46 | .PP |
bec63ef6 MK |
47 | .I policy |
48 | specifies the new scheduling policy for | |
49 | .IR thread . | |
50 | The supported values for | |
51 | .IR policy , | |
52 | and their semantics, are described in | |
25ac8173 | 53 | .BR sched (7). |
bec63ef6 MK |
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 | |
847e0d88 | 57 | .PP |
bec63ef6 MK |
58 | The structure pointed to by |
59 | .I param | |
60 | specifies the new scheduling parameters for | |
61 | .IR thread . | |
62 | Scheduling parameters are maintained in the following structure: | |
847e0d88 | 63 | .PP |
bec63ef6 | 64 | .in +4n |
b8302363 | 65 | .EX |
bec63ef6 MK |
66 | struct sched_param { |
67 | int sched_priority; /* Scheduling priority */ | |
68 | }; | |
b8302363 | 69 | .EE |
bec63ef6 | 70 | .in |
847e0d88 | 71 | .PP |
4c5f5413 | 72 | As can be seen, only one scheduling parameter is supported. |
bec63ef6 MK |
73 | For details of the permitted ranges for scheduling priorities |
74 | in each scheduling policy, see | |
25ac8173 | 75 | .BR sched (7). |
847e0d88 | 76 | .PP |
bec63ef6 MK |
77 | The |
78 | .BR pthread_getschedparam () | |
79 | function returns the scheduling policy and parameters of the thread | |
80 | .IR thread , | |
81 | in the buffers pointed to by | |
82 | .I policy | |
83 | and | |
84 | .IR param , | |
85 | respectively. | |
86 | The returned priority value is that set by the most recent | |
87 | .BR pthread_setschedparam (), | |
88 | .BR pthread_setschedprio (3), | |
89 | or | |
90 | .BR pthread_create (3) | |
91 | call that affected | |
92 | .IR thread . | |
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) | |
97 | and | |
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. | |
104 | .SH RETURN VALUE | |
105 | On success, these functions return 0; | |
c7094399 | 106 | on error, they return a nonzero error number. |
bec63ef6 MK |
107 | If |
108 | .BR pthread_setschedparam () | |
109 | fails, the scheduling policy and parameters of | |
110 | .I thread | |
111 | are not changed. | |
112 | .SH ERRORS | |
222d90f4 | 113 | Both of these functions can fail with the following error: |
bec63ef6 MK |
114 | .TP |
115 | .B ESRCH | |
116 | No thread with the ID | |
117 | .I thread | |
118 | could be found. | |
119 | .PP | |
120 | .BR pthread_setschedparam () | |
121 | may additionally fail with the following errors: | |
122 | .TP | |
123 | .B EINVAL | |
124 | .I policy | |
125 | is not a recognized policy, or | |
126 | .I param | |
127 | does not make sense for the | |
128 | .IR policy . | |
129 | .TP | |
130 | .B EPERM | |
131 | The caller does not have appropriate privileges | |
bec63ef6 | 132 | to set the specified scheduling policy and parameters. |
bec63ef6 | 133 | .PP |
c0bda60d | 134 | POSIX.1 also documents an |
bec63ef6 MK |
135 | .B ENOTSUP |
136 | ("attempt was made to set the policy or scheduling parameters | |
137 | to an unsupported value") error for | |
138 | .BR pthread_setschedparam (). | |
139 | .\" .SH VERSIONS | |
140 | .\" Available since glibc 2.0 | |
8276212a | 141 | .SH ATTRIBUTES |
5ae1637e PH |
142 | For an explanation of the terms used in this section, see |
143 | .BR attributes (7). | |
144 | .TS | |
145 | allbox; | |
146 | lbw24 lb lb | |
147 | l l l. | |
148 | Interface Attribute Value | |
149 | T{ | |
150 | .BR pthread_setschedparam (), | |
8276212a | 151 | .BR pthread_getschedparam () |
5ae1637e PH |
152 | T} Thread safety MT-Safe |
153 | .TE | |
bec63ef6 | 154 | .SH CONFORMING TO |
c0bda60d | 155 | POSIX.1-2001, POSIX.1-2008. |
bec63ef6 | 156 | .SH NOTES |
a1ca9644 MK |
157 | For a description of the permissions required to, and the effect of, |
158 | changing a thread's scheduling policy and priority, | |
159 | and details of the permitted ranges for priorities | |
160 | in each scheduling policy, see | |
25ac8173 | 161 | .BR sched (7). |
bec63ef6 MK |
162 | .SH EXAMPLE |
163 | The program below demonstrates the use of | |
164 | .BR pthread_setschedparam () | |
165 | and | |
166 | .BR pthread_getschedparam (), | |
167 | as well as the use of a number of other scheduling-related | |
168 | pthreads functions. | |
847e0d88 | 169 | .PP |
bec63ef6 MK |
170 | In the following run, the main thread sets its scheduling policy to |
171 | .BR SCHED_FIFO | |
172 | with a priority of 10, | |
173 | and initializes a thread attributes object with | |
174 | a scheduling policy attribute of | |
175 | .BR SCHED_RR | |
176 | and a scheduling priority attribute of 20. | |
177 | The program then sets (using | |
178 | .BR pthread_attr_setinheritsched (3)) | |
179 | the inherit scheduler attribute of the thread attributes object to | |
180 | .BR PTHREAD_EXPLICIT_SCHED , | |
181 | meaning that threads created using this attributes object should | |
182 | take their scheduling attributes from the thread attributes object. | |
183 | The program then creates a thread using the thread attributes object, | |
184 | and that thread displays its scheduling policy and priority. | |
e646a1ba | 185 | .PP |
bec63ef6 | 186 | .in +4n |
e646a1ba | 187 | .EX |
bec63ef6 MK |
188 | $ \fBsu\fP # Need privilege to set real-time scheduling policies |
189 | Password: | |
190 | # \fB./a.out \-mf10 \-ar20 \-i e\fP | |
191 | Scheduler settings of main thread | |
192 | policy=SCHED_FIFO, priority=10 | |
193 | ||
194 | Scheduler settings in \(aqattr\(aq | |
195 | policy=SCHED_RR, priority=20 | |
196 | inheritsched is EXPLICIT | |
197 | ||
198 | Scheduler attributes of new thread | |
199 | policy=SCHED_RR, priority=20 | |
b8302363 | 200 | .EE |
bec63ef6 | 201 | .in |
847e0d88 | 202 | .PP |
bec63ef6 MK |
203 | In the above output, one can see that the scheduling policy and priority |
204 | were taken from the values specified in the thread attributes object. | |
847e0d88 | 205 | .PP |
bec63ef6 MK |
206 | The next run is the same as the previous, |
207 | except that the inherit scheduler attribute is set to | |
208 | .BR PTHREAD_INHERIT_SCHED , | |
209 | meaning that threads created using the thread attributes object should | |
210 | ignore the scheduling attributes specified in the attributes object | |
211 | and instead take their scheduling attributes from the creating thread. | |
847e0d88 | 212 | .PP |
bec63ef6 | 213 | .in +4n |
b8302363 | 214 | .EX |
bec63ef6 MK |
215 | # \fB./a.out \-mf10 \-ar20 \-i i\fP |
216 | Scheduler settings of main thread | |
217 | policy=SCHED_FIFO, priority=10 | |
218 | ||
219 | Scheduler settings in \(aqattr\(aq | |
220 | policy=SCHED_RR, priority=20 | |
221 | inheritsched is INHERIT | |
222 | ||
223 | Scheduler attributes of new thread | |
224 | policy=SCHED_FIFO, priority=10 | |
b8302363 | 225 | .EE |
bec63ef6 | 226 | .in |
847e0d88 | 227 | .PP |
bec63ef6 MK |
228 | In the above output, one can see that the scheduling policy and priority |
229 | were taken from the creating thread, | |
230 | rather than the thread attributes object. | |
847e0d88 | 231 | .PP |
50b1e6a7 MK |
232 | Note that if we had omitted the |
233 | .IR "\-i\ i" | |
a113945f | 234 | option, the output would have been the same, since |
50b1e6a7 MK |
235 | .BR PTHREAD_INHERIT_SCHED |
236 | is the default for the inherit scheduler attribute. | |
bec63ef6 MK |
237 | .SS Program source |
238 | \& | |
e7d0bb47 | 239 | .EX |
bec63ef6 MK |
240 | /* pthreads_sched_test.c */ |
241 | ||
242 | #include <pthread.h> | |
243 | #include <stdio.h> | |
244 | #include <stdlib.h> | |
245 | #include <unistd.h> | |
246 | #include <errno.h> | |
247 | ||
940c8ce2 MK |
248 | #define handle_error_en(en, msg) \\ |
249 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) | |
bec63ef6 MK |
250 | |
251 | static void | |
252 | usage(char *prog_name, char *msg) | |
253 | { | |
254 | if (msg != NULL) | |
255 | fputs(msg, stderr); | |
256 | ||
257 | fprintf(stderr, "Usage: %s [options]\\n", prog_name); | |
258 | fprintf(stderr, "Options are:\\n"); | |
259 | #define fpe(msg) fprintf(stderr, "\\t%s", msg); /* Shorter */ | |
260 | fpe("\-a<policy><prio> Set scheduling policy and priority in\\n"); | |
261 | fpe(" thread attributes object\\n"); | |
262 | fpe(" <policy> can be\\n"); | |
263 | fpe(" f SCHED_FIFO\\n"); | |
264 | fpe(" r SCHED_RR\\n"); | |
265 | fpe(" o SCHED_OTHER\\n"); | |
266 | fpe("\-A Use default thread attributes object\\n"); | |
78e369ff | 267 | fpe("\-i {e|i} Set inherit scheduler attribute to\\n"); |
bec63ef6 MK |
268 | fpe(" \(aqexplicit\(aq or \(aqinherit\(aq\\n"); |
269 | fpe("\-m<policy><prio> Set scheduling policy and priority on\\n"); | |
270 | fpe(" main thread before pthread_create() call\\n"); | |
271 | exit(EXIT_FAILURE); | |
c54ed37e | 272 | } |
bec63ef6 MK |
273 | |
274 | static int | |
275 | get_policy(char p, int *policy) | |
276 | { | |
277 | switch (p) { | |
278 | case \(aqf\(aq: *policy = SCHED_FIFO; return 1; | |
279 | case \(aqr\(aq: *policy = SCHED_RR; return 1; | |
280 | case \(aqo\(aq: *policy = SCHED_OTHER; return 1; | |
281 | default: return 0; | |
282 | } | |
c54ed37e | 283 | } |
bec63ef6 MK |
284 | |
285 | static void | |
286 | display_sched_attr(int policy, struct sched_param *param) | |
287 | { | |
288 | printf(" policy=%s, priority=%d\\n", | |
289 | (policy == SCHED_FIFO) ? "SCHED_FIFO" : | |
290 | (policy == SCHED_RR) ? "SCHED_RR" : | |
291 | (policy == SCHED_OTHER) ? "SCHED_OTHER" : | |
292 | "???", | |
293 | param\->sched_priority); | |
c54ed37e | 294 | } |
bec63ef6 MK |
295 | |
296 | static void | |
297 | display_thread_sched_attr(char *msg) | |
298 | { | |
299 | int policy, s; | |
300 | struct sched_param param; | |
301 | ||
302 | s = pthread_getschedparam(pthread_self(), &policy, ¶m); | |
303 | if (s != 0) | |
940c8ce2 | 304 | handle_error_en(s, "pthread_getschedparam"); |
bec63ef6 MK |
305 | |
306 | printf("%s\\n", msg); | |
307 | display_sched_attr(policy, ¶m); | |
c54ed37e | 308 | } |
bec63ef6 MK |
309 | |
310 | static void * | |
311 | thread_start(void *arg) | |
312 | { | |
313 | display_thread_sched_attr("Scheduler attributes of new thread"); | |
314 | ||
315 | return NULL; | |
c54ed37e | 316 | } |
bec63ef6 MK |
317 | |
318 | int | |
319 | main(int argc, char *argv[]) | |
320 | { | |
321 | int s, opt, inheritsched, use_null_attrib, policy; | |
322 | pthread_t thread; | |
323 | pthread_attr_t attr; | |
324 | pthread_attr_t *attrp; | |
325 | char *attr_sched_str, *main_sched_str, *inheritsched_str; | |
326 | struct sched_param param; | |
327 | ||
328 | /* Process command\-line options */ | |
329 | ||
330 | use_null_attrib = 0; | |
331 | attr_sched_str = NULL; | |
332 | main_sched_str = NULL; | |
333 | inheritsched_str = NULL; | |
334 | ||
335 | while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) { | |
336 | switch (opt) { | |
337 | case \(aqa\(aq: attr_sched_str = optarg; break; | |
338 | case \(aqA\(aq: use_null_attrib = 1; break; | |
339 | case \(aqi\(aq: inheritsched_str = optarg; break; | |
340 | case \(aqm\(aq: main_sched_str = optarg; break; | |
341 | default: usage(argv[0], "Unrecognized option\\n"); | |
342 | } | |
343 | } | |
344 | ||
345 | if (use_null_attrib && | |
346 | (inheritsched_str != NULL || attr_sched_str != NULL)) | |
347 | usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n"); | |
348 | ||
349 | /* Optionally set scheduling attributes of main thread, | |
350 | and display the attributes */ | |
351 | ||
352 | if (main_sched_str != NULL) { | |
353 | if (!get_policy(main_sched_str[0], &policy)) | |
78e369ff | 354 | usage(argv[0], "Bad policy for main thread (\-m)\\n"); |
bec63ef6 MK |
355 | param.sched_priority = strtol(&main_sched_str[1], NULL, 0); |
356 | ||
357 | s = pthread_setschedparam(pthread_self(), policy, ¶m); | |
358 | if (s != 0) | |
940c8ce2 | 359 | handle_error_en(s, "pthread_setschedparam"); |
bec63ef6 MK |
360 | } |
361 | ||
362 | display_thread_sched_attr("Scheduler settings of main thread"); | |
363 | printf("\\n"); | |
364 | ||
365 | /* Initialize thread attributes object according to options */ | |
366 | ||
367 | attrp = NULL; | |
368 | ||
369 | if (!use_null_attrib) { | |
370 | s = pthread_attr_init(&attr); | |
371 | if (s != 0) | |
940c8ce2 | 372 | handle_error_en(s, "pthread_attr_init"); |
bec63ef6 MK |
373 | attrp = &attr; |
374 | } | |
375 | ||
376 | if (inheritsched_str != NULL) { | |
377 | if (inheritsched_str[0] == \(aqe\(aq) | |
378 | inheritsched = PTHREAD_EXPLICIT_SCHED; | |
379 | else if (inheritsched_str[0] == \(aqi\(aq) | |
380 | inheritsched = PTHREAD_INHERIT_SCHED; | |
381 | else | |
382 | usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n"); | |
383 | ||
384 | s = pthread_attr_setinheritsched(&attr, inheritsched); | |
385 | if (s != 0) | |
940c8ce2 | 386 | handle_error_en(s, "pthread_attr_setinheritsched"); |
bec63ef6 MK |
387 | } |
388 | ||
389 | if (attr_sched_str != NULL) { | |
390 | if (!get_policy(attr_sched_str[0], &policy)) | |
391 | usage(argv[0], | |
392 | "Bad policy for \(aqattr\(aq (\-a)\\n"); | |
393 | param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); | |
394 | ||
395 | s = pthread_attr_setschedpolicy(&attr, policy); | |
396 | if (s != 0) | |
940c8ce2 | 397 | handle_error_en(s, "pthread_attr_setschedpolicy"); |
bec63ef6 MK |
398 | s = pthread_attr_setschedparam(&attr, ¶m); |
399 | if (s != 0) | |
940c8ce2 | 400 | handle_error_en(s, "pthread_attr_setschedparam"); |
bec63ef6 MK |
401 | } |
402 | ||
403 | /* If we initialized a thread attributes object, display | |
404 | the scheduling attributes that were set in the object */ | |
405 | ||
406 | if (attrp != NULL) { | |
407 | s = pthread_attr_getschedparam(&attr, ¶m); | |
408 | if (s != 0) | |
940c8ce2 | 409 | handle_error_en(s, "pthread_attr_getschedparam"); |
bec63ef6 MK |
410 | s = pthread_attr_getschedpolicy(&attr, &policy); |
411 | if (s != 0) | |
940c8ce2 | 412 | handle_error_en(s, "pthread_attr_getschedpolicy"); |
bec63ef6 MK |
413 | |
414 | printf("Scheduler settings in \(aqattr\(aq\\n"); | |
415 | display_sched_attr(policy, ¶m); | |
416 | ||
417 | s = pthread_attr_getinheritsched(&attr, &inheritsched); | |
418 | printf(" inheritsched is %s\\n", | |
419 | (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : | |
420 | (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : | |
421 | "???"); | |
422 | printf("\\n"); | |
423 | } | |
424 | ||
425 | /* Create a thread that will display its scheduling attributes */ | |
426 | ||
427 | s = pthread_create(&thread, attrp, &thread_start, NULL); | |
428 | if (s != 0) | |
940c8ce2 | 429 | handle_error_en(s, "pthread_create"); |
bec63ef6 MK |
430 | |
431 | /* Destroy unneeded thread attributes object */ | |
432 | ||
c420c4a1 SN |
433 | if (!use_null_attrib) { |
434 | s = pthread_attr_destroy(&attr); | |
435 | if (s != 0) | |
436 | handle_error_en(s, "pthread_attr_destroy"); | |
437 | } | |
bec63ef6 MK |
438 | |
439 | s = pthread_join(thread, NULL); | |
440 | if (s != 0) | |
940c8ce2 | 441 | handle_error_en(s, "pthread_join"); |
bec63ef6 MK |
442 | |
443 | exit(EXIT_SUCCESS); | |
c54ed37e | 444 | } |
e7d0bb47 | 445 | .EE |
bec63ef6 | 446 | .SH SEE ALSO |
ca8a0bd2 MK |
447 | .ad l |
448 | .nh | |
cb4db101 | 449 | .BR getrlimit (2), |
bec63ef6 | 450 | .BR sched_get_priority_min (2), |
bec63ef6 MK |
451 | .BR pthread_attr_init (3), |
452 | .BR pthread_attr_setinheritsched (3), | |
453 | .BR pthread_attr_setschedparam (3), | |
454 | .BR pthread_attr_setschedpolicy (3), | |
bec63ef6 MK |
455 | .BR pthread_create (3), |
456 | .BR pthread_self (3), | |
3e5c319e | 457 | .BR pthread_setschedprio (3), |
25ac8173 MK |
458 | .BR pthreads (7), |
459 | .BR sched (7) |