man3/pthread_setschedparam.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   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.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_SETSCHEDPARAM 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthread_setschedparam, pthread_getschedparam \- set/get
  29 scheduling policy and parameters of a thread
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <pthread.h>
  33 .PP
  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 *restrict " policy ,
  37 .BI "                          struct sched_param *restrict " param );
  38 .PP
  39 Compile and link with \fI\-pthread\fP.
  40 .fi
  41 .SH DESCRIPTION
  42 The
  43 .BR pthread_setschedparam ()
  44 function sets the scheduling policy and parameters of the thread
  45 .IR thread .
  46 .PP
  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
  53 .BR sched (7).
  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 .PP
  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 .PP
  64 .in +4n
  65 .EX
  66 struct sched_param {
  67     int sched_priority;     /* Scheduling priority */
  68 };
  69 .EE
  70 .in
  71 .PP
  72 As can be seen, only one scheduling parameter is supported.
  73 For details of the permitted ranges for scheduling priorities
  74 in each scheduling policy, see
  75 .BR sched (7).
  76 .PP
  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;
 106 on error, they return a nonzero error number.
 107 If
 108 .BR pthread_setschedparam ()
 109 fails, the scheduling policy and parameters of
 110 .I thread
 111 are not changed.
 112 .SH ERRORS
 113 Both of these functions can fail with the following error:
 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
 132 to set the specified scheduling policy and parameters.
 133 .PP
 134 POSIX.1 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
 141 .SH ATTRIBUTES
 142 For an explanation of the terms used in this section, see
 143 .BR attributes (7).
 144 .ad l
 145 .nh
 146 .TS
 147 allbox;
 148 lbx lb lb
 149 l l l.
 150 Interface       Attribute       Value
 151 T{
 152 .BR pthread_setschedparam (),
 153 .BR pthread_getschedparam ()
 154 T}      Thread safety   MT-Safe
 155 .TE
 156 .hy
 157 .ad
 158 .sp 1
 159 .SH CONFORMING TO
 160 POSIX.1-2001, POSIX.1-2008.
 161 .SH NOTES
 162 For a description of the permissions required to, and the effect of,
 163 changing a thread's scheduling policy and priority,
 164 and details of the permitted ranges for priorities
 165 in each scheduling policy, see
 166 .BR sched (7).
 167 .SH EXAMPLES
 168 The program below demonstrates the use of
 169 .BR pthread_setschedparam ()
 170 and
 171 .BR pthread_getschedparam (),
 172 as well as the use of a number of other scheduling-related
 173 pthreads functions.
 174 .PP
 175 In the following run, the main thread sets its scheduling policy to
 176 .BR SCHED_FIFO
 177 with a priority of 10,
 178 and initializes a thread attributes object with
 179 a scheduling policy attribute of
 180 .BR SCHED_RR
 181 and a scheduling priority attribute of 20.
 182 The program then sets (using
 183 .BR pthread_attr_setinheritsched (3))
 184 the inherit scheduler attribute of the thread attributes object to
 185 .BR PTHREAD_EXPLICIT_SCHED ,
 186 meaning that threads created using this attributes object should
 187 take their scheduling attributes from the thread attributes object.
 188 The program then creates a thread using the thread attributes object,
 189 and that thread displays its scheduling policy and priority.
 190 .PP
 191 .in +4n
 192 .EX
 193 $ \fBsu\fP      # Need privilege to set real\-time scheduling policies
 194 Password:
 195 # \fB./a.out \-mf10 \-ar20 \-i e\fP
 196 Scheduler settings of main thread
 197     policy=SCHED_FIFO, priority=10
 198
 199 Scheduler settings in \(aqattr\(aq
 200     policy=SCHED_RR, priority=20
 201     inheritsched is EXPLICIT
 202
 203 Scheduler attributes of new thread
 204     policy=SCHED_RR, priority=20
 205 .EE
 206 .in
 207 .PP
 208 In the above output, one can see that the scheduling policy and priority
 209 were taken from the values specified in the thread attributes object.
 210 .PP
 211 The next run is the same as the previous,
 212 except that the inherit scheduler attribute is set to
 213 .BR PTHREAD_INHERIT_SCHED ,
 214 meaning that threads created using the thread attributes object should
 215 ignore the scheduling attributes specified in the attributes object
 216 and instead take their scheduling attributes from the creating thread.
 217 .PP
 218 .in +4n
 219 .EX
 220 # \fB./a.out \-mf10 \-ar20 \-i i\fP
 221 Scheduler settings of main thread
 222     policy=SCHED_FIFO, priority=10
 223
 224 Scheduler settings in \(aqattr\(aq
 225     policy=SCHED_RR, priority=20
 226     inheritsched is INHERIT
 227
 228 Scheduler attributes of new thread
 229     policy=SCHED_FIFO, priority=10
 230 .EE
 231 .in
 232 .PP
 233 In the above output, one can see that the scheduling policy and priority
 234 were taken from the creating thread,
 235 rather than the thread attributes object.
 236 .PP
 237 Note that if we had omitted the
 238 .IR "\-i\ i"
 239 option, the output would have been the same, since
 240 .BR PTHREAD_INHERIT_SCHED
 241 is the default for the inherit scheduler attribute.
 242 .SS Program source
 243 \&
 244 .EX
 245 /* pthreads_sched_test.c */
 246
 247 #include <pthread.h>
 248 #include <stdio.h>
 249 #include <stdlib.h>
 250 #include <unistd.h>
 251 #include <errno.h>
 252
 253 #define handle_error_en(en, msg) \e
 254         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 255
 256 static void
 257 usage(char *prog_name, char *msg)
 258 {
 259     if (msg != NULL)
 260         fputs(msg, stderr);
 261
 262     fprintf(stderr, "Usage: %s [options]\en", prog_name);
 263     fprintf(stderr, "Options are:\en");
 264 #define fpe(msg) fprintf(stderr, "\et%s", msg);          /* Shorter */
 265     fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
 266     fpe("                 thread attributes object\en");
 267     fpe("                 <policy> can be\en");
 268     fpe("                     f  SCHED_FIFO\en");
 269     fpe("                     r  SCHED_RR\en");
 270     fpe("                     o  SCHED_OTHER\en");
 271     fpe("\-A               Use default thread attributes object\en");
 272     fpe("\-i {e|i}         Set inherit scheduler attribute to\en");
 273     fpe("                 \(aqexplicit\(aq or \(aqinherit\(aq\en");
 274     fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
 275     fpe("                 main thread before pthread_create() call\en");
 276     exit(EXIT_FAILURE);
 277 }
 278
 279 static int
 280 get_policy(char p, int *policy)
 281 {
 282     switch (p) {
 283     case \(aqf\(aq: *policy = SCHED_FIFO;     return 1;
 284     case \(aqr\(aq: *policy = SCHED_RR;       return 1;
 285     case \(aqo\(aq: *policy = SCHED_OTHER;    return 1;
 286     default:  return 0;
 287     }
 288 }
 289
 290 static void
 291 display_sched_attr(int policy, struct sched_param *param)
 292 {
 293     printf("    policy=%s, priority=%d\en",
 294             (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
 295             (policy == SCHED_RR)    ? "SCHED_RR" :
 296             (policy == SCHED_OTHER) ? "SCHED_OTHER" :
 297             "???",
 298             param\->sched_priority);
 299 }
 300
 301 static void
 302 display_thread_sched_attr(char *msg)
 303 {
 304     int policy, s;
 305     struct sched_param param;
 306
 307     s = pthread_getschedparam(pthread_self(), &policy, &param);
 308     if (s != 0)
 309         handle_error_en(s, "pthread_getschedparam");
 310
 311     printf("%s\en", msg);
 312     display_sched_attr(policy, &param);
 313 }
 314
 315 static void *
 316 thread_start(void *arg)
 317 {
 318     display_thread_sched_attr("Scheduler attributes of new thread");
 319
 320     return NULL;
 321 }
 322
 323 int
 324 main(int argc, char *argv[])
 325 {
 326     int s, opt, inheritsched, use_null_attrib, policy;
 327     pthread_t thread;
 328     pthread_attr_t attr;
 329     pthread_attr_t *attrp;
 330     char *attr_sched_str, *main_sched_str, *inheritsched_str;
 331     struct sched_param param;
 332
 333     /* Process command\-line options. */
 334
 335     use_null_attrib = 0;
 336     attr_sched_str = NULL;
 337     main_sched_str = NULL;
 338     inheritsched_str = NULL;
 339
 340     while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
 341         switch (opt) {
 342         case \(aqa\(aq: attr_sched_str = optarg;      break;
 343         case \(aqA\(aq: use_null_attrib = 1;          break;
 344         case \(aqi\(aq: inheritsched_str = optarg;    break;
 345         case \(aqm\(aq: main_sched_str = optarg;      break;
 346         default:  usage(argv[0], "Unrecognized option\en");
 347         }
 348     }
 349
 350     if (use_null_attrib &&
 351             (inheritsched_str != NULL || attr_sched_str != NULL))
 352         usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\en");
 353
 354     /* Optionally set scheduling attributes of main thread,
 355        and display the attributes. */
 356
 357     if (main_sched_str != NULL) {
 358         if (!get_policy(main_sched_str[0], &policy))
 359             usage(argv[0], "Bad policy for main thread (\-m)\en");
 360         param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
 361
 362         s = pthread_setschedparam(pthread_self(), policy, &param);
 363         if (s != 0)
 364             handle_error_en(s, "pthread_setschedparam");
 365     }
 366
 367     display_thread_sched_attr("Scheduler settings of main thread");
 368     printf("\en");
 369
 370     /* Initialize thread attributes object according to options. */
 371
 372     attrp = NULL;
 373
 374     if (!use_null_attrib) {
 375         s = pthread_attr_init(&attr);
 376         if (s != 0)
 377             handle_error_en(s, "pthread_attr_init");
 378         attrp = &attr;
 379     }
 380
 381     if (inheritsched_str != NULL) {
 382         if (inheritsched_str[0] == \(aqe\(aq)
 383             inheritsched = PTHREAD_EXPLICIT_SCHED;
 384         else if (inheritsched_str[0] == \(aqi\(aq)
 385             inheritsched = PTHREAD_INHERIT_SCHED;
 386         else
 387             usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\en");
 388
 389         s = pthread_attr_setinheritsched(&attr, inheritsched);
 390         if (s != 0)
 391             handle_error_en(s, "pthread_attr_setinheritsched");
 392     }
 393
 394     if (attr_sched_str != NULL) {
 395         if (!get_policy(attr_sched_str[0], &policy))
 396             usage(argv[0],
 397                     "Bad policy for \(aqattr\(aq (\-a)\en");
 398         param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
 399
 400         s = pthread_attr_setschedpolicy(&attr, policy);
 401         if (s != 0)
 402             handle_error_en(s, "pthread_attr_setschedpolicy");
 403         s = pthread_attr_setschedparam(&attr, &param);
 404         if (s != 0)
 405             handle_error_en(s, "pthread_attr_setschedparam");
 406     }
 407
 408     /* If we initialized a thread attributes object, display
 409        the scheduling attributes that were set in the object. */
 410
 411     if (attrp != NULL) {
 412         s = pthread_attr_getschedparam(&attr, &param);
 413         if (s != 0)
 414             handle_error_en(s, "pthread_attr_getschedparam");
 415         s = pthread_attr_getschedpolicy(&attr, &policy);
 416         if (s != 0)
 417             handle_error_en(s, "pthread_attr_getschedpolicy");
 418
 419         printf("Scheduler settings in \(aqattr\(aq\en");
 420         display_sched_attr(policy, &param);
 421
 422         s = pthread_attr_getinheritsched(&attr, &inheritsched);
 423         printf("    inheritsched is %s\en",
 424                 (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
 425                 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 426                 "???");
 427         printf("\en");
 428     }
 429
 430     /* Create a thread that will display its scheduling attributes. */
 431
 432     s = pthread_create(&thread, attrp, &thread_start, NULL);
 433     if (s != 0)
 434         handle_error_en(s, "pthread_create");
 435
 436     /* Destroy unneeded thread attributes object. */
 437
 438     if (!use_null_attrib) {
 439       s = pthread_attr_destroy(&attr);
 440       if (s != 0)
 441           handle_error_en(s, "pthread_attr_destroy");
 442     }
 443
 444     s = pthread_join(thread, NULL);
 445     if (s != 0)
 446         handle_error_en(s, "pthread_join");
 447
 448     exit(EXIT_SUCCESS);
 449 }
 450 .EE
 451 .SH SEE ALSO
 452 .ad l
 453 .nh
 454 .BR getrlimit (2),
 455 .BR sched_get_priority_min (2),
 456 .BR pthread_attr_init (3),
 457 .BR pthread_attr_setinheritsched (3),
 458 .BR pthread_attr_setschedparam (3),
 459 .BR pthread_attr_setschedpolicy (3),
 460 .BR pthread_create (3),
 461 .BR pthread_self (3),
 462 .BR pthread_setschedprio (3),
 463 .BR pthreads (7),
 464 .BR sched (7)