1pthread_setschedparam(3) Library Functions Manual pthread_setschedparam(3)
2
6 pthread_setschedparam, pthread_getschedparam - set/get scheduling pol‐
7 icy and parameters of a thread
8
10 POSIX threads library (libpthread, -lpthread)
11
13 #include <pthread.h>
14 int pthread_setschedparam(pthread_t thread, int policy,
16 const struct sched_param *param);
17 int pthread_getschedparam(pthread_t thread, int *restrict policy,
18 struct sched_param *restrict param);
19
21 The pthread_setschedparam() function sets the scheduling policy and pa‐
22 rameters of the thread thread.
23 policy specifies the new scheduling policy for thread. The supported
25 values for policy, and their semantics, are described in sched(7).
26 The structure pointed to by param specifies the new scheduling parame‐
28 ters for thread. Scheduling parameters are maintained in the following
29 structure:
30 struct sched_param {
32 int sched_priority; /* Scheduling priority */
33 };
34 As can be seen, only one scheduling parameter is supported. For de‐
36 tails of the permitted ranges for scheduling priorities in each sched‐
37 uling policy, see sched(7).
38 The pthread_getschedparam() function returns the scheduling policy and
40 parameters of the thread thread, in the buffers pointed to by policy
41 and param, respectively. The returned priority value is that set by
42 the most recent pthread_setschedparam(), pthread_setschedprio(3), or
43 pthread_create(3) call that affected thread. The returned priority
44 does not reflect any temporary priority adjustments as a result of
45 calls to any priority inheritance or priority ceiling functions (see,
46 for example, pthread_mutexattr_setprioceiling(3) and pthread_mutex‐
47 attr_setprotocol(3)).
48
50 On success, these functions return 0; on error, they return a nonzero
51 error number. If pthread_setschedparam() fails, the scheduling policy
52 and parameters of thread are not changed.
53
55 Both of these functions can fail with the following error:
56 ESRCH No thread with the ID thread could be found.
58 pthread_setschedparam() may additionally fail with the following er‐
60 rors:
61 EINVAL policy is not a recognized policy, or param does not make sense
63 for the policy.
64 EPERM The caller does not have appropriate privileges to set the spec‐
66 ified scheduling policy and parameters.
67 POSIX.1 also documents an ENOTSUP ("attempt was made to set the policy
69 or scheduling parameters to an unsupported value") error for
70 pthread_setschedparam().
71
73 For an explanation of the terms used in this section, see at‐
74 tributes(7).
75 ┌────────────────────────────────────────────┬───────────────┬─────────┐
77 │Interface │ Attribute │ Value │
78 ├────────────────────────────────────────────┼───────────────┼─────────┤
79 │pthread_setschedparam(), │ Thread safety │ MT-Safe │
80 │pthread_getschedparam() │ │ │
81 └────────────────────────────────────────────┴───────────────┴─────────┘
82
84 POSIX.1-2008.
85
87 glibc 2.0 POSIX.1-2001.
88
90 For a description of the permissions required to, and the effect of,
91 changing a thread's scheduling policy and priority, and details of the
92 permitted ranges for priorities in each scheduling policy, see
93 sched(7).
94
96 The program below demonstrates the use of pthread_setschedparam() and
97 pthread_getschedparam(), as well as the use of a number of other sched‐
98 uling-related pthreads functions.
99 In the following run, the main thread sets its scheduling policy to
101 SCHED_FIFO with a priority of 10, and initializes a thread attributes
102 object with a scheduling policy attribute of SCHED_RR and a scheduling
103 priority attribute of 20. The program then sets (using pthread_at‐
104 tr_setinheritsched(3)) the inherit scheduler attribute of the thread
105 attributes object to PTHREAD_EXPLICIT_SCHED, meaning that threads cre‐
106 ated using this attributes object should take their scheduling at‐
107 tributes from the thread attributes object. The program then creates a
108 thread using the thread attributes object, and that thread displays its
109 scheduling policy and priority.
110 $ su # Need privilege to set real-time scheduling policies
112 Password:
113 # ./a.out -mf10 -ar20 -i e
114 Scheduler settings of main thread
115 policy=SCHED_FIFO, priority=10
116 Scheduler settings in 'attr'
118 policy=SCHED_RR, priority=20
119 inheritsched is EXPLICIT
120 Scheduler attributes of new thread
122 policy=SCHED_RR, priority=20
123 In the above output, one can see that the scheduling policy and prior‐
125 ity were taken from the values specified in the thread attributes ob‐
126 ject.
127 The next run is the same as the previous, except that the inherit
129 scheduler attribute is set to PTHREAD_INHERIT_SCHED, meaning that
130 threads created using the thread attributes object should ignore the
131 scheduling attributes specified in the attributes object and instead
132 take their scheduling attributes from the creating thread.
133 # ./a.out -mf10 -ar20 -i i
135 Scheduler settings of main thread
136 policy=SCHED_FIFO, priority=10
137 Scheduler settings in 'attr'
139 policy=SCHED_RR, priority=20
140 inheritsched is INHERIT
141 Scheduler attributes of new thread
143 policy=SCHED_FIFO, priority=10
144 In the above output, one can see that the scheduling policy and prior‐
146 ity were taken from the creating thread, rather than the thread at‐
147 tributes object.
148 Note that if we had omitted the -i i option, the output would have been
150 the same, since PTHREAD_INHERIT_SCHED is the default for the inherit
151 scheduler attribute.
152 Program source
154 /* pthreads_sched_test.c */
156 #include <errno.h>
158 #include <pthread.h>
159 #include <stdio.h>
160 #include <stdlib.h>
161 #include <unistd.h>
162 #define handle_error_en(en, msg) \
164 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
165 static void
167 usage(char *prog_name, char *msg)
168 {
169 if (msg != NULL)
170 fputs(msg, stderr);
171 fprintf(stderr, "Usage: %s [options]\n", prog_name);
173 fprintf(stderr, "Options are:\n");
174 #define fpe(msg) fprintf(stderr, "\t%s", msg) /* Shorter */
175 fpe("-a<policy><prio> Set scheduling policy and priority in\n");
176 fpe(" thread attributes object\n");
177 fpe(" <policy> can be\n");
178 fpe(" f SCHED_FIFO\n");
179 fpe(" r SCHED_RR\n");
180 fpe(" o SCHED_OTHER\n");
181 fpe("-A Use default thread attributes object\n");
182 fpe("-i {e|i} Set inherit scheduler attribute to\n");
183 fpe(" 'explicit' or 'inherit'\n");
184 fpe("-m<policy><prio> Set scheduling policy and priority on\n");
185 fpe(" main thread before pthread_create() call\n");
186 exit(EXIT_FAILURE);
187 }
188 static int
190 get_policy(char p, int *policy)
191 {
192 switch (p) {
193 case 'f': *policy = SCHED_FIFO; return 1;
194 case 'r': *policy = SCHED_RR; return 1;
195 case 'o': *policy = SCHED_OTHER; return 1;
196 default: return 0;
197 }
198 }
199 static void
201 display_sched_attr(int policy, struct sched_param *param)
202 {
203 printf(" policy=%s, priority=%d\n",
204 (policy == SCHED_FIFO) ? "SCHED_FIFO" :
205 (policy == SCHED_RR) ? "SCHED_RR" :
206 (policy == SCHED_OTHER) ? "SCHED_OTHER" :
207 "???",
208 param->sched_priority);
209 }
210 static void
212 display_thread_sched_attr(char *msg)
213 {
214 int policy, s;
215 struct sched_param param;
216 s = pthread_getschedparam(pthread_self(), &policy, ¶m);
218 if (s != 0)
219 handle_error_en(s, "pthread_getschedparam");
220 printf("%s\n", msg);
222 display_sched_attr(policy, ¶m);
223 }
224 static void *
226 thread_start(void *arg)
227 {
228 display_thread_sched_attr("Scheduler attributes of new thread");
229 return NULL;
231 }
232 int
234 main(int argc, char *argv[])
235 {
236 int s, opt, inheritsched, use_null_attrib, policy;
237 pthread_t thread;
238 pthread_attr_t attr;
239 pthread_attr_t *attrp;
240 char *attr_sched_str, *main_sched_str, *inheritsched_str;
241 struct sched_param param;
242 /* Process command-line options. */
244 use_null_attrib = 0;
246 attr_sched_str = NULL;
247 main_sched_str = NULL;
248 inheritsched_str = NULL;
249 while ((opt = getopt(argc, argv, "a:Ai:m:")) != -1) {
251 switch (opt) {
252 case 'a': attr_sched_str = optarg; break;
253 case 'A': use_null_attrib = 1; break;
254 case 'i': inheritsched_str = optarg; break;
255 case 'm': main_sched_str = optarg; break;
256 default: usage(argv[0], "Unrecognized option\n");
257 }
258 }
259 if (use_null_attrib
261 && (inheritsched_str != NULL || attr_sched_str != NULL))
262 {
263 usage(argv[0], "Can't specify -A with -i or -a\n");
264 }
265 /* Optionally set scheduling attributes of main thread,
267 and display the attributes. */
268 if (main_sched_str != NULL) {
270 if (!get_policy(main_sched_str[0], &policy))
271 usage(argv[0], "Bad policy for main thread (-m)\n");
272 param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
273 s = pthread_setschedparam(pthread_self(), policy, ¶m);
275 if (s != 0)
276 handle_error_en(s, "pthread_setschedparam");
277 }
278 display_thread_sched_attr("Scheduler settings of main thread");
280 printf("\n");
281 /* Initialize thread attributes object according to options. */
283 attrp = NULL;
285 if (!use_null_attrib) {
287 s = pthread_attr_init(&attr);
288 if (s != 0)
289 handle_error_en(s, "pthread_attr_init");
290 attrp = &attr;
291 }
292 if (inheritsched_str != NULL) {
294 if (inheritsched_str[0] == 'e')
295 inheritsched = PTHREAD_EXPLICIT_SCHED;
296 else if (inheritsched_str[0] == 'i')
297 inheritsched = PTHREAD_INHERIT_SCHED;
298 else
299 usage(argv[0], "Value for -i must be 'e' or 'i'\n");
300 s = pthread_attr_setinheritsched(&attr, inheritsched);
302 if (s != 0)
303 handle_error_en(s, "pthread_attr_setinheritsched");
304 }
305 if (attr_sched_str != NULL) {
307 if (!get_policy(attr_sched_str[0], &policy))
308 usage(argv[0], "Bad policy for 'attr' (-a)\n");
309 param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
310 s = pthread_attr_setschedpolicy(&attr, policy);
312 if (s != 0)
313 handle_error_en(s, "pthread_attr_setschedpolicy");
314 s = pthread_attr_setschedparam(&attr, ¶m);
315 if (s != 0)
316 handle_error_en(s, "pthread_attr_setschedparam");
317 }
318 /* If we initialized a thread attributes object, display
320 the scheduling attributes that were set in the object. */
321 if (attrp != NULL) {
323 s = pthread_attr_getschedparam(&attr, ¶m);
324 if (s != 0)
325 handle_error_en(s, "pthread_attr_getschedparam");
326 s = pthread_attr_getschedpolicy(&attr, &policy);
327 if (s != 0)
328 handle_error_en(s, "pthread_attr_getschedpolicy");
329 printf("Scheduler settings in 'attr'\n");
331 display_sched_attr(policy, ¶m);
332 pthread_attr_getinheritsched(&attr, &inheritsched);
334 printf(" inheritsched is %s\n",
335 (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
336 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
337 "???");
338 printf("\n");
339 }
340 /* Create a thread that will display its scheduling attributes. */
342 s = pthread_create(&thread, attrp, &thread_start, NULL);
344 if (s != 0)
345 handle_error_en(s, "pthread_create");
346 /* Destroy unneeded thread attributes object. */
348 if (!use_null_attrib) {
350 s = pthread_attr_destroy(&attr);
351 if (s != 0)
352 handle_error_en(s, "pthread_attr_destroy");
353 }
354 s = pthread_join(thread, NULL);
356 if (s != 0)
357 handle_error_en(s, "pthread_join");
358 exit(EXIT_SUCCESS);
360 }
361
363 getrlimit(2), sched_get_priority_min(2), pthread_attr_init(3),
364 pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
365 pthread_attr_setschedpolicy(3), pthread_create(3), pthread_self(3),
366 pthread_setschedprio(3), pthreads(7), sched(7)
367Linux man-pages 6.04 2023-03-30 pthread_setschedparam(3)