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