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