]>
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 | .\" |
8660ef9f | 26 | .TH PTHREAD_SETSCHEDPARAM 3 2014-05-28 "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> | |
33 | ||
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 ); | |
bec63ef6 MK |
38 | .sp |
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 . | |
46 | ||
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 | |
57 | ||
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: | |
63 | ||
64 | .in +4n | |
65 | .nf | |
66 | struct sched_param { | |
67 | int sched_priority; /* Scheduling priority */ | |
68 | }; | |
69 | .fi | |
70 | .in | |
71 | ||
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). |
bec63ef6 MK |
76 | |
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 MK |
133 | .PP |
134 | POSIX.1-2001 also documents an | |
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 PH |
141 | .SH ATTRIBUTES |
142 | .SS Multithreading (see pthreads(7)) | |
143 | The | |
144 | .BR pthread_setschedparam () | |
145 | and | |
146 | .BR pthread_getschedparam () | |
147 | functions are thread-safe. | |
bec63ef6 MK |
148 | .SH CONFORMING TO |
149 | POSIX.1-2001. | |
150 | .SH NOTES | |
a1ca9644 MK |
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 | |
25ac8173 | 155 | .BR sched (7). |
bec63ef6 MK |
156 | .SH EXAMPLE |
157 | The program below demonstrates the use of | |
158 | .BR pthread_setschedparam () | |
159 | and | |
160 | .BR pthread_getschedparam (), | |
161 | as well as the use of a number of other scheduling-related | |
162 | pthreads functions. | |
163 | ||
164 | In the following run, the main thread sets its scheduling policy to | |
165 | .BR SCHED_FIFO | |
166 | with a priority of 10, | |
167 | and initializes a thread attributes object with | |
168 | a scheduling policy attribute of | |
169 | .BR SCHED_RR | |
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. | |
179 | .in +4n | |
180 | .nf | |
181 | ||
182 | $ \fBsu\fP # Need privilege to set real-time scheduling policies | |
183 | Password: | |
184 | # \fB./a.out \-mf10 \-ar20 \-i e\fP | |
185 | Scheduler settings of main thread | |
186 | policy=SCHED_FIFO, priority=10 | |
187 | ||
188 | Scheduler settings in \(aqattr\(aq | |
189 | policy=SCHED_RR, priority=20 | |
190 | inheritsched is EXPLICIT | |
191 | ||
192 | Scheduler attributes of new thread | |
193 | policy=SCHED_RR, priority=20 | |
194 | .fi | |
195 | .in | |
196 | ||
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. | |
199 | ||
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. | |
206 | ||
207 | .in +4n | |
208 | .nf | |
209 | # \fB./a.out \-mf10 \-ar20 \-i i\fP | |
210 | Scheduler settings of main thread | |
211 | policy=SCHED_FIFO, priority=10 | |
212 | ||
213 | Scheduler settings in \(aqattr\(aq | |
214 | policy=SCHED_RR, priority=20 | |
215 | inheritsched is INHERIT | |
216 | ||
217 | Scheduler attributes of new thread | |
218 | policy=SCHED_FIFO, priority=10 | |
219 | .fi | |
220 | .in | |
221 | ||
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. | |
50b1e6a7 MK |
225 | |
226 | Note that if we had omitted the | |
227 | .IR "\-i\ i" | |
a113945f | 228 | option, the output would have been the same, since |
50b1e6a7 MK |
229 | .BR PTHREAD_INHERIT_SCHED |
230 | is the default for the inherit scheduler attribute. | |
bec63ef6 MK |
231 | .SS Program source |
232 | \& | |
233 | .nf | |
234 | /* pthreads_sched_test.c */ | |
235 | ||
236 | #include <pthread.h> | |
237 | #include <stdio.h> | |
238 | #include <stdlib.h> | |
239 | #include <unistd.h> | |
240 | #include <errno.h> | |
241 | ||
940c8ce2 MK |
242 | #define handle_error_en(en, msg) \\ |
243 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) | |
bec63ef6 MK |
244 | |
245 | static void | |
246 | usage(char *prog_name, char *msg) | |
247 | { | |
248 | if (msg != NULL) | |
249 | fputs(msg, stderr); | |
250 | ||
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"); | |
78e369ff | 261 | fpe("\-i {e|i} Set inherit scheduler attribute to\\n"); |
bec63ef6 MK |
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"); | |
265 | exit(EXIT_FAILURE); | |
c54ed37e | 266 | } |
bec63ef6 MK |
267 | |
268 | static int | |
269 | get_policy(char p, int *policy) | |
270 | { | |
271 | switch (p) { | |
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; | |
275 | default: return 0; | |
276 | } | |
c54ed37e | 277 | } |
bec63ef6 MK |
278 | |
279 | static void | |
280 | display_sched_attr(int policy, struct sched_param *param) | |
281 | { | |
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" : | |
286 | "???", | |
287 | param\->sched_priority); | |
c54ed37e | 288 | } |
bec63ef6 MK |
289 | |
290 | static void | |
291 | display_thread_sched_attr(char *msg) | |
292 | { | |
293 | int policy, s; | |
294 | struct sched_param param; | |
295 | ||
296 | s = pthread_getschedparam(pthread_self(), &policy, ¶m); | |
297 | if (s != 0) | |
940c8ce2 | 298 | handle_error_en(s, "pthread_getschedparam"); |
bec63ef6 MK |
299 | |
300 | printf("%s\\n", msg); | |
301 | display_sched_attr(policy, ¶m); | |
c54ed37e | 302 | } |
bec63ef6 MK |
303 | |
304 | static void * | |
305 | thread_start(void *arg) | |
306 | { | |
307 | display_thread_sched_attr("Scheduler attributes of new thread"); | |
308 | ||
309 | return NULL; | |
c54ed37e | 310 | } |
bec63ef6 MK |
311 | |
312 | int | |
313 | main(int argc, char *argv[]) | |
314 | { | |
315 | int s, opt, inheritsched, use_null_attrib, policy; | |
316 | pthread_t thread; | |
317 | pthread_attr_t attr; | |
318 | pthread_attr_t *attrp; | |
319 | char *attr_sched_str, *main_sched_str, *inheritsched_str; | |
320 | struct sched_param param; | |
321 | ||
322 | /* Process command\-line options */ | |
323 | ||
324 | use_null_attrib = 0; | |
325 | attr_sched_str = NULL; | |
326 | main_sched_str = NULL; | |
327 | inheritsched_str = NULL; | |
328 | ||
329 | while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) { | |
330 | switch (opt) { | |
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"); | |
336 | } | |
337 | } | |
338 | ||
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"); | |
342 | ||
343 | /* Optionally set scheduling attributes of main thread, | |
344 | and display the attributes */ | |
345 | ||
346 | if (main_sched_str != NULL) { | |
347 | if (!get_policy(main_sched_str[0], &policy)) | |
78e369ff | 348 | usage(argv[0], "Bad policy for main thread (\-m)\\n"); |
bec63ef6 MK |
349 | param.sched_priority = strtol(&main_sched_str[1], NULL, 0); |
350 | ||
351 | s = pthread_setschedparam(pthread_self(), policy, ¶m); | |
352 | if (s != 0) | |
940c8ce2 | 353 | handle_error_en(s, "pthread_setschedparam"); |
bec63ef6 MK |
354 | } |
355 | ||
356 | display_thread_sched_attr("Scheduler settings of main thread"); | |
357 | printf("\\n"); | |
358 | ||
359 | /* Initialize thread attributes object according to options */ | |
360 | ||
361 | attrp = NULL; | |
362 | ||
363 | if (!use_null_attrib) { | |
364 | s = pthread_attr_init(&attr); | |
365 | if (s != 0) | |
940c8ce2 | 366 | handle_error_en(s, "pthread_attr_init"); |
bec63ef6 MK |
367 | attrp = &attr; |
368 | } | |
369 | ||
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; | |
375 | else | |
376 | usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n"); | |
377 | ||
378 | s = pthread_attr_setinheritsched(&attr, inheritsched); | |
379 | if (s != 0) | |
940c8ce2 | 380 | handle_error_en(s, "pthread_attr_setinheritsched"); |
bec63ef6 MK |
381 | } |
382 | ||
383 | if (attr_sched_str != NULL) { | |
384 | if (!get_policy(attr_sched_str[0], &policy)) | |
385 | usage(argv[0], | |
386 | "Bad policy for \(aqattr\(aq (\-a)\\n"); | |
387 | param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); | |
388 | ||
389 | s = pthread_attr_setschedpolicy(&attr, policy); | |
390 | if (s != 0) | |
940c8ce2 | 391 | handle_error_en(s, "pthread_attr_setschedpolicy"); |
bec63ef6 MK |
392 | s = pthread_attr_setschedparam(&attr, ¶m); |
393 | if (s != 0) | |
940c8ce2 | 394 | handle_error_en(s, "pthread_attr_setschedparam"); |
bec63ef6 MK |
395 | } |
396 | ||
397 | /* If we initialized a thread attributes object, display | |
398 | the scheduling attributes that were set in the object */ | |
399 | ||
400 | if (attrp != NULL) { | |
401 | s = pthread_attr_getschedparam(&attr, ¶m); | |
402 | if (s != 0) | |
940c8ce2 | 403 | handle_error_en(s, "pthread_attr_getschedparam"); |
bec63ef6 MK |
404 | s = pthread_attr_getschedpolicy(&attr, &policy); |
405 | if (s != 0) | |
940c8ce2 | 406 | handle_error_en(s, "pthread_attr_getschedpolicy"); |
bec63ef6 MK |
407 | |
408 | printf("Scheduler settings in \(aqattr\(aq\\n"); | |
409 | display_sched_attr(policy, ¶m); | |
410 | ||
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" : | |
415 | "???"); | |
416 | printf("\\n"); | |
417 | } | |
418 | ||
419 | /* Create a thread that will display its scheduling attributes */ | |
420 | ||
421 | s = pthread_create(&thread, attrp, &thread_start, NULL); | |
422 | if (s != 0) | |
940c8ce2 | 423 | handle_error_en(s, "pthread_create"); |
bec63ef6 MK |
424 | |
425 | /* Destroy unneeded thread attributes object */ | |
426 | ||
427 | s = pthread_attr_destroy(&attr); | |
428 | if (s != 0) | |
940c8ce2 | 429 | handle_error_en(s, "pthread_attr_destroy"); |
bec63ef6 MK |
430 | |
431 | s = pthread_join(thread, NULL); | |
432 | if (s != 0) | |
940c8ce2 | 433 | handle_error_en(s, "pthread_join"); |
bec63ef6 MK |
434 | |
435 | exit(EXIT_SUCCESS); | |
c54ed37e | 436 | } |
bec63ef6 MK |
437 | .fi |
438 | .SH SEE ALSO | |
ca8a0bd2 MK |
439 | .ad l |
440 | .nh | |
cb4db101 | 441 | .BR getrlimit (2), |
bec63ef6 | 442 | .BR sched_get_priority_min (2), |
bec63ef6 MK |
443 | .BR pthread_attr_init (3), |
444 | .BR pthread_attr_setinheritsched (3), | |
445 | .BR pthread_attr_setschedparam (3), | |
446 | .BR pthread_attr_setschedpolicy (3), | |
bec63ef6 MK |
447 | .BR pthread_create (3), |
448 | .BR pthread_self (3), | |
3e5c319e | 449 | .BR pthread_setschedprio (3), |
25ac8173 MK |
450 | .BR pthreads (7), |
451 | .BR sched (7) |