man3/pthread_attr_setinheritsched.3

   1 '\" t
   2 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH pthread_attr_setinheritsched 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 pthread_attr_setinheritsched, pthread_attr_getinheritsched \- set/get
  10 inherit-scheduler attribute in thread attributes object
  11 .SH LIBRARY
  12 POSIX threads library
  13 .RI ( libpthread ", " \-lpthread )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <pthread.h>
  17 .P
  18 .BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr ,
  19 .BI "                                 int " inheritsched );
  20 .BI "int pthread_attr_getinheritsched(const pthread_attr_t *restrict " attr ,
  21 .BI "                                 int *restrict " inheritsched );
  22 .fi
  23 .SH DESCRIPTION
  24 The
  25 .BR pthread_attr_setinheritsched ()
  26 function sets the inherit-scheduler attribute of the
  27 thread attributes object referred to by
  28 .I attr
  29 to the value specified in
  30 .IR inheritsched .
  31 The inherit-scheduler attribute determines whether a thread created using
  32 the thread attributes object
  33 .I attr
  34 will inherit its scheduling attributes from the calling thread
  35 or whether it will take them from
  36 .IR attr .
  37 .P
  38 The following scheduling attributes are affected by the
  39 inherit-scheduler attribute:
  40 scheduling policy
  41 .RB ( pthread_attr_setschedpolicy (3)),
  42 scheduling priority
  43 .RB ( pthread_attr_setschedparam (3)),
  44 and contention scope
  45 .RB ( pthread_attr_setscope (3)).
  46 .P
  47 The following values may be specified in
  48 .IR inheritsched :
  49 .TP
  50 .B PTHREAD_INHERIT_SCHED
  51 Threads that are created using
  52 .I attr
  53 inherit scheduling attributes from the creating thread;
  54 the scheduling attributes in
  55 .I attr
  56 are ignored.
  57 .TP
  58 .B PTHREAD_EXPLICIT_SCHED
  59 Threads that are created using
  60 .I attr
  61 take their scheduling attributes from the values specified
  62 by the attributes object.
  63 .\" FIXME Document the defaults for scheduler settings
  64 .P
  65 The default setting of the inherit-scheduler attribute in
  66 a newly initialized thread attributes object is
  67 .BR PTHREAD_INHERIT_SCHED .
  68 .P
  69 The
  70 .BR pthread_attr_getinheritsched ()
  71 returns the inherit-scheduler attribute of the thread attributes object
  72 .I attr
  73 in the buffer pointed to by
  74 .IR inheritsched .
  75 .SH RETURN VALUE
  76 On success, these functions return 0;
  77 on error, they return a nonzero error number.
  78 .SH ERRORS
  79 .BR pthread_attr_setinheritsched ()
  80 can fail with the following error:
  81 .TP
  82 .B EINVAL
  83 Invalid value in
  84 .IR inheritsched .
  85 .P
  86 POSIX.1 also documents an optional
  87 .B ENOTSUP
  88 error ("attempt was made to set the attribute to an unsupported value") for
  89 .BR pthread_attr_setinheritsched ().
  90 .SH ATTRIBUTES
  91 For an explanation of the terms used in this section, see
  92 .BR attributes (7).
  93 .TS
  94 allbox;
  95 lbx lb lb
  96 l l l.
  97 Interface       Attribute       Value
  98 T{
  99 .na
 100 .nh
 101 .BR pthread_attr_setinheritsched (),
 102 .BR pthread_attr_getinheritsched ()
 103 T}      Thread safety   MT-Safe
 104 .TE
 105 .SH STANDARDS
 106 POSIX.1-2008.
 107 .SH HISTORY
 108 glibc 2.0.
 109 POSIX.1-2001.
 110 .SH BUGS
 111 As at glibc 2.8, if a thread attributes object is initialized using
 112 .BR pthread_attr_init (3),
 113 then the scheduling policy of the attributes object is set to
 114 .B SCHED_OTHER
 115 and the scheduling priority is set to 0.
 116 However, if the inherit-scheduler attribute is then set to
 117 .BR PTHREAD_EXPLICIT_SCHED ,
 118 then a thread created using the attribute object
 119 wrongly inherits its scheduling attributes from the creating thread.
 120 This bug does not occur if either the scheduling policy or
 121 scheduling priority attribute is explicitly set
 122 in the thread attributes object before calling
 123 .BR pthread_create (3).
 124 .\" FIXME . Track status of the following bug:
 125 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7007
 126 .SH EXAMPLES
 127 See
 128 .BR pthread_setschedparam (3).
 129 .SH SEE ALSO
 130 .ad l
 131 .nh
 132 .BR pthread_attr_init (3),
 133 .BR pthread_attr_setschedparam (3),
 134 .BR pthread_attr_setschedpolicy (3),
 135 .BR pthread_attr_setscope (3),
 136 .BR pthread_create (3),
 137 .BR pthread_setschedparam (3),
 138 .BR pthread_setschedprio (3),
 139 .BR pthreads (7),
 140 .BR sched (7)