linuxthreads/man/pthread_attr_init.man

   1 .TH PTHREAD_ATTR_INIT 3 LinuxThreads
   2
   3 .XREF pthread_attr_destroy
   4 .XREF pthread_attr_setdetachstate
   5 .XREF pthread_attr_getdetachstate
   6 .XREF pthread_attr_setschedparam
   7 .XREF pthread_attr_getschedparam
   8 .XREF pthread_attr_setschedpolicy
   9 .XREF pthread_attr_getschedpolicy
  10 .XREF pthread_attr_setinheritsched
  11 .XREF pthread_attr_getinheritsched
  12 .XREF pthread_attr_setscope
  13 .XREF pthread_attr_getscope
  14
  15 .SH NAME
  16 pthread_attr_init, pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_setscope, pthread_attr_getscope \- thread creation attributes
  17
  18 .SH SYNOPSIS
  19 #include <pthread.h>
  20
  21 int pthread_attr_init(pthread_attr_t *attr);
  22
  23 int pthread_attr_destroy(pthread_attr_t *attr);
  24
  25 int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);
  26
  27 int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate);
  28
  29 int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
  30
  31 int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);
  32
  33 int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param);
  34
  35 int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param);
  36
  37 int pthread_attr_setinheritsched(pthread_attr_t *attr, int inherit);
  38
  39 int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inherit);
  40
  41 int pthread_attr_setscope(pthread_attr_t *attr, int scope);
  42
  43 int pthread_attr_getscope(const pthread_attr_t *attr, int *scope);
  44
  45 .SH DESCRIPTION
  46
  47 Setting attributes for threads is achieved by filling a
  48 thread attribute object |attr| of type !pthread_attr_t!, then passing it as
  49 second argument to !pthread_create!(3). Passing !NULL! is equivalent to
  50 passing a thread attribute object with all attributes set to their
  51 default values.
  52
  53 !pthread_attr_init! initializes the thread attribute object |attr| and
  54 fills it with default values for the attributes. (The default values
  55 are listed below for each attribute.)
  56
  57 Each attribute |attrname| (see below for a list of all attributes) can
  58 be individually set using the function !pthread_attr_set!|attrname|
  59 and retrieved using the function !pthread_attr_get!|attrname|.
  60
  61 !pthread_attr_destroy! destroys a thread attribute object, which
  62 must not be reused until it is reinitialized. !pthread_attr_destroy!
  63 does nothing in the LinuxThreads implementation.
  64
  65 Attribute objects are consulted only when creating a new thread. The
  66 same attribute object can be used for creating several
  67 threads. Modifying an attribute object after a call to
  68 !pthread_create! does not change the attributes of the thread
  69 previously created.
  70
  71 The following thread attributes are supported:
  72
  73 .SS detachstate
  74
  75 Control whether the thread is created in the joinable state (value
  76 !PTHREAD_CREATE_JOINABLE!) or in the detached state
  77 (!PTHREAD_CREATE_DETACHED!).
  78
  79 Default value: !PTHREAD_CREATE_JOINABLE!.
  80
  81 In the joinable state, another thread can synchronize on the thread
  82 termination and recover its termination code using !pthread_join!(3),
  83 but some of the thread resources are kept allocated after the thread
  84 terminates, and reclaimed only when another thread performs
  85 !pthread_join!(3) on that thread.
  86
  87 In the detached state, the thread resources are immediately freed when
  88 it terminates, but !pthread_join!(3) cannot be used to synchronize on
  89 the thread termination.
  90
  91 A thread created in the joinable state can later be put in the
  92 detached thread using !pthread_detach!(3).
  93
  94 .SS schedpolicy
  95
  96 Select the scheduling policy for the thread: one of
  97 !SCHED_OTHER! (regular, non-realtime scheduling),
  98 !SCHED_RR! (realtime, round-robin) or
  99 !SCHED_FIFO! (realtime, first-in first-out). See
 100 !sched_setpolicy!(2) for more information on scheduling policies.
 101
 102 Default value: !SCHED_OTHER!.
 103
 104 The realtime scheduling policies !SCHED_RR! and !SCHED_FIFO! are
 105 available only to processes with superuser privileges.
 106
 107 The scheduling policy of a thread can be changed after creation with
 108 !pthread_setschedparam!(3).
 109
 110 .SS schedparam
 111
 112 Contain the scheduling parameters (essentially, the scheduling
 113 priority) for the thread. See !sched_setparam!(2) for more information
 114 on scheduling parameters.
 115
 116 Default value: priority is 0.
 117
 118 This attribute is not significant if the scheduling policy is !SCHED_OTHER!;
 119 it only matters for the realtime policies !SCHED_RR! and !SCHED_FIFO!.
 120
 121 The scheduling priority of a thread can be changed after creation with
 122 !pthread_setschedparam!(3).
 123
 124 .SS inheritsched
 125
 126 Indicate whether the scheduling policy and scheduling parameters for
 127 the newly created thread are determined by the values of the
 128 |schedpolicy| and |schedparam| attributes (value
 129 !PTHREAD_EXPLICIT_SCHED!) or are inherited from the parent thread
 130 (value !PTHREAD_INHERIT_SCHED!).
 131
 132 Default value: !PTHREAD_EXPLICIT_SCHED!.
 133
 134 .SS scope
 135
 136 Define the scheduling contention scope for the created thread.  The
 137 only value supported in the LinuxThreads implementation is
 138 !PTHREAD_SCOPE_SYSTEM!, meaning that the threads contend for CPU time
 139 with all processes running on the machine. In particular, thread
 140 priorities are interpreted relative to the priorities of all other
 141 processes on the machine. The other value specified by the standard,
 142 !PTHREAD_SCOPE_PROCESS!, means that scheduling contention occurs only
 143 between the threads of the running process: thread priorities are
 144 interpreted relative to the priorities of the other threads of the
 145 process, regardless of the priorities of other processes.
 146 !PTHREAD_SCOPE_PROCESS! is not supported in LinuxThreads.
 147
 148 Default value: !PTHREAD_SCOPE_SYSTEM!.
 149
 150 .SH "RETURN VALUE"
 151
 152 All functions return 0 on success and a non-zero error code on error.
 153 On success, the !pthread_attr_get!|attrname| functions also store the
 154 current value of the attribute |attrname| in the location pointed to
 155 by their second argument.
 156
 157 .SH ERRORS
 158
 159 The !pthread_attr_setdetachstate! function returns the following error
 160 codes on error:
 161 .RS
 162 .TP
 163 !EINVAL!
 164 the specified |detachstate| is not one of !PTHREAD_CREATE_JOINABLE! or
 165 !PTHREAD_CREATE_DETACHED!.
 166 .RE
 167
 168 The !pthread_attr_setschedparam! function returns the following error
 169 codes on error:
 170 .RS
 171 .TP
 172 !EINVAL!
 173 the priority specified in |param| is outside the range of allowed
 174 priorities for the scheduling policy currently in |attr|
 175 (1 to 99 for !SCHED_FIFO! and !SCHED_RR!; 0 for !SCHED_OTHER!).
 176 .RE
 177
 178 The !pthread_attr_setschedpolicy! function returns the following error
 179 codes on error:
 180 .RS
 181 .TP
 182 !EINVAL!
 183 the specified |policy| is not one of !SCHED_OTHER!, !SCHED_FIFO!, or
 184 !SCHED_RR!.
 185
 186 .TP
 187 !ENOTSUP!
 188 |policy| is !SCHED_FIFO! or !SCHED_RR!, and the effective user of the
 189 calling process is not super-user.
 190 .RE
 191
 192 The !pthread_attr_setinheritsched! function returns the following error
 193 codes on error:
 194 .RS
 195 .TP
 196 !EINVAL!
 197 the specified |inherit| is not one of !PTHREAD_INHERIT_SCHED! or
 198 !PTHREAD_EXPLICIT_SCHED!.
 199 .RE
 200
 201 The !pthread_attr_setscope! function returns the following error
 202 codes on error:
 203 .RS
 204 .TP
 205 !EINVAL!
 206 the specified |scope| is not one of !PTHREAD_SCOPE_SYSTEM! or
 207 !PTHREAD_SCOPE_PROCESS!.
 208
 209 .TP
 210 !ENOTSUP!
 211 the specified |scope| is !PTHREAD_SCOPE_PROCESS! (not supported).
 212 .RE
 213
 214 .SH AUTHOR
 215 Xavier Leroy <Xavier.Leroy@inria.fr>
 216
 217 .SH "SEE ALSO"
 218 !pthread_create!(3),
 219 !pthread_join!(3),
 220 !pthread_detach!(3),
 221 !pthread_setschedparam!(3).