path: root/libpthread/linuxthreads.old/linuxthreads.texi

@node POSIX Threads
@c @node POSIX Threads, , Top, Top
@chapter POSIX Threads
@c %MENU% The standard threads library

@c This chapter needs more work bigtime. -zw

This chapter describes the pthreads (POSIX threads) library.  This
library provides support functions for multithreaded programs: thread
primitives, synchronization objects, and so forth.  It also implements
POSIX 1003.1b semaphores (not to be confused with System V semaphores).

The threads operations (@samp{pthread_*}) do not use @var{errno}.
Instead they return an error code directly.  The semaphore operations do
use @var{errno}.

@menu
* Basic Thread Operations::     Creating, terminating, and waiting for threads.
* Thread Attributes::           Tuning thread scheduling.
* Cancellation::                Stopping a thread before it's done.
* Cleanup Handlers::            Deallocating resources when a thread is
                                  canceled.
* Mutexes::                     One way to synchronize threads.
* Condition Variables::         Another way.
* POSIX Semaphores::            And a third way.
* Thread-Specific Data::        Variables with different values in
                                  different threads.
* Threads and Signal Handling:: Why you should avoid mixing the two, and
                                  how to do it if you must.
* Threads and Fork::            Interactions between threads and the
                                  @code{fork} function.
* Streams and Fork::            Interactions between stdio streams and
                                  @code{fork}.
* Miscellaneous Thread Functions:: A grab bag of utility routines.
@end menu

@node Basic Thread Operations
@section Basic Thread Operations

These functions are the thread equivalents of @code{fork}, @code{exit},
and @code{wait}.

@comment pthread.h
@comment POSIX
@deftypefun int pthread_create (pthread_t * @var{thread}, pthread_attr_t * @var{attr}, void * (*@var{start_routine})(void *), void * @var{arg})
@code{pthread_create} creates a new thread of control that executes
concurrently with the calling thread. The new thread calls the
function @var{start_routine}, passing it @var{arg} as first argument. The
new thread terminates either explicitly, by calling @code{pthread_exit},
or implicitly, by returning from the @var{start_routine} function. The
latter case is equivalent to calling @code{pthread_exit} with the result
returned by @var{start_routine} as exit code.

The @var{attr} argument specifies thread attributes to be applied to the
new thread. @xref{Thread Attributes}, for details. The @var{attr}
argument can also be @code{NULL}, in which case default attributes are
used: the created thread is joinable (not detached) and has an ordinary
(not realtime) scheduling policy.

On success, the identifier of the newly created thread is stored in the
location pointed by the @var{thread} argument, and a 0 is returned. On
error, a non-zero error code is returned.

This function may return the following errors:
@table @code
@item EAGAIN
Not enough system resources to create a process for the new thread,
or more than @code{PTHREAD_THREADS_MAX} threads are already active.
@end table
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun void pthread_exit (void *@var{retval})
@code{pthread_exit} terminates the execution of the calling thread.  All
cleanup handlers (@pxref{Cleanup Handlers}) that have been set for the
calling thread with @code{pthread_cleanup_push} are executed in reverse
order (the most recently pushed handler is executed first). Finalization
functions for thread-specific data are then called for all keys that
have non-@code{NULL} values associated with them in the calling thread
(@pxref{Thread-Specific Data}).  Finally, execution of the calling
thread is stopped.

The @var{retval} argument is the return value of the thread. It can be
retrieved from another thread using @code{pthread_join}.

The @code{pthread_exit} function never returns.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cancel (pthread_t @var{thread})

@code{pthread_cancel} sends a cancellation request to the thread denoted
by the @var{thread} argument.  If there is no such thread,
@code{pthread_cancel} fails and returns @code{ESRCH}.  Otherwise it
returns 0. @xref{Cancellation}, for details.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_join (pthread_t @var{th}, void **thread_@var{return})
@code{pthread_join} suspends the execution of the calling thread until
the thread identified by @var{th} terminates, either by calling
@code{pthread_exit} or by being canceled.

If @var{thread_return} is not @code{NULL}, the return value of @var{th}
is stored in the location pointed to by @var{thread_return}.  The return
value of @var{th} is either the argument it gave to @code{pthread_exit},
or @code{PTHREAD_CANCELED} if @var{th} was canceled.

The joined thread @code{th} must be in the joinable state: it must not
have been detached using @code{pthread_detach} or the
@code{PTHREAD_CREATE_DET