]>
Commit | Line | Data |
---|---|---|
bec63ef6 MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" | |
4c5f5413 | 24 | .TH PTHREAD_SETSCHEDPARAM 3 2008-11-17 "Linux" "Linux Programmer's Manual" |
bec63ef6 | 25 | .SH NAME |
c3665d56 | 26 | pthread_setschedparam, pthread_getschedparam \- set/get |
bec63ef6 MK |
27 | scheduling policy and parameters of a thread |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <pthread.h> | |
31 | ||
32 | .BI "pthread_setschedparam(pthread_t " thread ", int " policy , | |
33 | .BI " const struct sched_param *" param ); | |
34 | .BI "pthread_getschedparam(pthread_t " thread ", int *" policy , | |
35 | .BI " struct sched_param *" param ); | |
36 | .sp | |
37 | Compile and link with \fI\-pthread\fP. | |
38 | .SH DESCRIPTION | |
39 | The | |
40 | .BR pthread_setschedparam () | |
41 | function sets the scheduling policy and parameters of the thread | |
42 | .IR thread . | |
43 | ||
44 | .I policy | |
45 | specifies the new scheduling policy for | |
46 | .IR thread . | |
47 | The supported values for | |
48 | .IR policy , | |
49 | and their semantics, are described in | |
50 | .BR sched_setscheduler (2). | |
51 | .\" FIXME . pthread_setschedparam() places no restriction on the policy, | |
52 | .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER | |
53 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 | |
54 | ||
55 | The structure pointed to by | |
56 | .I param | |
57 | specifies the new scheduling parameters for | |
58 | .IR thread . | |
59 | Scheduling parameters are maintained in the following structure: | |
60 | ||
61 | .in +4n | |
62 | .nf | |
63 | struct sched_param { | |
64 | int sched_priority; /* Scheduling priority */ | |
65 | }; | |
66 | .fi | |
67 | .in | |
68 | ||
4c5f5413 | 69 | As can be seen, only one scheduling parameter is supported. |
bec63ef6 MK |
70 | For details of the permitted ranges for scheduling priorities |
71 | in each scheduling policy, see | |
72 | .BR sched_setscheduler (2). | |
73 | ||
74 | The | |
75 | .BR pthread_getschedparam () | |
76 | function returns the scheduling policy and parameters of the thread | |
77 | .IR thread , | |
78 | in the buffers pointed to by | |
79 | .I policy | |
80 | and | |
81 | .IR param , | |
82 | respectively. | |
83 | The returned priority value is that set by the most recent | |
84 | .BR pthread_setschedparam (), | |
85 | .BR pthread_setschedprio (3), | |
86 | or | |
87 | .BR pthread_create (3) | |
88 | call that affected | |
89 | .IR thread . | |
90 | The returned priority does not reflect any temporary priority adjustments | |
91 | as a result of calls to any priority inheritance or | |
92 | priority ceiling functions (see, for example, | |
93 | .BR pthread_mutexattr_setprioceiling (3) | |
94 | and | |
95 | .BR pthread_mutexattr_setprotocol (3)). | |
96 | .\" FIXME . nptl/pthread_setschedparam.c has the following | |
97 | .\" /* If the thread should have higher priority because of some | |
98 | .\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ | |
99 | .\" Eventually (perhaps after writing the mutexattr pages), we | |
100 | .\" may want to add something on the topic to this page. | |
101 | .SH RETURN VALUE | |
102 | On success, these functions return 0; | |
c7094399 | 103 | on error, they return a nonzero error number. |
bec63ef6 MK |
104 | If |
105 | .BR pthread_setschedparam () | |
106 | fails, the scheduling policy and parameters of | |
107 | .I thread | |
108 | are not changed. | |
109 | .SH ERRORS | |
222d90f4 | 110 | Both of these functions can fail with the following error: |
bec63ef6 MK |
111 | .TP |
112 | .B ESRCH | |
113 | No thread with the ID | |
114 | .I thread | |
115 | could be found. | |
116 | .PP | |
117 | .BR pthread_setschedparam () | |
118 | may additionally fail with the following errors: | |
119 | .TP | |
120 | .B EINVAL | |
121 | .I policy | |
122 | is not a recognized policy, or | |
123 | .I param | |
124 | does not make sense for the | |
125 | .IR policy . | |
126 | .TP | |
127 | .B EPERM | |
128 | The caller does not have appropriate privileges | |
bec63ef6 | 129 | to set the specified scheduling policy and parameters. |
bec63ef6 MK |
130 | .PP |
131 | POSIX.1-2001 also documents an | |
132 | .B ENOTSUP | |
133 | ("attempt was made to set the policy or scheduling parameters | |
134 | to an unsupported value") error for | |
135 | .BR pthread_setschedparam (). | |
136 | .\" .SH VERSIONS | |
137 | .\" Available since glibc 2.0 | |
138 | .SH CONFORMING TO | |
139 | POSIX.1-2001. | |
140 | .SH NOTES | |
a1ca9644 MK |
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_setscheduler (2). | |
bec63ef6 MK |
146 | .SH EXAMPLE |
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 | ||
154 | In the following run, the main thread sets its scheduling policy to | |
155 | .BR SCHED_FIFO | |
156 | with a priority of 10, | |
157 | and initializes a thread attributes object with | |
158 | a scheduling policy attribute of | |
159 | .BR 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 | .in +4n | |
170 | .nf | |
171 | ||
172 | $ \fBsu\fP # Need privilege to set real-time scheduling policies | |
173 | Password: | |
174 | # \fB./a.out \-mf10 \-ar20 \-i e\fP | |
175 | Scheduler settings of main thread | |
176 | policy=SCHED_FIFO, priority=10 | |
177 | ||
178 | Scheduler settings in \(aqattr\(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 | .fi | |
185 | .in | |
186 | ||
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 | ||
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 | ||
197 | .in +4n | |
198 | .nf | |
199 | # \fB./a.out \-mf10 \-ar20 \-i i\fP | |
200 | Scheduler settings of main thread | |
201 | policy=SCHED_FIFO, priority=10 | |
202 | ||
203 | Scheduler settings in \(aqattr\(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 | .fi | |
210 | .in | |
211 | ||
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. | |
50b1e6a7 MK |
215 | |
216 | Note that if we had omitted the | |
217 | .IR "\-i\ i" | |
a113945f | 218 | option, the output would have been the same, since |
50b1e6a7 MK |
219 | .BR PTHREAD_INHERIT_SCHED |
220 | is the default for the inherit scheduler attribute. | |
bec63ef6 MK |
221 | .SS Program source |
222 | \& | |
223 | .nf | |
224 | /* pthreads_sched_test.c */ | |
225 | ||
226 | #include <pthread.h> | |
227 | #include <stdio.h> | |
228 | #include <stdlib.h> | |
229 | #include <unistd.h> | |
230 | #include <errno.h> | |
231 | ||
940c8ce2 MK |
232 | #define handle_error_en(en, msg) \\ |
233 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) | |
bec63ef6 MK |
234 | |
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]\\n", prog_name); | |
242 | fprintf(stderr, "Options are:\\n"); | |
243 | #define fpe(msg) fprintf(stderr, "\\t%s", msg); /* Shorter */ | |
244 | fpe("\-a<policy><prio> Set scheduling policy and priority in\\n"); | |
245 | fpe(" thread attributes object\\n"); | |
246 | fpe(" <policy> can be\\n"); | |
247 | fpe(" f SCHED_FIFO\\n"); | |
248 | fpe(" r SCHED_RR\\n"); | |
249 | fpe(" o SCHED_OTHER\\n"); | |
250 | fpe("\-A Use default thread attributes object\\n"); | |
251 | fpe("\-i {e|s} Set inherit scheduler attribute to\\n"); | |
252 | fpe(" \(aqexplicit\(aq or \(aqinherit\(aq\\n"); | |
253 | fpe("\-m<policy><prio> Set scheduling policy and priority on\\n"); | |
254 | fpe(" main thread before pthread_create() call\\n"); | |
255 | exit(EXIT_FAILURE); | |
256 | } /* usage */ | |
257 | ||
258 | static int | |
259 | get_policy(char p, int *policy) | |
260 | { | |
261 | switch (p) { | |
262 | case \(aqf\(aq: *policy = SCHED_FIFO; return 1; | |
263 | case \(aqr\(aq: *policy = SCHED_RR; return 1; | |
264 | case \(aqo\(aq: *policy = SCHED_OTHER; return 1; | |
265 | default: return 0; | |
266 | } | |
267 | } /* get_policy */ | |
268 | ||
269 | static void | |
270 | display_sched_attr(int policy, struct sched_param *param) | |
271 | { | |
272 | printf(" policy=%s, priority=%d\\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 | } /* display_sched_attr */ | |
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, ¶m); | |
287 | if (s != 0) | |
940c8ce2 | 288 | handle_error_en(s, "pthread_getschedparam"); |
bec63ef6 MK |
289 | |
290 | printf("%s\\n", msg); | |
291 | display_sched_attr(policy, ¶m); | |
292 | } /* display_thread_sched_attr */ | |
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 | } /* thread_start */ | |
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 \(aqa\(aq: attr_sched_str = optarg; break; | |
322 | case \(aqA\(aq: use_null_attrib = 1; break; | |
323 | case \(aqi\(aq: inheritsched_str = optarg; break; | |
324 | case \(aqm\(aq: main_sched_str = optarg; break; | |
325 | default: usage(argv[0], "Unrecognized option\\n"); | |
326 | } | |
327 | } | |
328 | ||
329 | if (use_null_attrib && | |
330 | (inheritsched_str != NULL || attr_sched_str != NULL)) | |
331 | usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n"); | |
332 | ||
333 | /* Optionally set scheduling attributes of main thread, | |
334 | and display the attributes */ | |
335 | ||
336 | if (main_sched_str != NULL) { | |
337 | if (!get_policy(main_sched_str[0], &policy)) | |
338 | usage(argv[0], "Bad policy for main thread (\-s)\\n"); | |
339 | param.sched_priority = strtol(&main_sched_str[1], NULL, 0); | |
340 | ||
341 | s = pthread_setschedparam(pthread_self(), policy, ¶m); | |
342 | if (s != 0) | |
940c8ce2 | 343 | handle_error_en(s, "pthread_setschedparam"); |
bec63ef6 MK |
344 | } |
345 | ||
346 | display_thread_sched_attr("Scheduler settings of main thread"); | |
347 | printf("\\n"); | |
348 | ||
349 | /* Initialize thread attributes object according to options */ | |
350 | ||
351 | attrp = NULL; | |
352 | ||
353 | if (!use_null_attrib) { | |
354 | s = pthread_attr_init(&attr); | |
355 | if (s != 0) | |
940c8ce2 | 356 | handle_error_en(s, "pthread_attr_init"); |
bec63ef6 MK |
357 | attrp = &attr; |
358 | } | |
359 | ||
360 | if (inheritsched_str != NULL) { | |
361 | if (inheritsched_str[0] == \(aqe\(aq) | |
362 | inheritsched = PTHREAD_EXPLICIT_SCHED; | |
363 | else if (inheritsched_str[0] == \(aqi\(aq) | |
364 | inheritsched = PTHREAD_INHERIT_SCHED; | |
365 | else | |
366 | usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n"); | |
367 | ||
368 | s = pthread_attr_setinheritsched(&attr, inheritsched); | |
369 | if (s != 0) | |
940c8ce2 | 370 | handle_error_en(s, "pthread_attr_setinheritsched"); |
bec63ef6 MK |
371 | } |
372 | ||
373 | if (attr_sched_str != NULL) { | |
374 | if (!get_policy(attr_sched_str[0], &policy)) | |
375 | usage(argv[0], | |
376 | "Bad policy for \(aqattr\(aq (\-a)\\n"); | |
377 | param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); | |
378 | ||
379 | s = pthread_attr_setschedpolicy(&attr, policy); | |
380 | if (s != 0) | |
940c8ce2 | 381 | handle_error_en(s, "pthread_attr_setschedpolicy"); |
bec63ef6 MK |
382 | s = pthread_attr_setschedparam(&attr, ¶m); |
383 | if (s != 0) | |
940c8ce2 | 384 | handle_error_en(s, "pthread_attr_setschedparam"); |
bec63ef6 MK |
385 | } |
386 | ||
387 | /* If we initialized a thread attributes object, display | |
388 | the scheduling attributes that were set in the object */ | |
389 | ||
390 | if (attrp != NULL) { | |
391 | s = pthread_attr_getschedparam(&attr, ¶m); | |
392 | if (s != 0) | |
940c8ce2 | 393 | handle_error_en(s, "pthread_attr_getschedparam"); |
bec63ef6 MK |
394 | s = pthread_attr_getschedpolicy(&attr, &policy); |
395 | if (s != 0) | |
940c8ce2 | 396 | handle_error_en(s, "pthread_attr_getschedpolicy"); |
bec63ef6 MK |
397 | |
398 | printf("Scheduler settings in \(aqattr\(aq\\n"); | |
399 | display_sched_attr(policy, ¶m); | |
400 | ||
401 | s = pthread_attr_getinheritsched(&attr, &inheritsched); | |
402 | printf(" inheritsched is %s\\n", | |
403 | (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : | |
404 | (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : | |
405 | "???"); | |
406 | printf("\\n"); | |
407 | } | |
408 | ||
409 | /* Create a thread that will display its scheduling attributes */ | |
410 | ||
411 | s = pthread_create(&thread, attrp, &thread_start, NULL); | |
412 | if (s != 0) | |
940c8ce2 | 413 | handle_error_en(s, "pthread_create"); |
bec63ef6 MK |
414 | |
415 | /* Destroy unneeded thread attributes object */ | |
416 | ||
417 | s = pthread_attr_destroy(&attr); | |
418 | if (s != 0) | |
940c8ce2 | 419 | handle_error_en(s, "pthread_attr_destroy"); |
bec63ef6 MK |
420 | |
421 | s = pthread_join(thread, NULL); | |
422 | if (s != 0) | |
940c8ce2 | 423 | handle_error_en(s, "pthread_join"); |
bec63ef6 MK |
424 | |
425 | exit(EXIT_SUCCESS); | |
426 | } /* main */ | |
427 | .fi | |
428 | .SH SEE ALSO | |
cb4db101 | 429 | .BR getrlimit (2), |
bec63ef6 MK |
430 | .BR sched_get_priority_min (2), |
431 | .BR sched_setscheduler (2), | |
432 | .BR pthread_attr_init (3), | |
433 | .BR pthread_attr_setinheritsched (3), | |
434 | .BR pthread_attr_setschedparam (3), | |
435 | .BR pthread_attr_setschedpolicy (3), | |
436 | .BR pthread_setschedprio (3), | |
437 | .BR pthread_create (3), | |
438 | .BR pthread_self (3), | |
439 | .BR pthreads (7) |