Remove include/bits/ipc.h.
[glibc.git] / manual / threads.texi
blob4d080d44cfbdcd863861b020e517f4113524c9c8
1 @node POSIX Threads
2 @c @node POSIX Threads, Internal Probes, Cryptographic Functions, Top
3 @chapter POSIX Threads
4 @c %MENU% POSIX Threads
5 @cindex pthreads
7 This chapter describes the @glibcadj{} POSIX Thread implementation.
9 @menu
10 * Thread-specific Data::          Support for creating and
11                                   managing thread-specific data
12 * Non-POSIX Extensions::          Additional functions to extend
13                                   POSIX Thread functionality
14 @end menu
16 @node Thread-specific Data
17 @section Thread-specific Data
19 The @glibcadj{} implements functions to allow users to create and manage
20 data specific to a thread.  Such data may be destroyed at thread exit,
21 if a destructor is provided.  The following functions are defined:
23 @comment pthread.h
24 @comment POSIX
25 @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
26 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
27 @c pthread_key_create ok
28 @c  KEY_UNUSED ok
29 @c  KEY_USABLE ok
30 Create a thread-specific data key for the calling thread, referenced by
31 @var{key}.
33 Objects declared with the C++11 @code{thread_local} keyword are destroyed
34 before thread-specific data, so they should not be used in thread-specific
35 data destructors or even as members of the thread-specific data, since the
36 latter is passed as an argument to the destructor function.
37 @end deftypefun
39 @comment pthread.h
40 @comment POSIX
41 @deftypefun int pthread_key_delete (pthread_key_t @var{key})
42 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
43 @c pthread_key_delete ok
44 @c   This uses atomic compare and exchange to increment the seq number
45 @c   after testing it's not a KEY_UNUSED seq number.
46 @c  KEY_UNUSED dup ok
47 Destroy the thread-specific data @var{key} in the calling thread.  The
48 destructor for the thread-specific data is not called during destruction, nor
49 is it called during thread exit.
50 @end deftypefun
52 @comment pthread.h
53 @comment POSIX
54 @deftypefun void *pthread_getspecific (pthread_key_t @var{key})
55 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
56 @c pthread_getspecific ok
57 Return the thread-specific data associated with @var{key} in the calling
58 thread.
59 @end deftypefun
61 @comment pthread.h
62 @comment POSIX
63 @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
64 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
65 @c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
66 @c   a level2 block may be allocated by a signal handler after
67 @c   another call already made a decision to allocate it, thus losing
68 @c   the allocated value.  the seq number is updated before the
69 @c   value, which might cause an earlier-generation value to seem
70 @c   current if setspecific is cancelled or interrupted by a signal
71 @c  KEY_UNUSED ok
72 @c  calloc dup @ascuheap @acsmem
73 Associate the thread-specific @var{value} with @var{key} in the calling thread.
74 @end deftypefun
77 @node Non-POSIX Extensions
78 @section Non-POSIX Extensions
80 In addition to implementing the POSIX API for threads, @theglibc{} provides
81 additional functions and interfaces to provide functionality not specified in
82 the standard.
84 @menu
85 * Default Thread Attributes::             Setting default attributes for
86                                           threads in a process.
87 @end menu
89 @node Default Thread Attributes
90 @subsection Setting Process-wide defaults for thread attributes
92 @Theglibc{} provides non-standard API functions to set and get the default
93 attributes used in the creation of threads in a process.
95 @comment pthread.h
96 @comment GNU
97 @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
98 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
99 @c Takes lock around read from default_pthread_attr.
100 Get the default attribute values and set @var{attr} to match.  This
101 function returns @math{0} on success and a non-zero error code on
102 failure.
103 @end deftypefun
105 @comment pthread.h
106 @comment GNU
107 @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr})
108 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
109 @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem
110 @c  check_sched_policy_attr ok
111 @c  check_sched_priority_attr ok
112 @c   sched_get_priority_min dup ok
113 @c   sched_get_priority_max dup ok
114 @c  check_cpuset_attr ok
115 @c   determine_cpumask_size ok
116 @c  check_stacksize_attr ok
117 @c  lll_lock @asulock @aculock
118 @c  free dup @ascuheap @acsmem
119 @c  realloc dup @ascuheap @acsmem
120 @c  memcpy dup ok
121 @c  lll_unlock @asulock @aculock
122 Set the default attribute values to match the values in @var{attr}.  The
123 function returns @math{0} on success and a non-zero error code on failure.
124 The following error codes are defined for this function:
126 @table @code
127 @item EINVAL
128 At least one of the values in @var{attr} does not qualify as valid for the
129 attributes or the stack address is set in the attribute.
130 @item ENOMEM
131 The system does not have sufficient memory.
132 @end table
133 @end deftypefun
135 @c FIXME these are undocumented:
136 @c pthread_atfork
137 @c pthread_attr_destroy
138 @c pthread_attr_getaffinity_np
139 @c pthread_attr_getdetachstate
140 @c pthread_attr_getguardsize
141 @c pthread_attr_getinheritsched
142 @c pthread_attr_getschedparam
143 @c pthread_attr_getschedpolicy
144 @c pthread_attr_getscope
145 @c pthread_attr_getstack
146 @c pthread_attr_getstackaddr
147 @c pthread_attr_getstacksize
148 @c pthread_attr_init
149 @c pthread_attr_setaffinity_np
150 @c pthread_attr_setdetachstate
151 @c pthread_attr_setguardsize
152 @c pthread_attr_setinheritsched
153 @c pthread_attr_setschedparam
154 @c pthread_attr_setschedpolicy
155 @c pthread_attr_setscope
156 @c pthread_attr_setstack
157 @c pthread_attr_setstackaddr
158 @c pthread_attr_setstacksize
159 @c pthread_barrierattr_destroy
160 @c pthread_barrierattr_getpshared
161 @c pthread_barrierattr_init
162 @c pthread_barrierattr_setpshared
163 @c pthread_barrier_destroy
164 @c pthread_barrier_init
165 @c pthread_barrier_wait
166 @c pthread_cancel
167 @c pthread_cleanup_push
168 @c pthread_cleanup_pop
169 @c pthread_condattr_destroy
170 @c pthread_condattr_getclock
171 @c pthread_condattr_getpshared
172 @c pthread_condattr_init
173 @c pthread_condattr_setclock
174 @c pthread_condattr_setpshared
175 @c pthread_cond_broadcast
176 @c pthread_cond_destroy
177 @c pthread_cond_init
178 @c pthread_cond_signal
179 @c pthread_cond_timedwait
180 @c pthread_cond_wait
181 @c pthread_create
182 @c pthread_detach
183 @c pthread_equal
184 @c pthread_exit
185 @c pthread_getaffinity_np
186 @c pthread_getattr_np
187 @c pthread_getconcurrency
188 @c pthread_getcpuclockid
189 @c pthread_getname_np
190 @c pthread_getschedparam
191 @c pthread_join
192 @c pthread_kill
193 @c pthread_kill_other_threads_np
194 @c pthread_mutexattr_destroy
195 @c pthread_mutexattr_getkind_np
196 @c pthread_mutexattr_getprioceiling
197 @c pthread_mutexattr_getprotocol
198 @c pthread_mutexattr_getpshared
199 @c pthread_mutexattr_getrobust
200 @c pthread_mutexattr_getrobust_np
201 @c pthread_mutexattr_gettype
202 @c pthread_mutexattr_init
203 @c pthread_mutexattr_setkind_np
204 @c pthread_mutexattr_setprioceiling
205 @c pthread_mutexattr_setprotocol
206 @c pthread_mutexattr_setpshared
207 @c pthread_mutexattr_setrobust
208 @c pthread_mutexattr_setrobust_np
209 @c pthread_mutexattr_settype
210 @c pthread_mutex_consistent
211 @c pthread_mutex_consistent_np
212 @c pthread_mutex_destroy
213 @c pthread_mutex_getprioceiling
214 @c pthread_mutex_init
215 @c pthread_mutex_lock
216 @c pthread_mutex_setprioceiling
217 @c pthread_mutex_timedlock
218 @c pthread_mutex_trylock
219 @c pthread_mutex_unlock
220 @c pthread_once
221 @c pthread_rwlockattr_destroy
222 @c pthread_rwlockattr_getkind_np
223 @c pthread_rwlockattr_getpshared
224 @c pthread_rwlockattr_init
225 @c pthread_rwlockattr_setkind_np
226 @c pthread_rwlockattr_setpshared
227 @c pthread_rwlock_destroy
228 @c pthread_rwlock_init
229 @c pthread_rwlock_rdlock
230 @c pthread_rwlock_timedrdlock
231 @c pthread_rwlock_timedwrlock
232 @c pthread_rwlock_tryrdlock
233 @c pthread_rwlock_trywrlock
234 @c pthread_rwlock_unlock
235 @c pthread_rwlock_wrlock
236 @c pthread_self
237 @c pthread_setaffinity_np
238 @c pthread_setcancelstate
239 @c pthread_setcanceltype
240 @c pthread_setconcurrency
241 @c pthread_setname_np
242 @c pthread_setschedparam
243 @c pthread_setschedprio
244 @c pthread_sigmask
245 @c pthread_sigqueue
246 @c pthread_spin_destroy
247 @c pthread_spin_init
248 @c pthread_spin_lock
249 @c pthread_spin_trylock
250 @c pthread_spin_unlock
251 @c pthread_testcancel
252 @c pthread_timedjoin_np
253 @c pthread_tryjoin_np
254 @c pthread_yield