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 *policy,
15                                 struct sched_param *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       └─────────────────────────┴───────────────┴─────────┘

CONFORMING TO

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

NOTES

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

EXAMPLES

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

SEE ALSO

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

COLOPHON

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