Document pthread_mutex_unlock.
[kopensolaris-gnu/glibc.git] / linuxthreads / linuxthreads.texi
1 @node POSIX Threads
2 @c @node POSIX Threads, , Top, Top
3 @chapter POSIX Threads
4 @c %MENU% The standard threads library
5
6 @c This chapter needs more work bigtime. -zw
7
8 This chapter describes the pthreads (POSIX threads) library.  This
9 library provides support functions for multithreaded programs: thread
10 primitives, synchronization objects, and so forth.  It also implements
11 POSIX 1003.1b semaphores (not to be confused with System V semaphores).
12
13 The threads operations (@samp{pthread_*}) do not use @var{errno}.
14 Instead they return an error code directly.  The semaphore operations do
15 use @var{errno}.
16
17 @menu
18 * Basic Thread Operations::     Creating, terminating, and waiting for threads.
19 * Thread Attributes::           Tuning thread scheduling.
20 * Cancellation::                Stopping a thread before it's done.
21 * Cleanup Handlers::            Deallocating resources when a thread is
22                                   cancelled.
23 * Mutexes::                     One way to synchronize threads.
24 * Condition Variables::         Another way.
25 * POSIX Semaphores::            And a third way.
26 * Thread-Specific Data::        Variables with different values in
27                                   different threads.
28 * Threads and Signal Handling:: Why you should avoid mixing the two, and
29                                   how to do it if you must.
30 * Threads and Fork::            Interactions between threads and the
31                                   @code{fork} function.
32 * Streams and Fork::            Interactions between stdio streams and
33                                   @code{fork}.
34 * Miscellaneous Thread Functions:: A grab bag of utility routines.
35 @end menu
36
37 @node Basic Thread Operations
38 @section Basic Thread Operations
39
40 These functions are the thread equivalents of @code{fork}, @code{exit},
41 and @code{wait}.
42
43 @comment pthread.h
44 @comment POSIX
45 @deftypefun int pthread_create (pthread_t * @var{thread}, pthread_attr_t * @var{attr}, void * (*@var{start_routine})(void *), void * @var{arg})
46 @code{pthread_create} creates a new thread of control that executes
47 concurrently with the calling thread. The new thread calls the
48 function @var{start_routine}, passing it @var{arg} as first argument. The
49 new thread terminates either explicitly, by calling @code{pthread_exit},
50 or implicitly, by returning from the @var{start_routine} function. The
51 latter case is equivalent to calling @code{pthread_exit} with the result
52 returned by @var{start_routine} as exit code.
53
54 The @var{attr} argument specifies thread attributes to be applied to the
55 new thread. @xref{Thread Attributes}, for details. The @var{attr}
56 argument can also be @code{NULL}, in which case default attributes are
57 used: the created thread is joinable (not detached) and has an ordinary
58 (not realtime) scheduling policy.
59
60 On success, the identifier of the newly created thread is stored in the
61 location pointed by the @var{thread} argument, and a 0 is returned. On
62 error, a non-zero error code is returned.
63
64 This function may return the following errors:
65 @table @code
66 @item EAGAIN
67 Not enough system resources to create a process for the new thread,
68 or more than @code{PTHREAD_THREADS_MAX} threads are already active.
69 @end table
70 @end deftypefun
71
72 @comment pthread.h
73 @comment POSIX
74 @deftypefun void pthread_exit (void *@var{retval})
75 @code{pthread_exit} terminates the execution of the calling thread.  All
76 cleanup handlers (@pxref{Cleanup Handlers}) that have been set for the
77 calling thread with @code{pthread_cleanup_push} are executed in reverse
78 order (the most recently pushed handler is executed first). Finalization
79 functions for thread-specific data are then called for all keys that
80 have non-@code{NULL} values associated with them in the calling thread
81 (@pxref{Thread-Specific Data}).  Finally, execution of the calling
82 thread is stopped.
83
84 The @var{retval} argument is the return value of the thread. It can be
85 retrieved from another thread using @code{pthread_join}.
86
87 The @code{pthread_exit} function never returns.
88 @end deftypefun
89
90 @comment pthread.h
91 @comment POSIX
92 @deftypefun int pthread_cancel (pthread_t @var{thread})
93
94 @code{pthread_cancel} sends a cancellation request to the thread denoted
95 by the @var{thread} argument.  If there is no such thread,
96 @code{pthread_cancel} fails and returns @code{ESRCH}.  Otherwise it
97 returns 0. @xref{Cancellation}, for details.
98 @end deftypefun
99
100 @comment pthread.h
101 @comment POSIX
102 @deftypefun int pthread_join (pthread_t @var{th}, void **thread_@var{return})
103 @code{pthread_join} suspends the execution of the calling thread until
104 the thread identified by @var{th} terminates, either by calling
105 @code{pthread_exit} or by being cancelled.
106
107 If @var{thread_return} is not @code{NULL}, the return value of @var{th}
108 is stored in the location pointed to by @var{thread_return}.  The return
109 value of @var{th} is either the argument it gave to @code{pthread_exit},
110 or @code{PTHREAD_CANCELED} if @var{th} was cancelled.
111
112 The joined thread @code{th} must be in the joinable state: it must not
113 have been detached using @code{pthread_detach} or the
114 @code{PTHREAD_CREATE_DETACHED} attribute to @code{pthread_create}.
115
116 When a joinable thread terminates, its memory resources (thread
117 descriptor and stack) are not deallocated until another thread performs
118 @code{pthread_join} on it. Therefore, @code{pthread_join} must be called
119 once for each joinable thread created to avoid memory leaks.
120
121 At most one thread can wait for the termination of a given
122 thread. Calling @code{pthread_join} on a thread @var{th} on which
123 another thread is already waiting for termination returns an error.
124
125 @code{pthread_join} is a cancellation point. If a thread is canceled
126 while suspended in @code{pthread_join}, the thread execution resumes
127 immediately and the cancellation is executed without waiting for the
128 @var{th} thread to terminate. If cancellation occurs during
129 @code{pthread_join}, the @var{th} thread remains not joined.
130
131 On success, the return value of @var{th} is stored in the location
132 pointed to by @var{thread_return}, and 0 is returned. On error, one of
133 the following values is returned:
134 @table @code
135 @item ESRCH
136 No thread could be found corresponding to that specified by @var{th}.
137 @item EINVAL
138 The @var{th} thread has been detached, or another thread is already
139 waiting on termination of @var{th}.
140 @item EDEADLK
141 The @var{th} argument refers to the calling thread.
142 @end table
143 @end deftypefun
144
145 @node Thread Attributes
146 @section Thread Attributes
147
148 @comment pthread.h
149 @comment POSIX
150
151 Threads have a number of attributes that may be set at creation time.
152 This is done by filling a thread attribute object @var{attr} of type
153 @code{pthread_attr_t}, then passing it as second argument to
154 @code{pthread_create}. Passing @code{NULL} is equivalent to passing a
155 thread attribute object with all attributes set to their default values.
156
157 Attribute objects are consulted only when creating a new thread.  The
158 same attribute object can be used for creating several threads.
159 Modifying an attribute object after a call to @code{pthread_create} does
160 not change the attributes of the thread previously created.
161
162 @comment pthread.h
163 @comment POSIX
164 @deftypefun int pthread_attr_init (pthread_attr_t *@var{attr})
165 @code{pthread_attr_init} initializes the thread attribute object
166 @var{attr} and fills it with default values for the attributes. (The
167 default values are listed below for each attribute.)
168
169 Each attribute @var{attrname} (see below for a list of all attributes)
170 can be individually set using the function
171 @code{pthread_attr_set@var{attrname}} and retrieved using the function
172 @code{pthread_attr_get@var{attrname}}.
173 @end deftypefun
174
175 @comment pthread.h
176 @comment POSIX
177 @deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr})
178 @code{pthread_attr_destroy} destroys the attribute object pointed to by
179 @var{attr} releasing any resources associated with it.  @var{attr} is
180 left in an undefined state, and you must not use it again in a call to
181 any pthreads function until it has been reinitialized.
182 @end deftypefun
183
184 @findex pthread_attr_setinheritsched
185 @findex pthread_attr_setschedparam
186 @findex pthread_attr_setschedpolicy
187 @findex pthread_attr_setscope
188 @comment pthread.h
189 @comment POSIX
190 @deftypefun int pthread_attr_set@var{attr} (pthread_attr_t *@var{obj}, int @var{value})
191 Set attribute @var{attr} to @var{value} in the attribute object pointed
192 to by @var{obj}.  See below for a list of possible attributes and the
193 values they can take.
194
195 On success, these functions return 0.  If @var{value} is not meaningful
196 for the @var{attr} being modified, they will return the error code
197 @code{EINVAL}.  Some of the functions have other failure modes; see
198 below.
199 @end deftypefun
200
201 @findex pthread_attr_getinheritsched
202 @findex pthread_attr_getschedparam
203 @findex pthread_attr_getschedpolicy
204 @findex pthread_attr_getscope
205 @comment pthread.h
206 @comment POSIX
207 @deftypefun int pthread_attr_get@var{attr} (const pthread_attr_t *@var{obj}, int *@var{value})
208 Store the current setting of @var{attr} in @var{obj} into the variable
209 pointed to by @var{value}.
210
211 These functions always return 0.
212 @end deftypefun
213
214 The following thread attributes are supported:
215 @table @samp
216 @item detachstate
217 Choose whether the thread is created in the joinable state (value
218 @code{PTHREAD_CREATE_JOINABLE}) or in the detached state
219 (@code{PTHREAD_CREATE_DETACHED}).  The default is
220 @code{PTHREAD_CREATE_JOINABLE}.
221
222 In the joinable state, another thread can synchronize on the thread
223 termination and recover its termination code using @code{pthread_join},
224 but some of the thread resources are kept allocated after the thread
225 terminates, and reclaimed only when another thread performs
226 @code{pthread_join} on that thread.
227
228 In the detached state, the thread resources are immediately freed when
229 it terminates, but @code{pthread_join} cannot be used to synchronize on
230 the thread termination.
231
232 A thread created in the joinable state can later be put in the detached
233 thread using @code{pthread_detach}.
234
235 @item schedpolicy
236 Select the scheduling policy for the thread: one of @code{SCHED_OTHER}
237 (regular, non-realtime scheduling), @code{SCHED_RR} (realtime,
238 round-robin) or @code{SCHED_FIFO} (realtime, first-in first-out).
239 The default is @code{SCHED_OTHER}.
240 @c Not doc'd in our manual: FIXME.
241 @c See @code{sched_setpolicy} for more information on scheduling policies.
242
243 The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}
244 are available only to processes with superuser privileges.
245 @code{pthread_attr_setschedparam} will fail and return @code{ENOTSUP} if
246 you try to set a realtime policy when you are unprivileged.
247
248 The scheduling policy of a thread can be changed after creation with
249 @code{pthread_setschedparam}.
250
251 @item schedparam
252 Change the scheduling parameter (the scheduling priority)
253 for the thread.  The default is 0.
254
255 This attribute is not significant if the scheduling policy is
256 @code{SCHED_OTHER}; it only matters for the realtime policies
257 @code{SCHED_RR} and @code{SCHED_FIFO}.
258
259 The scheduling priority of a thread can be changed after creation with
260 @code{pthread_setschedparam}.
261
262 @item inheritsched
263 Choose whether the scheduling policy and scheduling parameter for the
264 newly created thread are determined by the values of the
265 @var{schedpolicy} and @var{schedparam} attributes (value
266 @code{PTHREAD_EXPLICIT_SCHED}) or are inherited from the parent thread
267 (value @code{PTHREAD_INHERIT_SCHED}).  The default is
268 @code{PTHREAD_EXPLICIT_SCHED}.
269
270 @item scope
271 Choose the scheduling contention scope for the created thread.  The
272 default is @code{PTHREAD_SCOPE_SYSTEM}, meaning that the threads contend
273 for CPU time with all processes running on the machine. In particular,
274 thread priorities are interpreted relative to the priorities of all
275 other processes on the machine. The other possibility,
276 @code{PTHREAD_SCOPE_PROCESS}, means that scheduling contention occurs
277 only between the threads of the running process: thread priorities are
278 interpreted relative to the priorities of the other threads of the
279 process, regardless of the priorities of other processes.
280
281 @code{PTHREAD_SCOPE_PROCESS} is not supported in LinuxThreads.  If you
282 try to set the scope to this value @code{pthread_attr_setscope} will
283 fail and return @code{ENOTSUP}.
284 @end table
285
286 @node Cancellation
287 @section Cancellation
288
289 Cancellation is the mechanism by which a thread can terminate the
290 execution of another thread. More precisely, a thread can send a
291 cancellation request to another thread. Depending on its settings, the
292 target thread can then either ignore the request, honor it immediately,
293 or defer it till it reaches a cancellation point.  When threads are
294 first created by @code{pthread_create}, they always defer cancellation
295 requests.
296
297 When a thread eventually honors a cancellation request, it behaves as if
298 @code{pthread_exit(PTHREAD_CANCELED)} was called.  All cleanup handlers
299 are executed in reverse order, finalization functions for
300 thread-specific data are called, and finally the thread stops executing.
301 If the cancelled thread was joinable, the return value
302 @code{PTHREAD_CANCELED} is provided to whichever thread calls
303 @var{pthread_join} on it. See @code{pthread_exit} for more information.
304
305 Cancellation points are the points where the thread checks for pending
306 cancellation requests and performs them.  The POSIX threads functions
307 @code{pthread_join}, @code{pthread_cond_wait},
308 @code{pthread_cond_timedwait}, @code{pthread_testcancel},
309 @code{sem_wait}, and @code{sigwait} are cancellation points.  In
310 addition, these system calls are cancellation points:
311
312 @multitable @columnfractions .33 .33 .33
313 @item @t{accept}        @tab @t{open}           @tab @t{sendmsg}
314 @item @t{close}         @tab @t{pause}          @tab @t{sendto}
315 @item @t{connect}       @tab @t{read}           @tab @t{system}
316 @item @t{fcntl}         @tab @t{recv}           @tab @t{tcdrain}
317 @item @t{fsync}         @tab @t{recvfrom}       @tab @t{wait}
318 @item @t{lseek}         @tab @t{recvmsg}        @tab @t{waitpid}
319 @item @t{msync}         @tab @t{send}           @tab @t{write}
320 @item @t{nanosleep}
321 @end multitable
322
323 @noindent
324 All library functions that call these functions (such as
325 @code{printf}) are also cancellation points.
326
327 @comment pthread.h
328 @comment POSIX
329 @deftypefun int pthread_setcancelstate (int @var{state}, int *@var{oldstate})
330 @code{pthread_setcancelstate} changes the cancellation state for the
331 calling thread -- that is, whether cancellation requests are ignored or
332 not. The @var{state} argument is the new cancellation state: either
333 @code{PTHREAD_CANCEL_ENABLE} to enable cancellation, or
334 @code{PTHREAD_CANCEL_DISABLE} to disable cancellation (cancellation
335 requests are ignored).
336
337 If @var{oldstate} is not @code{NULL}, the previous cancellation state is
338 stored in the location pointed to by @var{oldstate}, and can thus be
339 restored later by another call to @code{pthread_setcancelstate}.
340
341 If the @var{state} argument is not @code{PTHREAD_CANCEL_ENABLE} or
342 @code{PTHREAD_CANCEL_DISABLE}, @code{pthread_setcancelstate} fails and
343 returns @code{EINVAL}.  Otherwise it returns 0.
344 @end deftypefun
345
346 @comment pthread.h
347 @comment POSIX
348 @deftypefun int pthread_setcanceltype (int @var{type}, int *@var{oldtype})
349 @code{pthread_setcanceltype} changes the type of responses to
350 cancellation requests for the calling thread: asynchronous (immediate)
351 or deferred.  The @var{type} argument is the new cancellation type:
352 either @code{PTHREAD_CANCEL_ASYNCHRONOUS} to cancel the calling thread
353 as soon as the cancellation request is received, or
354 @code{PTHREAD_CANCEL_DEFERRED} to keep the cancellation request pending
355 until the next cancellation point. If @var{oldtype} is not @code{NULL},
356 the previous cancellation state is stored in the location pointed to by
357 @var{oldtype}, and can thus be restored later by another call to
358 @code{pthread_setcanceltype}.
359
360 If the @var{type} argument is not @code{PTHREAD_CANCEL_DEFERRED} or
361 @code{PTHREAD_CANCEL_ASYNCHRONOUS}, @code{pthread_setcanceltype} fails
362 and returns @code{EINVAL}.  Otherwise it returns 0.
363 @end deftypefun
364
365 @comment pthread.h
366 @comment POSIX
367 @deftypefun void pthread_testcancel (@var{void})
368 @code{pthread_testcancel} does nothing except testing for pending
369 cancellation and executing it. Its purpose is to introduce explicit
370 checks for cancellation in long sequences of code that do not call
371 cancellation point functions otherwise.
372 @end deftypefun
373
374 @node Cleanup Handlers
375 @section Cleanup Handlers
376
377 Cleanup handlers are functions that get called when a thread terminates,
378 either by calling @code{pthread_exit} or because of
379 cancellation. Cleanup handlers are installed and removed following a
380 stack-like discipline.
381
382 The purpose of cleanup handlers is to free the resources that a thread
383 may hold at the time it terminates. In particular, if a thread exits or
384 is cancelled while it owns a locked mutex, the mutex will remain locked
385 forever and prevent other threads from executing normally. The best way
386 to avoid this is, just before locking the mutex, to install a cleanup
387 handler whose effect is to unlock the mutex. Cleanup handlers can be
388 used similarly to free blocks allocated with @code{malloc} or close file
389 descriptors on thread termination.
390
391 Here is how to lock a mutex @var{mut} in such a way that it will be
392 unlocked if the thread is canceled while @var{mut} is locked:
393
394 @smallexample
395 pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
396 pthread_mutex_lock(&mut);
397 /* do some work */
398 pthread_mutex_unlock(&mut);
399 pthread_cleanup_pop(0);
400 @end smallexample
401
402 Equivalently, the last two lines can be replaced by
403
404 @smallexample
405 pthread_cleanup_pop(1);
406 @end smallexample
407
408 Notice that the code above is safe only in deferred cancellation mode
409 (see @code{pthread_setcanceltype}). In asynchronous cancellation mode, a
410 cancellation can occur between @code{pthread_cleanup_push} and
411 @code{pthread_mutex_lock}, or between @code{pthread_mutex_unlock} and
412 @code{pthread_cleanup_pop}, resulting in both cases in the thread trying
413 to unlock a mutex not locked by the current thread. This is the main
414 reason why asynchronous cancellation is difficult to use.
415
416 If the code above must also work in asynchronous cancellation mode,
417 then it must switch to deferred mode for locking and unlocking the
418 mutex:
419
420 @smallexample
421 pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
422 pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
423 pthread_mutex_lock(&mut);
424 /* do some work */
425 pthread_cleanup_pop(1);
426 pthread_setcanceltype(oldtype, NULL);
427 @end smallexample
428
429 The code above can be rewritten in a more compact and efficient way,
430 using the non-portable functions @code{pthread_cleanup_push_defer_np}
431 and @code{pthread_cleanup_pop_restore_np}:
432
433 @smallexample
434 pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut);
435 pthread_mutex_lock(&mut);
436 /* do some work */
437 pthread_cleanup_pop_restore_np(1);
438 @end smallexample
439
440 @comment pthread.h
441 @comment POSIX
442 @deftypefun void pthread_cleanup_push (void (*@var{routine}) (void *), void *@var{arg})
443
444 @code{pthread_cleanup_push} installs the @var{routine} function with
445 argument @var{arg} as a cleanup handler. From this point on to the
446 matching @code{pthread_cleanup_pop}, the function @var{routine} will be
447 called with arguments @var{arg} when the thread terminates, either
448 through @code{pthread_exit} or by cancellation. If several cleanup
449 handlers are active at that point, they are called in LIFO order: the
450 most recently installed handler is called first.
451 @end deftypefun
452
453 @comment pthread.h
454 @comment POSIX
455 @deftypefun void pthread_cleanup_pop (int @var{execute})
456 @code{pthread_cleanup_pop} removes the most recently installed cleanup
457 handler. If the @var{execute} argument is not 0, it also executes the
458 handler, by calling the @var{routine} function with arguments
459 @var{arg}. If the @var{execute} argument is 0, the handler is only
460 removed but not executed.
461 @end deftypefun
462
463 Matching pairs of @code{pthread_cleanup_push} and
464 @code{pthread_cleanup_pop} must occur in the same function, at the same
465 level of block nesting.  Actually, @code{pthread_cleanup_push} and
466 @code{pthread_cleanup_pop} are macros, and the expansion of
467 @code{pthread_cleanup_push} introduces an open brace @code{@{} with the
468 matching closing brace @code{@}} being introduced by the expansion of the
469 matching @code{pthread_cleanup_pop}.
470
471 @comment pthread.h
472 @comment GNU
473 @deftypefun void pthread_cleanup_push_defer_np (void (*@var{routine}) (void *), void *@var{arg})
474 @code{pthread_cleanup_push_defer_np} is a non-portable extension that
475 combines @code{pthread_cleanup_push} and @code{pthread_setcanceltype}.
476 It pushes a cleanup handler just as @code{pthread_cleanup_push} does,
477 but also saves the current cancellation type and sets it to deferred
478 cancellation. This ensures that the cleanup mechanism is effective even
479 if the thread was initially in asynchronous cancellation mode.
480 @end deftypefun
481
482 @comment pthread.h
483 @comment GNU
484 @deftypefun void pthread_cleanup_pop_restore_np (int @var{execute})
485 @code{pthread_cleanup_pop_restore_np} pops a cleanup handler introduced
486 by @code{pthread_cleanup_push_defer_np}, and restores the cancellation
487 type to its value at the time @code{pthread_cleanup_push_defer_np} was
488 called.
489 @end deftypefun
490
491 @code{pthread_cleanup_push_defer_np} and
492 @code{pthread_cleanup_pop_restore_np} must occur in matching pairs, at
493 the same level of block nesting.
494
495 The sequence
496
497 @smallexample
498 pthread_cleanup_push_defer_np(routine, arg);
499 ...
500 pthread_cleanup_pop_defer_np(execute);
501 @end smallexample
502
503 @noindent
504 is functionally equivalent to (but more compact and efficient than)
505
506 @smallexample
507 @{
508   int oldtype;
509   pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
510   pthread_cleanup_push(routine, arg);
511   ...
512   pthread_cleanup_pop(execute);
513   pthread_setcanceltype(oldtype, NULL);
514 @}
515 @end smallexample
516
517
518 @node Mutexes
519 @section Mutexes
520
521 A mutex is a MUTual EXclusion device, and is useful for protecting
522 shared data structures from concurrent modifications, and implementing
523 critical sections and monitors.
524
525 A mutex has two possible states: unlocked (not owned by any thread),
526 and locked (owned by one thread). A mutex can never be owned by two
527 different threads simultaneously. A thread attempting to lock a mutex
528 that is already locked by another thread is suspended until the owning
529 thread unlocks the mutex first.
530
531 None of the mutex functions is a cancellation point, not even
532 @code{pthread_mutex_lock}, in spite of the fact that it can suspend a
533 thread for arbitrary durations. This way, the status of mutexes at
534 cancellation points is predictable, allowing cancellation handlers to
535 unlock precisely those mutexes that need to be unlocked before the
536 thread stops executing. Consequently, threads using deferred
537 cancellation should never hold a mutex for extended periods of time.
538
539 It is not safe to call mutex functions from a signal handler.  In
540 particular, calling @code{pthread_mutex_lock} or
541 @code{pthread_mutex_unlock} from a signal handler may deadlock the
542 calling thread.
543
544 @comment pthread.h
545 @comment POSIX
546 @deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr})
547
548 @code{pthread_mutex_init} initializes the mutex object pointed to by
549 @var{mutex} according to the mutex attributes specified in @var{mutexattr}.
550 If @var{mutexattr} is @code{NULL}, default attributes are used instead.
551
552 The LinuxThreads implementation supports only one mutex attribute,
553 the @var{mutex kind}, which is either ``fast'', ``recursive'', or
554 ``error checking''. The kind of a mutex determines whether
555 it can be locked again by a thread that already owns it.
556 The default kind is ``fast''.
557
558 Variables of type @code{pthread_mutex_t} can also be initialized
559 statically, using the constants @code{PTHREAD_MUTEX_INITIALIZER} (for
560 fast mutexes), @code{PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP} (for
561 recursive mutexes), and @code{PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP}
562 (for error checking mutexes).
563
564 @code{pthread_mutex_init} always returns 0.
565 @end deftypefun
566
567 @comment pthread.h
568 @comment POSIX
569 @deftypefun int pthread_mutex_lock (pthread_mutex_t *mutex))
570 @code{pthread_mutex_lock} locks the given mutex. If the mutex is
571 currently unlocked, it becomes locked and owned by the calling thread,
572 and @code{pthread_mutex_lock} returns immediately. If the mutex is
573 already locked by another thread, @code{pthread_mutex_lock} suspends the
574 calling thread until the mutex is unlocked.
575
576 If the mutex is already locked by the calling thread, the behavior of
577 @code{pthread_mutex_lock} depends on the kind of the mutex. If the mutex
578 is of the ``fast'' kind, the calling thread is suspended.  It will
579 remain suspended forever, because no other thread can unlock the mutex.
580 If  the mutex is of the ``error checking'' kind, @code{pthread_mutex_lock}
581 returns immediately with the error code @code{EDEADLK}.  If the mutex is
582 of the ``recursive'' kind, @code{pthread_mutex_lock} succeeds and
583 returns immediately, recording the number of times the calling thread
584 has locked the mutex. An equal number of @code{pthread_mutex_unlock}
585 operations must be performed before the mutex returns to the unlocked
586 state.
587 @end deftypefun
588
589 @comment pthread.h
590 @comment POSIX
591 @deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex})
592 @code{pthread_mutex_trylock} behaves identically to
593 @code{pthread_mutex_lock}, except that it does not block the calling
594 thread if the mutex is already locked by another thread (or by the
595 calling thread in the case of a ``fast'' mutex). Instead,
596 @code{pthread_mutex_trylock} returns immediately with the error code
597 @code{EBUSY}.
598 @end deftypefun
599
600 @comment pthread.h
601 @comment POSIX
602 @deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
603 The @code{pthread_mutex_timedlock} is similar to the
604 @code{pthread_mutex_lock} function but instead of blocking for in
605 indefinite time if the mutex is locked by another thread, it returns
606 when the time specified in @var{abstime} is reached.
607
608 If the mutex is successfully locked, the function returns zero.  If the
609 time specified in @var{abstime} is reached without the mutex being locked,
610 @code{ETIMEDOUT} is returned.
611
612 This function was introduced in the POSIX.1d revision of the POSIX standard.
613 @end deftypefun
614
615 @comment pthread.h
616 @comment POSIX
617 @deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex})
618 @code{pthread_mutex_unlock} unlocks the given mutex. The mutex is
619 assumed to be locked and owned by the calling thread on entrance to
620 @code{pthread_mutex_unlock}. If the mutex is of the ``fast'' kind,
621 @code{pthread_mutex_unlock} always returns it to the unlocked state. If
622 it is of the ``recursive'' kind, it decrements the locking count of the
623 mutex (number of @code{pthread_mutex_lock} operations performed on it by
624 the calling thread), and only when this count reaches zero is the mutex
625 actually unlocked.
626
627 On ``error checking'' mutexes, @code{pthread_mutex_unlock} actually
628 checks at run-time that the mutex is locked on entrance, and that it was
629 locked by the same thread that is now calling
630 @code{pthread_mutex_unlock}.  If these conditions are not met,
631 @code{pthread_mutex_unlock} returns @code{EPERM}, and the mutex remains
632 unchanged.  ``Fast'' and ``recursive'' mutexes perform no such checks,
633 thus allowing a locked mutex to be unlocked by a thread other than its
634 owner. This is non-portable behavior and must not be relied upon.
635 @end deftypefun
636
637 @comment pthread.h
638 @comment POSIX
639 @deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex})
640 @code{pthread_mutex_destroy} destroys a mutex object, freeing the
641 resources it might hold. The mutex must be unlocked on entrance. In the
642 LinuxThreads implementation, no resources are associated with mutex
643 objects, thus @code{pthread_mutex_destroy} actually does nothing except
644 checking that the mutex is unlocked.
645
646 If the mutex is locked by some thread, @code{pthread_mutex_destroy}
647 returns @code{EBUSY}.  Otherwise it returns 0.
648 @end deftypefun
649
650 If any of the above functions (except @code{pthread_mutex_init})
651 is applied to an uninitialized mutex, they will simply return
652 @code{EINVAL} and do nothing.
653
654 A shared global variable @var{x} can be protected by a mutex as follows:
655
656 @smallexample
657 int x;
658 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
659 @end smallexample
660
661 All accesses and modifications to @var{x} should be bracketed by calls to
662 @code{pthread_mutex_lock} and @code{pthread_mutex_unlock} as follows:
663
664 @smallexample
665 pthread_mutex_lock(&mut);
666 /* operate on x */
667 pthread_mutex_unlock(&mut);
668 @end smallexample
669
670 Mutex attributes can be specified at mutex creation time, by passing a
671 mutex attribute object as second argument to @code{pthread_mutex_init}.
672 Passing @code{NULL} is equivalent to passing a mutex attribute object
673 with all attributes set to their default values.
674
675 @comment pthread.h
676 @comment POSIX
677 @deftypefun int pthread_mutexattr_init (pthread_mutexattr_t *@var{attr})
678 @code{pthread_mutexattr_init} initializes the mutex attribute object
679 @var{attr} and fills it with default values for the attributes.
680
681 This function always returns 0.
682 @end deftypefun
683
684 @comment pthread.h
685 @comment POSIX
686 @deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr})
687 @code{pthread_mutexattr_destroy} destroys a mutex attribute object,
688 which must not be reused until it is
689 reinitialized. @code{pthread_mutexattr_destroy} does nothing in the
690 LinuxThreads implementation.
691
692 This function always returns 0.
693 @end deftypefun
694
695 LinuxThreads supports only one mutex attribute: the mutex kind, which is
696 either @code{PTHREAD_MUTEX_FAST_NP} for ``fast'' mutexes,
697 @code{PTHREAD_MUTEX_RECURSIVE_NP} for ``recursive'' mutexes, or
698 @code{PTHREAD_MUTEX_ERRORCHECK_NP} for ``error checking'' mutexes.  As
699 the @code{NP} suffix indicates, this is a non-portable extension to the
700 POSIX standard and should not be employed in portable programs.
701
702 The mutex kind determines what happens if a thread attempts to lock a
703 mutex it already owns with @code{pthread_mutex_lock}. If the mutex is of
704 the ``fast'' kind, @code{pthread_mutex_lock} simply suspends the calling
705 thread forever.  If the mutex is of the ``error checking'' kind,
706 @code{pthread_mutex_lock} returns immediately with the error code
707 @code{EDEADLK}.  If the mutex is of the ``recursive'' kind, the call to
708 @code{pthread_mutex_lock} returns immediately with a success return
709 code. The number of times the thread owning the mutex has locked it is
710 recorded in the mutex. The owning thread must call
711 @code{pthread_mutex_unlock} the same number of times before the mutex
712 returns to the unlocked state.
713
714 The default mutex kind is ``fast'', that is, @code{PTHREAD_MUTEX_FAST_NP}.
715
716 @comment pthread.h
717 @comment GNU
718 @deftypefun int pthread_mutexattr_setkind_np (pthread_mutexattr_t *@var{attr}, int @var{kind})
719 @code{pthread_mutexattr_setkind_np} sets the mutex kind attribute in
720 @var{attr} to the value specified by @var{kind}.
721
722 If @var{kind} is not @code{PTHREAD_MUTEX_FAST_NP},
723 @code{PTHREAD_MUTEX_RECURSIVE_NP}, or
724 @code{PTHREAD_MUTEX_ERRORCHECK_NP}, this function will return
725 @code{EINVAL} and leave @var{attr} unchanged.
726 @end deftypefun
727
728 @comment pthread.h
729 @comment GNU
730 @deftypefun int pthread_mutexattr_getkind_np (const pthread_mutexattr_t *@var{attr}, int *@var{kind})
731 @code{pthread_mutexattr_getkind_np} retrieves the current value of the
732 mutex kind attribute in @var{attr} and stores it in the location pointed
733 to by @var{kind}.
734
735 This function always returns 0.
736 @end deftypefun
737
738 @node Condition Variables
739 @section Condition Variables
740
741 A condition (short for ``condition variable'') is a synchronization
742 device that allows threads to suspend execution until some predicate on
743 shared data is satisfied. The basic operations on conditions are: signal
744 the condition (when the predicate becomes true), and wait for the
745 condition, suspending the thread execution until another thread signals
746 the condition.
747
748 A condition variable must always be associated with a mutex, to avoid
749 the race condition where a thread prepares to wait on a condition
750 variable and another thread signals the condition just before the first
751 thread actually waits on it.
752
753 @comment pthread.h
754 @comment POSIX
755 @deftypefun int pthread_cond_init (pthread_cond_t *@var{cond}, pthread_condattr_t *cond_@var{attr})
756
757 @code{pthread_cond_init} initializes the condition variable @var{cond},
758 using the condition attributes specified in @var{cond_attr}, or default
759 attributes if @var{cond_attr} is @code{NULL}. The LinuxThreads
760 implementation supports no attributes for conditions, hence the
761 @var{cond_attr} parameter is actually ignored.
762
763 Variables of type @code{pthread_cond_t} can also be initialized
764 statically, using the constant @code{PTHREAD_COND_INITIALIZER}.
765
766 This function always returns 0.
767 @end deftypefun
768
769 @comment pthread.h
770 @comment POSIX
771 @deftypefun int pthread_cond_signal (pthread_cond_t *@var{cond})
772 @code{pthread_cond_signal} restarts one of the threads that are waiting
773 on the condition variable @var{cond}. If no threads are waiting on
774 @var{cond}, nothing happens. If several threads are waiting on
775 @var{cond}, exactly one is restarted, but it is not specified which.
776
777 This function always returns 0.
778 @end deftypefun
779
780 @comment pthread.h
781 @comment POSIX
782 @deftypefun int pthread_cond_broadcast (pthread_cond_t *@var{cond})
783 @code{pthread_cond_broadcast} restarts all the threads that are waiting
784 on the condition variable @var{cond}. Nothing happens if no threads are
785 waiting on @var{cond}.
786
787 This function always returns 0.
788 @end deftypefun
789
790 @comment pthread.h
791 @comment POSIX
792 @deftypefun int pthread_cond_wait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex})
793 @code{pthread_cond_wait} atomically unlocks the @var{mutex} (as per
794 @code{pthread_unlock_mutex}) and waits for the condition variable
795 @var{cond} to be signaled. The thread execution is suspended and does
796 not consume any CPU time until the condition variable is signaled. The
797 @var{mutex} must be locked by the calling thread on entrance to
798 @code{pthread_cond_wait}. Before returning to the calling thread,
799 @code{pthread_cond_wait} re-acquires @var{mutex} (as per
800 @code{pthread_lock_mutex}).
801
802 Unlocking the mutex and suspending on the condition variable is done
803 atomically. Thus, if all threads always acquire the mutex before
804 signaling the condition, this guarantees that the condition cannot be
805 signaled (and thus ignored) between the time a thread locks the mutex
806 and the time it waits on the condition variable.
807
808 This function always returns 0.
809 @end deftypefun
810
811 @comment pthread.h
812 @comment POSIX
813 @deftypefun int pthread_cond_timedwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
814 @code{pthread_cond_timedwait} atomically unlocks @var{mutex} and waits
815 on @var{cond}, as @code{pthread_cond_wait} does, but it also bounds the
816 duration of the wait. If @var{cond} has not been signaled before time
817 @var{abstime}, the mutex @var{mutex} is re-acquired and
818 @code{pthread_cond_timedwait} returns the error code @code{ETIMEDOUT}.
819 The wait can also be interrupted by a signal; in that case
820 @code{pthread_cond_timedwait} returns @code{EINTR}.
821
822 The @var{abstime} parameter specifies an absolute time, with the same
823 origin as @code{time} and @code{gettimeofday}: an @var{abstime} of 0
824 corresponds to 00:00:00 GMT, January 1, 1970.
825 @end deftypefun
826
827 @comment pthread.h
828 @comment POSIX
829 @deftypefun int pthread_cond_destroy (pthread_cond_t *@var{cond})
830 @code{pthread_cond_destroy} destroys the condition variable @var{cond},
831 freeing the resources it might hold.  If any threads are waiting on the
832 condition variable, @code{pthread_cond_destroy} leaves @var{cond}
833 untouched and returns @code{EBUSY}.  Otherwise it returns 0, and
834 @var{cond} must not be used again until it is reinitialized.
835
836 In the LinuxThreads implementation, no resources are associated with
837 condition variables, so @code{pthread_cond_destroy} actually does
838 nothing.
839 @end deftypefun
840
841 @code{pthread_cond_wait} and @code{pthread_cond_timedwait} are
842 cancellation points. If a thread is cancelled while suspended in one of
843 these functions, the thread immediately resumes execution, relocks the
844 mutex specified by  @var{mutex}, and finally executes the cancellation.
845 Consequently, cleanup handlers are assured that @var{mutex} is locked
846 when they are called.
847
848 It is not safe to call the condition variable functions from a signal
849 handler. In particular, calling @code{pthread_cond_signal} or
850 @code{pthread_cond_broadcast} from a signal handler may deadlock the
851 calling thread.
852
853 Consider two shared variables @var{x} and @var{y}, protected by the
854 mutex @var{mut}, and a condition variable @var{cond} that is to be
855 signaled whenever @var{x} becomes greater than @var{y}.
856
857 @smallexample
858 int x,y;
859 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
860 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
861 @end smallexample
862
863 Waiting until @var{x} is greater than @var{y} is performed as follows:
864
865 @smallexample
866 pthread_mutex_lock(&mut);
867 while (x <= y) @{
868         pthread_cond_wait(&cond, &mut);
869 @}
870 /* operate on x and y */
871 pthread_mutex_unlock(&mut);
872 @end smallexample
873
874 Modifications on @var{x} and @var{y} that may cause @var{x} to become greater than
875 @var{y} should signal the condition if needed:
876
877 @smallexample
878 pthread_mutex_lock(&mut);
879 /* modify x and y */
880 if (x > y) pthread_cond_broadcast(&cond);
881 pthread_mutex_unlock(&mut);
882 @end smallexample
883
884 If it can be proved that at most one waiting thread needs to be waken
885 up (for instance, if there are only two threads communicating through
886 @var{x} and @var{y}), @code{pthread_cond_signal} can be used as a slightly more
887 efficient alternative to @code{pthread_cond_broadcast}. In doubt, use
888 @code{pthread_cond_broadcast}.
889
890 To wait for @var{x} to becomes greater than @var{y} with a timeout of 5
891 seconds, do:
892
893 @smallexample
894 struct timeval now;
895 struct timespec timeout;
896 int retcode;
897
898 pthread_mutex_lock(&mut);
899 gettimeofday(&now);
900 timeout.tv_sec = now.tv_sec + 5;
901 timeout.tv_nsec = now.tv_usec * 1000;
902 retcode = 0;
903 while (x <= y && retcode != ETIMEDOUT) @{
904         retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
905 @}
906 if (retcode == ETIMEDOUT) @{
907         /* timeout occurred */
908 @} else @{
909         /* operate on x and y */
910 @}
911 pthread_mutex_unlock(&mut);
912 @end smallexample
913
914 Condition attributes can be specified at condition creation time, by
915 passing a condition attribute object as second argument to
916 @code{pthread_cond_init}.  Passing @code{NULL} is equivalent to passing
917 a condition attribute object with all attributes set to their default
918 values.
919
920 The LinuxThreads implementation supports no attributes for
921 conditions. The functions on condition attributes are included only for
922 compliance with the POSIX standard.
923
924 @comment pthread.h
925 @comment POSIX
926 @deftypefun int pthread_condattr_init (pthread_condattr_t *@var{attr})
927 @deftypefunx int pthread_condattr_destroy (pthread_condattr_t *@var{attr})
928 @code{pthread_condattr_init} initializes the condition attribute object
929 @var{attr} and fills it with default values for the attributes.
930 @code{pthread_condattr_destroy} destroys the condition attribute object
931 @var{attr}.
932
933 Both functions do nothing in the LinuxThreads implementation.
934
935 @code{pthread_condattr_init} and @code{pthread_condattr_destroy} always
936 return 0.
937 @end deftypefun
938
939 @node POSIX Semaphores
940 @section POSIX Semaphores
941
942 @vindex SEM_VALUE_MAX
943 Semaphores are counters for resources shared between threads. The
944 basic operations on semaphores are: increment the counter atomically,
945 and wait until the counter is non-null and decrement it atomically.
946
947 Semaphores have a maximum value past which they cannot be incremented.
948 The macro @code{SEM_VALUE_MAX} is defined to be this maximum value.  In
949 the GNU C library, @code{SEM_VALUE_MAX} is equal to @code{INT_MAX}
950 (@pxref{Range of Type}), but it may be much smaller on other systems.
951
952 The pthreads library implements POSIX 1003.1b semaphores.  These should
953 not be confused with System V semaphores (@code{ipc}, @code{semctl} and
954 @code{semop}).
955 @c !!! SysV IPC is not doc'd at all in our manual
956
957 All the semaphore functions and macros are defined in @file{semaphore.h}.
958
959 @comment semaphore.h
960 @comment POSIX
961 @deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
962 @code{sem_init} initializes the semaphore object pointed to by
963 @var{sem}. The count associated with the semaphore is set initially to
964 @var{value}. The @var{pshared} argument indicates whether the semaphore
965 is local to the current process (@var{pshared} is zero) or is to be
966 shared between several processes (@var{pshared} is not zero).
967
968 On success @code{sem_init} returns 0.  On failure it returns -1 and sets
969 @var{errno} to one of the following values:
970
971 @table @code
972 @item EINVAL
973 @var{value} exceeds the maximal counter value @code{SEM_VALUE_MAX}
974
975 @item ENOSYS
976 @var{pshared} is not zero.  LinuxThreads currently does not support
977 process-shared semaphores.  (This will eventually change.)
978 @end table
979 @end deftypefun
980
981 @comment semaphore.h
982 @comment POSIX
983 @deftypefun int sem_destroy (sem_t * @var{sem})
984 @code{sem_destroy} destroys a semaphore object, freeing the resources it
985 might hold.  If any threads are waiting on the semaphore when
986 @code{sem_destroy} is called, it fails and sets @var{errno} to
987 @code{EBUSY}.
988
989 In the LinuxThreads implementation, no resources are associated with
990 semaphore objects, thus @code{sem_destroy} actually does nothing except
991 checking that no thread is waiting on the semaphore.  This will change
992 when process-shared semaphores are implemented.
993 @end deftypefun
994
995 @comment semaphore.h
996 @comment POSIX
997 @deftypefun int sem_wait (sem_t * @var{sem})
998 @code{sem_wait} suspends the calling thread until the semaphore pointed
999 to by @var{sem} has non-zero count. It then atomically decreases the
1000 semaphore count.
1001
1002 @code{sem_wait} is a cancellation point.  It always returns 0.
1003 @end deftypefun
1004
1005 @comment semaphore.h
1006 @comment POSIX
1007 @deftypefun int sem_trywait (sem_t * @var{sem})
1008 @code{sem_trywait} is a non-blocking variant of @code{sem_wait}. If the
1009 semaphore pointed to by @var{sem} has non-zero count, the count is
1010 atomically decreased and @code{sem_trywait} immediately returns 0.  If
1011 the semaphore count is zero, @code{sem_trywait} immediately returns -1
1012 and sets errno to @code{EAGAIN}.
1013 @end deftypefun
1014
1015 @comment semaphore.h
1016 @comment POSIX
1017 @deftypefun int sem_post (sem_t * @var{sem})
1018 @code{sem_post} atomically increases the count of the semaphore pointed to
1019 by @var{sem}. This function never blocks.
1020
1021 @c !!! This para appears not to agree with the code.
1022 On processors supporting atomic compare-and-swap (Intel 486, Pentium and
1023 later, Alpha, PowerPC, MIPS II, Motorola 68k, Ultrasparc), the
1024 @code{sem_post} function is can safely be called from signal handlers.
1025 This is the only thread synchronization function provided by POSIX
1026 threads that is async-signal safe.  On the Intel 386 and earlier Sparc
1027 chips, the current LinuxThreads implementation of @code{sem_post} is not
1028 async-signal safe, because the hardware does not support the required
1029 atomic operations.
1030
1031 @code{sem_post} always succeeds and returns 0, unless the semaphore
1032 count would exceed @code{SEM_VALUE_MAX} after being incremented.  In
1033 that case @code{sem_post} returns -1 and sets @var{errno} to
1034 @code{EINVAL}.  The semaphore count is left unchanged.
1035 @end deftypefun
1036
1037 @comment semaphore.h
1038 @comment POSIX
1039 @deftypefun int sem_getvalue (sem_t * @var{sem}, int * @var{sval})
1040 @code{sem_getvalue} stores in the location pointed to by @var{sval} the
1041 current count of the semaphore @var{sem}.  It always returns 0.
1042 @end deftypefun
1043
1044 @node Thread-Specific Data
1045 @section Thread-Specific Data
1046
1047 Programs often need global or static variables that have different
1048 values in different threads. Since threads share one memory space, this
1049 cannot be achieved with regular variables. Thread-specific data is the
1050 POSIX threads answer to this need.
1051
1052 Each thread possesses a private memory block, the thread-specific data
1053 area, or TSD area for short. This area is indexed by TSD keys. The TSD
1054 area associates values of type @code{void *} to TSD keys. TSD keys are
1055 common to all threads, but the value associated with a given TSD key can
1056 be different in each thread.
1057
1058 For concreteness, the TSD areas can be viewed as arrays of @code{void *}
1059 pointers, TSD keys as integer indices into these arrays, and the value
1060 of a TSD key as the value of the corresponding array element in the
1061 calling thread.
1062
1063 When a thread is created, its TSD area initially associates @code{NULL}
1064 with all keys.
1065
1066 @comment pthread.h
1067 @comment POSIX
1068 @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*destr_function) (void *))
1069 @code{pthread_key_create} allocates a new TSD key. The key is stored in
1070 the location pointed to by @var{key}. There is a limit of
1071 @code{PTHREAD_KEYS_MAX} on the number of keys allocated at a given
1072 time. The value initially associated with the returned key is
1073 @code{NULL} in all currently executing threads.
1074
1075 The @var{destr_function} argument, if not @code{NULL}, specifies a
1076 destructor function associated with the key. When a thread terminates
1077 via @code{pthread_exit} or by cancellation, @var{destr_function} is
1078 called on the value associated with the key in that thread. The
1079 @var{destr_function} is not called if a key is deleted with
1080 @code{pthread_key_delete} or a value is changed with
1081 @code{pthread_setspecific}.  The order in which destructor functions are
1082 called at thread termination time is unspecified.
1083
1084 Before the destructor function is called, the @code{NULL} value is
1085 associated with the key in the current thread.  A destructor function
1086 might, however, re-associate non-@code{NULL} values to that key or some
1087 other key.  To deal with this, if after all the destructors have been
1088 called for all non-@code{NULL} values, there are still some
1089 non-@code{NULL} values with associated destructors, then the process is
1090 repeated.  The LinuxThreads implementation stops the process after
1091 @code{PTHREAD_DESTRUCTOR_ITERATIONS} iterations, even if some
1092 non-@code{NULL} values with associated descriptors remain.  Other
1093 implementations may loop indefinitely.
1094
1095 @code{pthread_key_create} returns 0 unless @code{PTHREAD_KEYS_MAX} keys
1096 have already been allocated, in which case it fails and returns
1097 @code{EAGAIN}.
1098 @end deftypefun
1099
1100
1101 @comment pthread.h
1102 @comment POSIX
1103 @deftypefun int pthread_key_delete (pthread_key_t @var{key})
1104 @code{pthread_key_delete} deallocates a TSD key. It does not check
1105 whether non-@code{NULL} values are associated with that key in the
1106 currently executing threads, nor call the destructor function associated
1107 with the key.
1108
1109 If there is no such key @var{key}, it returns @code{EINVAL}.  Otherwise
1110 it returns 0.
1111 @end deftypefun
1112
1113 @comment pthread.h
1114 @comment POSIX
1115 @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{pointer})
1116 @code{pthread_setspecific} changes the value associated with @var{key}
1117 in the calling thread, storing the given @var{pointer} instead.
1118
1119 If there is no such key @var{key}, it returns @code{EINVAL}.  Otherwise
1120 it returns 0.
1121 @end deftypefun
1122
1123 @comment pthread.h
1124 @comment POSIX
1125 @deftypefun {void *} pthread_getspecific (pthread_key_t @var{key})
1126 @code{pthread_getspecific} returns the value currently associated with
1127 @var{key} in the calling thread.
1128
1129 If there is no such key @var{key}, it returns @code{NULL}.
1130 @end deftypefun
1131
1132 The following code fragment allocates a thread-specific array of 100
1133 characters, with automatic reclaimation at thread exit:
1134
1135 @smallexample
1136 /* Key for the thread-specific buffer */
1137 static pthread_key_t buffer_key;
1138
1139 /* Once-only initialisation of the key */
1140 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
1141
1142 /* Allocate the thread-specific buffer */
1143 void buffer_alloc(void)
1144 @{
1145   pthread_once(&buffer_key_once, buffer_key_alloc);
1146   pthread_setspecific(buffer_key, malloc(100));
1147 @}
1148
1149 /* Return the thread-specific buffer */
1150 char * get_buffer(void)
1151 @{
1152   return (char *) pthread_getspecific(buffer_key);
1153 @}
1154
1155 /* Allocate the key */
1156 static void buffer_key_alloc()
1157 @{
1158   pthread_key_create(&buffer_key, buffer_destroy);
1159 @}
1160
1161 /* Free the thread-specific buffer */
1162 static void buffer_destroy(void * buf)
1163 @{
1164   free(buf);
1165 @}
1166 @end smallexample
1167
1168 @node Threads and Signal Handling
1169 @section Threads and Signal Handling
1170
1171 @comment pthread.h
1172 @comment POSIX
1173 @deftypefun int pthread_sigmask (int @var{how}, const sigset_t *@var{newmask}, sigset_t *@var{oldmask})
1174 @code{pthread_sigmask} changes the signal mask for the calling thread as
1175 described by the @var{how} and @var{newmask} arguments. If @var{oldmask}
1176 is not @code{NULL}, the previous signal mask is stored in the location
1177 pointed to by @var{oldmask}.
1178
1179 The meaning of the @var{how} and @var{newmask} arguments is the same as
1180 for @code{sigprocmask}. If @var{how} is @code{SIG_SETMASK}, the signal
1181 mask is set to @var{newmask}. If @var{how} is @code{SIG_BLOCK}, the
1182 signals specified to @var{newmask} are added to the current signal mask.
1183 If @var{how} is @code{SIG_UNBLOCK}, the signals specified to
1184 @var{newmask} are removed from the current signal mask.
1185
1186 Recall that signal masks are set on a per-thread basis, but signal
1187 actions and signal handlers, as set with @code{sigaction}, are shared
1188 between all threads.
1189
1190 The @code{pthread_sigmask} function returns 0 on success, and one of the
1191 following error codes on error:
1192 @table @code
1193 @item EINVAL
1194 @var{how} is not one of @code{SIG_SETMASK}, @code{SIG_BLOCK}, or @code{SIG_UNBLOCK}
1195
1196 @item EFAULT
1197 @var{newmask} or @var{oldmask} point to invalid addresses
1198 @end table
1199 @end deftypefun
1200
1201 @comment pthread.h
1202 @comment POSIX
1203 @deftypefun int pthread_kill (pthread_t @var{thread}, int @var{signo})
1204 @code{pthread_kill} sends signal number @var{signo} to the thread
1205 @var{thread}.  The signal is delivered and handled as described in
1206 @ref{Signal Handling}.
1207
1208 @code{pthread_kill} returns 0 on success, one of the following error codes
1209 on error:
1210 @table @code
1211 @item EINVAL
1212 @var{signo} is not a valid signal number
1213
1214 @item ESRCH
1215 The thread @var{thread} does not exist (e.g. it has already terminated)
1216 @end table
1217 @end deftypefun
1218
1219 @comment pthread.h
1220 @comment POSIX
1221 @deftypefun int sigwait (const sigset_t *@var{set}, int *@var{sig})
1222 @code{sigwait} suspends the calling thread until one of the signals in
1223 @var{set} is delivered to the calling thread. It then stores the number
1224 of the signal received in the location pointed to by @var{sig} and
1225 returns. The signals in @var{set} must be blocked and not ignored on
1226 entrance to @code{sigwait}. If the delivered signal has a signal handler
1227 function attached, that function is @emph{not} called.
1228
1229 @code{sigwait} is a cancellation point.  It always returns 0.
1230 @end deftypefun
1231
1232 For @code{sigwait} to work reliably, the signals being waited for must be
1233 blocked in all threads, not only in the calling thread, since
1234 otherwise the POSIX semantics for signal delivery do not guarantee
1235 that it's the thread doing the @code{sigwait} that will receive the signal.
1236 The best way to achieve this is block those signals before any threads
1237 are created, and never unblock them in the program other than by
1238 calling @code{sigwait}.
1239
1240 Signal handling in LinuxThreads departs significantly from the POSIX
1241 standard. According to the standard, ``asynchronous'' (external) signals
1242 are addressed to the whole process (the collection of all threads),
1243 which then delivers them to one particular thread. The thread that
1244 actually receives the signal is any thread that does not currently block
1245 the signal.
1246
1247 In LinuxThreads, each thread is actually a kernel process with its own
1248 PID, so external signals are always directed to one particular thread.
1249 If, for instance, another thread is blocked in @code{sigwait} on that
1250 signal, it will not be restarted.
1251
1252 The LinuxThreads implementation of @code{sigwait} installs dummy signal
1253 handlers for the signals in @var{set} for the duration of the
1254 wait. Since signal handlers are shared between all threads, other
1255 threads must not attach their own signal handlers to these signals, or
1256 alternatively they should all block these signals (which is recommended
1257 anyway).
1258
1259 @node Threads and Fork
1260 @section Threads and Fork
1261
1262 It's not intuitively obvious what should happen when a multi-threaded POSIX
1263 process calls @code{fork}. Not only are the semantics tricky, but you may
1264 need to write code that does the right thing at fork time even if that code
1265 doesn't use the @code{fork} function. Moreover, you need to be aware of
1266 interaction between @code{fork} and some library features like
1267 @code{pthread_once} and stdio streams.
1268
1269 When @code{fork} is called by one of the threads of a process, it creates a new
1270 process which is copy of the  calling process. Effectively, in addition to
1271 copying certain system objects, the function takes a snapshot of the memory
1272 areas of the parent process, and creates identical areas in the child.
1273 To make matters more complicated, with threads it's possible for two or more
1274 threads to concurrently call fork to create two or more child processes.
1275
1276 The child process has a copy of the address space of the parent, but it does
1277 not inherit any of its threads. Execution of the child process is carried out
1278 by a new thread which returns from @code{fork} function with a return value of
1279 zero; it is the only thread in the child process.  Because threads are not
1280 inherited across fork, issues arise. At the time of the call to @code{fork},
1281 threads in the parent process other than the one calling @code{fork} may have
1282 been executing critical regions of code.  As a result, the child process may
1283 get a copy of objects that are not in a well-defined state.  This potential
1284 problem affects all components of the program.
1285
1286 Any program component which will continue being used in a child process must
1287 correctly handle its state during @code{fork}. For this purpose, the POSIX
1288 interface provides the special function @code{pthread_atfork} for installing
1289 pointers to handler functions which are called from within @code{fork}.
1290
1291 @comment pthread.h
1292 @comment POSIX
1293 @deftypefun int pthread_atfork (void (*@var{prepare})(void), void (*@var{parent})(void), void (*@var{child})(void))
1294
1295 @code{pthread_atfork} registers handler functions to be called just
1296 before and just after a new process is created with @code{fork}. The
1297 @var{prepare} handler will be called from the parent process, just
1298 before the new process is created. The @var{parent} handler will be
1299 called from the parent process, just before @code{fork} returns. The
1300 @var{child} handler will be called from the child process, just before
1301 @code{fork} returns.
1302
1303 @code{pthread_atfork} returns 0 on success and a non-zero error code on
1304 error.
1305
1306 One or more of the three handlers @var{prepare}, @var{parent} and
1307 @var{child} can be given as @code{NULL}, meaning that no handler needs
1308 to be called at the corresponding point.
1309
1310 @code{pthread_atfork} can be called several times to install several
1311 sets of handlers. At @code{fork} time, the @var{prepare} handlers are
1312 called in LIFO order (last added with @code{pthread_atfork}, first
1313 called before @code{fork}), while the @var{parent} and @var{child}
1314 handlers are called in FIFO order (first added, first called).
1315
1316 If there is insufficient memory available to register the handlers,
1317 @code{pthread_atfork} fails and returns @code{ENOMEM}.  Otherwise it
1318 returns 0.
1319
1320 The functions @code{fork} and @code{pthread_atfork} must not be regarded as
1321 reentrant from the context of the handlers.  That is to say, if a
1322 @code{pthread_atfork} handler invoked from within @code{fork} calls
1323 @code{pthread_atfork} or @code{fork}, the behavior is undefined.
1324
1325 Registering a triplet of handlers is an atomic operation with respect to fork.
1326 If new handlers are registered at about the same time as a fork occurs, either
1327 all three handlers will be called, or none of them will be called.
1328
1329 The handlers are inherited by the child process, and there is no
1330 way to remove them, short of using @code{exec} to load a new
1331 pocess image.
1332
1333 @end deftypefun
1334
1335 To understand the purpose of @code{pthread_atfork}, recall that
1336 @code{fork} duplicates the whole memory space, including mutexes in
1337 their current locking state, but only the calling thread: other threads
1338 are not running in the child process. Thus, if a mutex is locked by a
1339 thread other than the thread calling @code{fork}, that mutex will remain
1340 locked forever in the child process, possibly blocking the execution of
1341 the child process. Or if some shared data, such as a linked list, was in the
1342 middle of being updated by a thread in the parent process, the child
1343 will get a copy of the incompletely updated data which it cannot use.
1344
1345 To avoid this, install handlers with @code{pthread_atfork} as follows: have the
1346 @var{prepare} handler lock the mutexes (in locking order), and the
1347 @var{parent} handler unlock the mutexes. The @var{child} handler should reset
1348 the mutexes using @code{pthread_mutex_init}, as well as any other
1349 synchronization objects such as condition variables.
1350
1351 Locking the global mutexes before the fork ensures that all other threads are
1352 locked out of the critical regions of code protected by those mutexes.  Thus
1353 when @code{fork} takes a snapshot of the parent's address space, that snapshot
1354 will copy valid, stable data.  Resetting the synchronization objects in the
1355 child process will ensure they are properly cleansed of any artifacts from the
1356 threading subsystem of the parent process. For example, a mutex may inherit
1357 a wait queue of threads waiting for the lock; this wait queue makes no sense
1358 in the child process. Initializing the mutex takes care of this.
1359
1360 @node Streams and Fork
1361 @section Streams and Fork
1362
1363 The GNU standard I/O library has an internal mutex which guards the internal
1364 linked list of all standard C FILE objects. This mutex is properly taken care
1365 of during @code{fork} so that the child receives an intact copy of the list.
1366 This allows the @code{fopen} function, and related stream-creating functions,
1367 to work correctly in the child process, since these functions need to insert
1368 into the list.
1369
1370 However, the individual stream locks are not completely taken care of.  Thus
1371 unless the multithreaded application takes special precautions in its use of
1372 @code{fork}, the child process might not be able to safely use the streams that
1373 it inherited from the parent.   In general, for any given open stream in the
1374 parent that is to be used by the child process, the application must ensure
1375 that that stream is not in use by another thread when @code{fork} is called.
1376 Otherwise an inconsistent copy of the stream object be produced. An easy way to
1377 ensure this is to use @code{flockfile} to lock the stream prior to calling
1378 @code{fork} and then unlock it with @code{funlockfile} inside the parent
1379 process, provided that the parent's threads properly honor these locks.
1380 Nothing special needs to be done in the child process, since the library
1381 internally resets all stream locks.
1382
1383 Note that the stream locks are not shared between the parent and child.
1384 For example, even if you ensure that, say, the stream @code{stdout} is properly
1385 treated and can be safely used in the child, the stream locks do not provide
1386 an exclusion mechanism between the parent and child. If both processes write
1387 to @code{stdout}, strangely interleaved output may result regardless of
1388 the explicit use of @code{flockfile} or implicit locks.
1389
1390 Also note that these provisions are a GNU extension; other systems might not
1391 provide any way for streams to be used in the child of a multithreaded process.
1392 POSIX requires that such a child process confines itself to calling only
1393 asynchronous safe functions, which excludes much of the library, including
1394 standard I/O.
1395
1396 @node Miscellaneous Thread Functions
1397 @section Miscellaneous Thread Functions
1398
1399 @comment pthread.h
1400 @comment POSIX
1401 @deftypefun {pthread_t} pthread_self (@var{void})
1402 @code{pthread_self} returns the thread identifier for the calling thread.
1403 @end deftypefun
1404
1405 @comment pthread.h
1406 @comment POSIX
1407 @deftypefun int pthread_equal (pthread_t thread1, pthread_t thread2)
1408 @code{pthread_equal} determines if two thread identifiers refer to the same
1409 thread.
1410
1411 A non-zero value is returned if @var{thread1} and @var{thread2} refer to
1412 the same thread. Otherwise, 0 is returned.
1413 @end deftypefun
1414
1415 @comment pthread.h
1416 @comment POSIX
1417 @deftypefun int pthread_detach (pthread_t @var{th})
1418 @code{pthread_detach} puts the thread @var{th} in the detached
1419 state. This guarantees that the memory resources consumed by @var{th}
1420 will be freed immediately when @var{th} terminates. However, this
1421 prevents other threads from synchronizing on the termination of @var{th}
1422 using @code{pthread_join}.
1423
1424 A thread can be created initially in the detached state, using the
1425 @code{detachstate} attribute to @code{pthread_create}. In contrast,
1426 @code{pthread_detach} applies to threads created in the joinable state,
1427 and which need to be put in the detached state later.
1428
1429 After @code{pthread_detach} completes, subsequent attempts to perform
1430 @code{pthread_join} on @var{th} will fail. If another thread is already
1431 joining the thread @var{th} at the time @code{pthread_detach} is called,
1432 @code{pthread_detach} does nothing and leaves @var{th} in the joinable
1433 state.
1434
1435 On success, 0 is returned. On error, one of the following codes is
1436 returned:
1437 @table @code
1438 @item ESRCH
1439 No thread could be found corresponding to that specified by @var{th}
1440 @item EINVAL
1441 The thread @var{th} is already in the detached state
1442 @end table
1443 @end deftypefun
1444
1445 @comment pthread.h
1446 @comment GNU
1447 @deftypefun void pthread_kill_other_threads_np (@var{void})
1448 @code{pthread_kill_other_threads_np} is a non-portable LinuxThreads extension.
1449 It causes all threads in the program to terminate immediately, except
1450 the calling thread which proceeds normally. It is intended to be
1451 called just before a thread calls one of the @code{exec} functions,
1452 e.g. @code{execve}.
1453
1454 Termination of the other threads is not performed through
1455 @code{pthread_cancel} and completely bypasses the cancellation
1456 mechanism. Hence, the current settings for cancellation state and
1457 cancellation type are ignored, and the cleanup handlers are not
1458 executed in the terminated threads.
1459
1460 According to POSIX 1003.1c, a successful @code{exec*} in one of the
1461 threads should automatically terminate all other threads in the program.
1462 This behavior is not yet implemented in LinuxThreads.  Calling
1463 @code{pthread_kill_other_threads_np} before @code{exec*} achieves much
1464 of the same behavior, except that if @code{exec*} ultimately fails, then
1465 all other threads are already killed.
1466 @end deftypefun
1467
1468 @comment pthread.h
1469 @comment POSIX
1470 @deftypefun int pthread_once (pthread_once_t *once_@var{control}, void (*@var{init_routine}) (void))
1471
1472 The purpose of @code{pthread_once} is to ensure that a piece of
1473 initialization code is executed at most once. The @var{once_control}
1474 argument points to a static or extern variable statically initialized
1475 to @code{PTHREAD_ONCE_INIT}.
1476
1477 The first time @code{pthread_once} is called with a given
1478 @var{once_control} argument, it calls @var{init_routine} with no
1479 argument and changes the value of the @var{once_control} variable to
1480 record that initialization has been performed. Subsequent calls to
1481 @code{pthread_once} with the same @code{once_control} argument do
1482 nothing.
1483
1484 If a thread is cancelled while executing @var{init_routine}
1485 the state of the @var{once_control} variable is reset so that
1486 a future call to @code{pthread_once} will call the routine again.
1487
1488 If the process forks while one or more threads are executing
1489 @code{pthread_once} initialization routines, the states of their respective
1490 @var{once_control} variables will appear to be reset in the child process so
1491 that if the child calls @code{pthread_once}, the routines will be executed.
1492
1493 @code{pthread_once} always returns 0.
1494 @end deftypefun
1495
1496 @comment pthread.h
1497 @comment POSIX
1498 @deftypefun int pthread_setschedparam (pthread_t target_@var{thread}, int @var{policy}, const struct sched_param *@var{param})
1499
1500 @code{pthread_setschedparam} sets the scheduling parameters for the
1501 thread @var{target_thread} as indicated by @var{policy} and
1502 @var{param}. @var{policy} can be either @code{SCHED_OTHER} (regular,
1503 non-realtime scheduling), @code{SCHED_RR} (realtime, round-robin) or
1504 @code{SCHED_FIFO} (realtime, first-in first-out). @var{param} specifies
1505 the scheduling priority for the two realtime policies.  See
1506 @code{sched_setpolicy} for more information on scheduling policies.
1507
1508 The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}
1509 are available only to processes with superuser privileges.
1510
1511 On success, @code{pthread_setschedparam} returns 0.  On error it returns
1512 one of the following codes:
1513 @table @code
1514 @item EINVAL
1515 @var{policy} is not one of @code{SCHED_OTHER}, @code{SCHED_RR},
1516 @code{SCHED_FIFO}, or the priority value specified by @var{param} is not
1517 valid for the specified policy
1518
1519 @item EPERM
1520 Realtime scheduling was requested but the calling process does not have
1521 sufficient privileges.
1522
1523 @item ESRCH
1524 The @var{target_thread} is invalid or has already terminated
1525
1526 @item EFAULT
1527 @var{param} points outside the process memory space
1528 @end table
1529 @end deftypefun
1530
1531 @comment pthread.h
1532 @comment POSIX
1533 @deftypefun int pthread_getschedparam (pthread_t target_@var{thread}, int *@var{policy}, struct sched_param *@var{param})
1534
1535 @code{pthread_getschedparam} retrieves the scheduling policy and
1536 scheduling parameters for the thread @var{target_thread} and stores them
1537 in the locations pointed to by @var{policy} and @var{param},
1538 respectively.
1539
1540 @code{pthread_getschedparam} returns 0 on success, or one of the
1541 following error codes on failure:
1542 @table @code
1543 @item ESRCH
1544 The @var{target_thread} is invalid or has already terminated.
1545
1546 @item EFAULT
1547 @var{policy} or @var{param} point outside the process memory space.
1548
1549 @end table
1550 @end deftypefun