1PTHREAD_SETSCHEDPARAM(3)   Linux Programmer's Manual  PTHREAD_SETSCHEDPARAM(3)
2
3
4

NAME

6       pthread_setschedparam,  pthread_getschedparam - set/get scheduling pol‐
7       icy and parameters of a thread
8

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_setschedparam(pthread_t thread, int policy,
13                                 const struct sched_param *param);
14       int pthread_getschedparam(pthread_t thread, int *restrict policy,
15                                 struct sched_param *restrict param);
16
17       Compile and link with -pthread.
18

DESCRIPTION

20       The pthread_setschedparam() function sets the scheduling policy and pa‐
21       rameters of the thread thread.
22
23       policy  specifies  the new scheduling policy for thread.  The supported
24       values for policy, and their semantics, are described in sched(7).
25
26       The structure pointed to by param specifies the new scheduling  parame‐
27       ters for thread.  Scheduling parameters are maintained in the following
28       structure:
29
30           struct sched_param {
31               int sched_priority;     /* Scheduling priority */
32           };
33
34       As can be seen, only one scheduling parameter is  supported.   For  de‐
35       tails  of the permitted ranges for scheduling priorities in each sched‐
36       uling policy, see sched(7).
37
38       The pthread_getschedparam() function returns the scheduling policy  and
39       parameters  of  the  thread thread, in the buffers pointed to by policy
40       and param, respectively.  The returned priority value is  that  set  by
41       the  most  recent  pthread_setschedparam(), pthread_setschedprio(3), or
42       pthread_create(3) call that affected  thread.   The  returned  priority
43       does  not  reflect  any  temporary  priority adjustments as a result of
44       calls to any priority inheritance or priority ceiling  functions  (see,
45       for  example,  pthread_mutexattr_setprioceiling(3)  and  pthread_mutex‐
46       attr_setprotocol(3)).
47

RETURN VALUE

49       On success, these functions return 0; on error, they return  a  nonzero
50       error  number.  If pthread_setschedparam() fails, the scheduling policy
51       and parameters of thread are not changed.
52

ERRORS

54       Both of these functions can fail with the following error:
55
56       ESRCH  No thread with the ID thread could be found.
57
58       pthread_setschedparam() may additionally fail with  the  following  er‐
59       rors:
60
61       EINVAL policy  is not a recognized policy, or param does not make sense
62              for the policy.
63
64       EPERM  The caller does not have appropriate privileges to set the spec‐
65              ified scheduling policy and parameters.
66
67       POSIX.1  also documents an ENOTSUP ("attempt was made to set the policy
68       or  scheduling  parameters  to  an  unsupported   value")   error   for
69       pthread_setschedparam().
70

ATTRIBUTES

72       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
73       tributes(7).
74
75       ┌────────────────────────────────────────────┬───────────────┬─────────┐
76Interface                                   Attribute     Value   
77       ├────────────────────────────────────────────┼───────────────┼─────────┤
78pthread_setschedparam(),                    │ Thread safety │ MT-Safe │
79pthread_getschedparam()                     │               │         │
80       └────────────────────────────────────────────┴───────────────┴─────────┘
81

CONFORMING TO

83       POSIX.1-2001, POSIX.1-2008.
84

NOTES

86       For  a  description  of the permissions required to, and the effect of,
87       changing a thread's scheduling policy and priority, and details of  the
88       permitted   ranges  for  priorities  in  each  scheduling  policy,  see
89       sched(7).
90

EXAMPLES

92       The program below demonstrates the use of  pthread_setschedparam()  and
93       pthread_getschedparam(), as well as the use of a number of other sched‐
94       uling-related pthreads functions.
95
96       In the following run, the main thread sets  its  scheduling  policy  to
97       SCHED_FIFO  with  a priority of 10, and initializes a thread attributes
98       object with a scheduling policy attribute of SCHED_RR and a  scheduling
99       priority  attribute  of  20.   The program then sets (using pthread_at‐
100       tr_setinheritsched(3)) the inherit scheduler attribute  of  the  thread
101       attributes  object to PTHREAD_EXPLICIT_SCHED, meaning that threads cre‐
102       ated using this attributes object  should  take  their  scheduling  at‐
103       tributes from the thread attributes object.  The program then creates a
104       thread using the thread attributes object, and that thread displays its
105       scheduling policy and priority.
106
107           $ su      # Need privilege to set real-time scheduling policies
108           Password:
109           # ./a.out -mf10 -ar20 -i e
110           Scheduler settings of main thread
111               policy=SCHED_FIFO, priority=10
112
113           Scheduler settings in 'attr'
114               policy=SCHED_RR, priority=20
115               inheritsched is EXPLICIT
116
117           Scheduler attributes of new thread
118               policy=SCHED_RR, priority=20
119
120       In  the above output, one can see that the scheduling policy and prior‐
121       ity were taken from the values specified in the thread  attributes  ob‐
122       ject.
123
124       The  next  run  is  the  same  as the previous, except that the inherit
125       scheduler attribute  is  set  to  PTHREAD_INHERIT_SCHED,  meaning  that
126       threads  created  using  the thread attributes object should ignore the
127       scheduling attributes specified in the attributes  object  and  instead
128       take their scheduling attributes from the creating thread.
129
130           # ./a.out -mf10 -ar20 -i i
131           Scheduler settings of main thread
132               policy=SCHED_FIFO, priority=10
133
134           Scheduler settings in 'attr'
135               policy=SCHED_RR, priority=20
136               inheritsched is INHERIT
137
138           Scheduler attributes of new thread
139               policy=SCHED_FIFO, priority=10
140
141       In  the above output, one can see that the scheduling policy and prior‐
142       ity were taken from the creating thread, rather  than  the  thread  at‐
143       tributes object.
144
145       Note that if we had omitted the -i i option, the output would have been
146       the same, since PTHREAD_INHERIT_SCHED is the default  for  the  inherit
147       scheduler attribute.
148
149   Program source
150
151       /* pthreads_sched_test.c */
152
153       #include <pthread.h>
154       #include <stdio.h>
155       #include <stdlib.h>
156       #include <unistd.h>
157       #include <errno.h>
158
159       #define handle_error_en(en, msg) \
160               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
161
162       static void
163       usage(char *prog_name, char *msg)
164       {
165           if (msg != NULL)
166               fputs(msg, stderr);
167
168           fprintf(stderr, "Usage: %s [options]\n", prog_name);
169           fprintf(stderr, "Options are:\n");
170       #define fpe(msg) fprintf(stderr, "\t%s", msg);          /* Shorter */
171           fpe("-a<policy><prio> Set scheduling policy and priority in\n");
172           fpe("                 thread attributes object\n");
173           fpe("                 <policy> can be\n");
174           fpe("                     f  SCHED_FIFO\n");
175           fpe("                     r  SCHED_RR\n");
176           fpe("                     o  SCHED_OTHER\n");
177           fpe("-A               Use default thread attributes object\n");
178           fpe("-i {e|i}         Set inherit scheduler attribute to\n");
179           fpe("                 'explicit' or 'inherit'\n");
180           fpe("-m<policy><prio> Set scheduling policy and priority on\n");
181           fpe("                 main thread before pthread_create() call\n");
182           exit(EXIT_FAILURE);
183       }
184
185       static int
186       get_policy(char p, int *policy)
187       {
188           switch (p) {
189           case 'f': *policy = SCHED_FIFO;     return 1;
190           case 'r': *policy = SCHED_RR;       return 1;
191           case 'o': *policy = SCHED_OTHER;    return 1;
192           default:  return 0;
193           }
194       }
195
196       static void
197       display_sched_attr(int policy, struct sched_param *param)
198       {
199           printf("    policy=%s, priority=%d\n",
200                   (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
201                   (policy == SCHED_RR)    ? "SCHED_RR" :
202                   (policy == SCHED_OTHER) ? "SCHED_OTHER" :
203                   "???",
204                   param->sched_priority);
205       }
206
207       static void
208       display_thread_sched_attr(char *msg)
209       {
210           int policy, s;
211           struct sched_param param;
212
213           s = pthread_getschedparam(pthread_self(), &policy, &param);
214           if (s != 0)
215               handle_error_en(s, "pthread_getschedparam");
216
217           printf("%s\n", msg);
218           display_sched_attr(policy, &param);
219       }
220
221       static void *
222       thread_start(void *arg)
223       {
224           display_thread_sched_attr("Scheduler attributes of new thread");
225
226           return NULL;
227       }
228
229       int
230       main(int argc, char *argv[])
231       {
232           int s, opt, inheritsched, use_null_attrib, policy;
233           pthread_t thread;
234           pthread_attr_t attr;
235           pthread_attr_t *attrp;
236           char *attr_sched_str, *main_sched_str, *inheritsched_str;
237           struct sched_param param;
238
239           /* Process command-line options. */
240
241           use_null_attrib = 0;
242           attr_sched_str = NULL;
243           main_sched_str = NULL;
244           inheritsched_str = NULL;
245
246           while ((opt = getopt(argc, argv, "a:Ai:m:")) != -1) {
247               switch (opt) {
248               case 'a': attr_sched_str = optarg;      break;
249               case 'A': use_null_attrib = 1;          break;
250               case 'i': inheritsched_str = optarg;    break;
251               case 'm': main_sched_str = optarg;      break;
252               default:  usage(argv[0], "Unrecognized option\n");
253               }
254           }
255
256           if (use_null_attrib &&
257                   (inheritsched_str != NULL || attr_sched_str != NULL))
258               usage(argv[0], "Can't specify -A with -i or -a\n");
259
260           /* Optionally set scheduling attributes of main thread,
261              and display the attributes. */
262
263           if (main_sched_str != NULL) {
264               if (!get_policy(main_sched_str[0], &policy))
265                   usage(argv[0], "Bad policy for main thread (-m)\n");
266               param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
267
268               s = pthread_setschedparam(pthread_self(), policy, &param);
269               if (s != 0)
270                   handle_error_en(s, "pthread_setschedparam");
271           }
272
273           display_thread_sched_attr("Scheduler settings of main thread");
274           printf("\n");
275
276           /* Initialize thread attributes object according to options. */
277
278           attrp = NULL;
279
280           if (!use_null_attrib) {
281               s = pthread_attr_init(&attr);
282               if (s != 0)
283                   handle_error_en(s, "pthread_attr_init");
284               attrp = &attr;
285           }
286
287           if (inheritsched_str != NULL) {
288               if (inheritsched_str[0] == 'e')
289                   inheritsched = PTHREAD_EXPLICIT_SCHED;
290               else if (inheritsched_str[0] == 'i')
291                   inheritsched = PTHREAD_INHERIT_SCHED;
292               else
293                   usage(argv[0], "Value for -i must be 'e' or 'i'\n");
294
295               s = pthread_attr_setinheritsched(&attr, inheritsched);
296               if (s != 0)
297                   handle_error_en(s, "pthread_attr_setinheritsched");
298           }
299
300           if (attr_sched_str != NULL) {
301               if (!get_policy(attr_sched_str[0], &policy))
302                   usage(argv[0],
303                           "Bad policy for 'attr' (-a)\n");
304               param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
305
306               s = pthread_attr_setschedpolicy(&attr, policy);
307               if (s != 0)
308                   handle_error_en(s, "pthread_attr_setschedpolicy");
309               s = pthread_attr_setschedparam(&attr, &param);
310               if (s != 0)
311                   handle_error_en(s, "pthread_attr_setschedparam");
312           }
313
314           /* If we initialized a thread attributes object, display
315              the scheduling attributes that were set in the object. */
316
317           if (attrp != NULL) {
318               s = pthread_attr_getschedparam(&attr, &param);
319               if (s != 0)
320                   handle_error_en(s, "pthread_attr_getschedparam");
321               s = pthread_attr_getschedpolicy(&attr, &policy);
322               if (s != 0)
323                   handle_error_en(s, "pthread_attr_getschedpolicy");
324
325               printf("Scheduler settings in 'attr'\n");
326               display_sched_attr(policy, &param);
327
328               s = pthread_attr_getinheritsched(&attr, &inheritsched);
329               printf("    inheritsched is %s\n",
330                       (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
331                       (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
332                       "???");
333               printf("\n");
334           }
335
336           /* Create a thread that will display its scheduling attributes. */
337
338           s = pthread_create(&thread, attrp, &thread_start, NULL);
339           if (s != 0)
340               handle_error_en(s, "pthread_create");
341
342           /* Destroy unneeded thread attributes object. */
343
344           if (!use_null_attrib) {
345             s = pthread_attr_destroy(&attr);
346             if (s != 0)
347                 handle_error_en(s, "pthread_attr_destroy");
348           }
349
350           s = pthread_join(thread, NULL);
351           if (s != 0)
352               handle_error_en(s, "pthread_join");
353
354           exit(EXIT_SUCCESS);
355       }
356

SEE ALSO

358       getrlimit(2), sched_get_priority_min(2), pthread_attr_init(3),
359       pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
360       pthread_attr_setschedpolicy(3), pthread_create(3), pthread_self(3),
361       pthread_setschedprio(3), pthreads(7), sched(7)
362

COLOPHON

364       This page is part of release 5.12 of the Linux man-pages project.  A
365       description of the project, information about reporting bugs, and the
366       latest version of this page, can be found at
367       https://www.kernel.org/doc/man-pages/.
368
369
370
371Linux                             2021-03-22          PTHREAD_SETSCHEDPARAM(3)
Impressum