original/man3/pthread_setschedparam.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH PTHREAD_SETSCHEDPARAM 3 2008-11-17 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_setschedparam, pthread_getschedparam \- set/get
  27 scheduling policy and parameters of a thread
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <pthread.h>
  31
  32 .BI "pthread_setschedparam(pthread_t " thread ", int " policy ,
  33 .BI "                      const struct sched_param *" param );
  34 .BI "pthread_getschedparam(pthread_t " thread ", int *" policy ,
  35 .BI "                      struct sched_param *" param );
  36 .sp
  37 Compile and link with \fI\-pthread\fP.
  38 .SH DESCRIPTION
  39 The
  40 .BR pthread_setschedparam ()
  41 function sets the scheduling policy and parameters of the thread
  42 .IR thread .
  43
  44 .I policy
  45 specifies the new scheduling policy for
  46 .IR thread .
  47 The supported values for
  48 .IR policy ,
  49 and their semantics, are described in
  50 .BR sched_setscheduler (2).
  51 .\" FIXME . pthread_setschedparam() places no restriction on the policy,
  52 .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
  53 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
  54
  55 The structure pointed to by
  56 .I param
  57 specifies the new scheduling parameters for
  58 .IR thread .
  59 Scheduling parameters are maintained in the following structure:
  60
  61 .in +4n
  62 .nf
  63 struct sched_param {
  64     int sched_priority;     /* Scheduling priority */
  65 };
  66 .fi
  67 .in
  68
  69 As can be seen, only one scheduling parameter is supported.
  70 For details of the permitted ranges for scheduling priorities
  71 in each scheduling policy, see
  72 .BR sched_setscheduler (2).
  73
  74 The
  75 .BR pthread_getschedparam ()
  76 function returns the scheduling policy and parameters of the thread
  77 .IR thread ,
  78 in the buffers pointed to by
  79 .I policy
  80 and
  81 .IR param ,
  82 respectively.
  83 The returned priority value is that set by the most recent
  84 .BR pthread_setschedparam (),
  85 .BR pthread_setschedprio (3),
  86 or
  87 .BR pthread_create (3)
  88 call that affected
  89 .IR thread .
  90 The returned priority does not reflect any temporary priority adjustments
  91 as a result of calls to any priority inheritance or
  92 priority ceiling functions (see, for example,
  93 .BR pthread_mutexattr_setprioceiling (3)
  94 and
  95 .BR pthread_mutexattr_setprotocol (3)).
  96 .\" FIXME . nptl/pthread_setschedparam.c has the following
  97 .\"   /* If the thread should have higher priority because of some
  98 .\"      PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
  99 .\" Eventually (perhaps after writing the mutexattr pages), we
 100 .\" may want to add something on the topic to this page.
 101 .SH RETURN VALUE
 102 On success, these functions return 0;
 103 on error, they return a nonzero error number.
 104 If
 105 .BR pthread_setschedparam ()
 106 fails, the scheduling policy and parameters of
 107 .I thread
 108 are not changed.
 109 .SH ERRORS
 110 Both of these functions can fail with the following error:
 111 .TP
 112 .B ESRCH
 113 No thread with the ID
 114 .I thread
 115 could be found.
 116 .PP
 117 .BR pthread_setschedparam ()
 118 may additionally fail with the following errors:
 119 .TP
 120 .B EINVAL
 121 .I policy
 122 is not a recognized policy, or
 123 .I param
 124 does not make sense for the
 125 .IR policy .
 126 .TP
 127 .B EPERM
 128 The caller does not have appropriate privileges
 129 to set the specified scheduling policy and parameters.
 130 .PP
 131 POSIX.1-2001 also documents an
 132 .B ENOTSUP
 133 ("attempt was made to set the policy or scheduling parameters
 134 to an unsupported value") error for
 135 .BR pthread_setschedparam ().
 136 .\" .SH VERSIONS
 137 .\" Available since glibc 2.0
 138 .SH CONFORMING TO
 139 POSIX.1-2001.
 140 .SH NOTES
 141 For a description of the permissions required to, and the effect of,
 142 changing a thread's scheduling policy and priority,
 143 and details of the permitted ranges for priorities
 144 in each scheduling policy, see
 145 .BR sched_setscheduler (2).
 146 .SH EXAMPLE
 147 The program below demonstrates the use of
 148 .BR pthread_setschedparam ()
 149 and
 150 .BR pthread_getschedparam (),
 151 as well as the use of a number of other scheduling-related
 152 pthreads functions.
 153
 154 In the following run, the main thread sets its scheduling policy to
 155 .BR SCHED_FIFO
 156 with a priority of 10,
 157 and initializes a thread attributes object with
 158 a scheduling policy attribute of
 159 .BR SCHED_RR
 160 and a scheduling priority attribute of 20.
 161 The program then sets (using
 162 .BR pthread_attr_setinheritsched (3))
 163 the inherit scheduler attribute of the thread attributes object to
 164 .BR PTHREAD_EXPLICIT_SCHED ,
 165 meaning that threads created using this attributes object should
 166 take their scheduling attributes from the thread attributes object.
 167 The program then creates a thread using the thread attributes object,
 168 and that thread displays its scheduling policy and priority.
 169 .in +4n
 170 .nf
 171
 172 $ \fBsu\fP      # Need privilege to set real-time scheduling policies
 173 Password:
 174 # \fB./a.out \-mf10 \-ar20 \-i e\fP
 175 Scheduler settings of main thread
 176     policy=SCHED_FIFO, priority=10
 177
 178 Scheduler settings in \(aqattr\(aq
 179     policy=SCHED_RR, priority=20
 180     inheritsched is EXPLICIT
 181
 182 Scheduler attributes of new thread
 183     policy=SCHED_RR, priority=20
 184 .fi
 185 .in
 186
 187 In the above output, one can see that the scheduling policy and priority
 188 were taken from the values specified in the thread attributes object.
 189
 190 The next run is the same as the previous,
 191 except that the inherit scheduler attribute is set to
 192 .BR PTHREAD_INHERIT_SCHED ,
 193 meaning that threads created using the thread attributes object should
 194 ignore the scheduling attributes specified in the attributes object
 195 and instead take their scheduling attributes from the creating thread.
 196
 197 .in +4n
 198 .nf
 199 # \fB./a.out \-mf10 \-ar20 \-i i\fP
 200 Scheduler settings of main thread
 201     policy=SCHED_FIFO, priority=10
 202
 203 Scheduler settings in \(aqattr\(aq
 204     policy=SCHED_RR, priority=20
 205     inheritsched is INHERIT
 206
 207 Scheduler attributes of new thread
 208     policy=SCHED_FIFO, priority=10
 209 .fi
 210 .in
 211
 212 In the above output, one can see that the scheduling policy and priority
 213 were taken from the creating thread,
 214 rather than the thread attributes object.
 215
 216 Note that if we had omitted the
 217 .IR "\-i\ i"
 218 option, the output would have been the same, since
 219 .BR PTHREAD_INHERIT_SCHED
 220 is the default for the inherit scheduler attribute.
 221 .SS Program source
 222 \&
 223 .nf
 224 /* pthreads_sched_test.c */
 225
 226 #include <pthread.h>
 227 #include <stdio.h>
 228 #include <stdlib.h>
 229 #include <unistd.h>
 230 #include <errno.h>
 231
 232 #define handle_error_en(en, msg) \\
 233         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 234
 235 static void
 236 usage(char *prog_name, char *msg)
 237 {
 238     if (msg != NULL)
 239         fputs(msg, stderr);
 240
 241     fprintf(stderr, "Usage: %s [options]\\n", prog_name);
 242     fprintf(stderr, "Options are:\\n");
 243 #define fpe(msg) fprintf(stderr, "\\t%s", msg);          /* Shorter */
 244     fpe("\-a<policy><prio> Set scheduling policy and priority in\\n");
 245     fpe("                 thread attributes object\\n");
 246     fpe("                 <policy> can be\\n");
 247     fpe("                     f  SCHED_FIFO\\n");
 248     fpe("                     r  SCHED_RR\\n");
 249     fpe("                     o  SCHED_OTHER\\n");
 250     fpe("\-A               Use default thread attributes object\\n");
 251     fpe("\-i {e|s}         Set inherit scheduler attribute to\\n");
 252     fpe("                 \(aqexplicit\(aq or \(aqinherit\(aq\\n");
 253     fpe("\-m<policy><prio> Set scheduling policy and priority on\\n");
 254     fpe("                 main thread before pthread_create() call\\n");
 255     exit(EXIT_FAILURE);
 256 }
 257
 258 static int
 259 get_policy(char p, int *policy)
 260 {
 261     switch (p) {
 262     case \(aqf\(aq: *policy = SCHED_FIFO;     return 1;
 263     case \(aqr\(aq: *policy = SCHED_RR;       return 1;
 264     case \(aqo\(aq: *policy = SCHED_OTHER;    return 1;
 265     default:  return 0;
 266     }
 267 }
 268
 269 static void
 270 display_sched_attr(int policy, struct sched_param *param)
 271 {
 272     printf("    policy=%s, priority=%d\\n",
 273             (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
 274             (policy == SCHED_RR)    ? "SCHED_RR" :
 275             (policy == SCHED_OTHER) ? "SCHED_OTHER" :
 276             "???",
 277             param\->sched_priority);
 278 }
 279
 280 static void
 281 display_thread_sched_attr(char *msg)
 282 {
 283     int policy, s;
 284     struct sched_param param;
 285
 286     s = pthread_getschedparam(pthread_self(), &policy, &param);
 287     if (s != 0)
 288         handle_error_en(s, "pthread_getschedparam");
 289
 290     printf("%s\\n", msg);
 291     display_sched_attr(policy, &param);
 292 }
 293
 294 static void *
 295 thread_start(void *arg)
 296 {
 297     display_thread_sched_attr("Scheduler attributes of new thread");
 298
 299     return NULL;
 300 }
 301
 302 int
 303 main(int argc, char *argv[])
 304 {
 305     int s, opt, inheritsched, use_null_attrib, policy;
 306     pthread_t thread;
 307     pthread_attr_t attr;
 308     pthread_attr_t *attrp;
 309     char *attr_sched_str, *main_sched_str, *inheritsched_str;
 310     struct sched_param param;
 311
 312     /* Process command\-line options */
 313
 314     use_null_attrib = 0;
 315     attr_sched_str = NULL;
 316     main_sched_str = NULL;
 317     inheritsched_str = NULL;
 318
 319     while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
 320         switch (opt) {
 321         case \(aqa\(aq: attr_sched_str = optarg;      break;
 322         case \(aqA\(aq: use_null_attrib = 1;          break;
 323         case \(aqi\(aq: inheritsched_str = optarg;    break;
 324         case \(aqm\(aq: main_sched_str = optarg;      break;
 325         default:  usage(argv[0], "Unrecognized option\\n");
 326         }
 327     }
 328
 329     if (use_null_attrib &&
 330             (inheritsched_str != NULL || attr_sched_str != NULL))
 331         usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n");
 332
 333     /* Optionally set scheduling attributes of main thread,
 334        and display the attributes */
 335
 336     if (main_sched_str != NULL) {
 337         if (!get_policy(main_sched_str[0], &policy))
 338             usage(argv[0], "Bad policy for main thread (\-s)\\n");
 339         param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
 340
 341         s = pthread_setschedparam(pthread_self(), policy, &param);
 342         if (s != 0)
 343             handle_error_en(s, "pthread_setschedparam");
 344     }
 345
 346     display_thread_sched_attr("Scheduler settings of main thread");
 347     printf("\\n");
 348
 349     /* Initialize thread attributes object according to options */
 350
 351     attrp = NULL;
 352
 353     if (!use_null_attrib) {
 354         s = pthread_attr_init(&attr);
 355         if (s != 0)
 356             handle_error_en(s, "pthread_attr_init");
 357         attrp = &attr;
 358     }
 359
 360     if (inheritsched_str != NULL) {
 361         if (inheritsched_str[0] == \(aqe\(aq)
 362             inheritsched = PTHREAD_EXPLICIT_SCHED;
 363         else if (inheritsched_str[0] == \(aqi\(aq)
 364             inheritsched = PTHREAD_INHERIT_SCHED;
 365         else
 366             usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n");
 367
 368         s = pthread_attr_setinheritsched(&attr, inheritsched);
 369         if (s != 0)
 370             handle_error_en(s, "pthread_attr_setinheritsched");
 371     }
 372
 373     if (attr_sched_str != NULL) {
 374         if (!get_policy(attr_sched_str[0], &policy))
 375             usage(argv[0],
 376                     "Bad policy for \(aqattr\(aq (\-a)\\n");
 377         param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
 378
 379         s = pthread_attr_setschedpolicy(&attr, policy);
 380         if (s != 0)
 381             handle_error_en(s, "pthread_attr_setschedpolicy");
 382         s = pthread_attr_setschedparam(&attr, &param);
 383         if (s != 0)
 384             handle_error_en(s, "pthread_attr_setschedparam");
 385     }
 386
 387     /* If we initialized a thread attributes object, display
 388        the scheduling attributes that were set in the object */
 389
 390     if (attrp != NULL) {
 391         s = pthread_attr_getschedparam(&attr, &param);
 392         if (s != 0)
 393             handle_error_en(s, "pthread_attr_getschedparam");
 394         s = pthread_attr_getschedpolicy(&attr, &policy);
 395         if (s != 0)
 396             handle_error_en(s, "pthread_attr_getschedpolicy");
 397
 398         printf("Scheduler settings in \(aqattr\(aq\\n");
 399         display_sched_attr(policy, &param);
 400
 401         s = pthread_attr_getinheritsched(&attr, &inheritsched);
 402         printf("    inheritsched is %s\\n",
 403                 (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
 404                 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 405                 "???");
 406         printf("\\n");
 407     }
 408
 409     /* Create a thread that will display its scheduling attributes */
 410
 411     s = pthread_create(&thread, attrp, &thread_start, NULL);
 412     if (s != 0)
 413         handle_error_en(s, "pthread_create");
 414
 415     /* Destroy unneeded thread attributes object */
 416
 417     s = pthread_attr_destroy(&attr);
 418     if (s != 0)
 419         handle_error_en(s, "pthread_attr_destroy");
 420
 421     s = pthread_join(thread, NULL);
 422     if (s != 0)
 423         handle_error_en(s, "pthread_join");
 424
 425     exit(EXIT_SUCCESS);
 426 }
 427 .fi
 428 .SH SEE ALSO
 429 .BR getrlimit (2),
 430 .BR sched_get_priority_min (2),
 431 .BR sched_setscheduler (2),
 432 .BR pthread_attr_init (3),
 433 .BR pthread_attr_setinheritsched (3),
 434 .BR pthread_attr_setschedparam (3),
 435 .BR pthread_attr_setschedpolicy (3),
 436 .BR pthread_create (3),
 437 .BR pthread_self (3),
 438 .BR pthread_setschedprio (3),
 439 .BR pthreads (7)