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