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