remove outdated manpages and README's for ld.so/linuxthreads

1 files changed, 0 insertions, 1627 deletions

diff --git a/libpthread/linuxthreads/linuxthreads.texi b/libpthread/linuxthreads/linuxthreads.texi
deleted file mode 100644
index 795fb7097..000000000
--- a/libpthread/linuxthreads/linuxthreads.texi
+++ /dev/null
@@ -1,1627 +0,0 @@
-@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_DETACHED} attribute to @code{pthread_create}.
-
-When a joinable thread terminates, its memory resources (thread
-descriptor and stack) are not deallocated until another thread performs
-@code{pthread_join} on it. Therefore, @code{pthread_join} must be called
-once for each joinable thread created to avoid memory leaks.
-
-At most one thread can wait for the termination of a given
-thread. Calling @code{pthread_join} on a thread @var{th} on which
-another thread is already waiting for termination returns an error.
-
-@code{pthread_join} is a cancellation point. If a thread is canceled
-while suspended in @code{pthread_join}, the thread execution resumes
-immediately and the cancellation is executed without waiting for the
-@var{th} thread to terminate. If cancellation occurs during
-@code{pthread_join}, the @var{th} thread remains not joined.
-
-On success, the return value of @var{th} is stored in the location
-pointed to by @var{thread_return}, and 0 is returned. On error, one of
-the following values is returned:
-@table @code
-@item ESRCH
-No thread could be found corresponding to that specified by @var{th}.
-@item EINVAL
-The @var{th} thread has been detached, or another thread is already
-waiting on termination of @var{th}.
-@item EDEADLK
-The @var{th} argument refers to the calling thread.
-@end table
-@end deftypefun
-
-@node Thread Attributes
-@section Thread Attributes
-
-@comment pthread.h
-@comment POSIX
-
-Threads have a number of attributes that may be set at creation time.
-This is done by filling a thread attribute object @var{attr} of type
-@code{pthread_attr_t}, then passing it as second argument to
-@code{pthread_create}. Passing @code{NULL} is equivalent to passing a
-thread attribute object with all attributes set to their default values.
-
-Attribute objects are consulted only when creating a new thread.  The
-same attribute object can be used for creating several threads.
-Modifying an attribute object after a call to @code{pthread_create} does
-not change the attributes of the thread previously created.
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_attr_init (pthread_attr_t *@var{attr})
-@code{pthread_attr_init} initializes the thread attribute object
-@var{attr} and fills it with default values for the attributes. (The
-default values are listed below for each attribute.)
-
-Each attribute @var{attrname} (see below for a list of all attributes)
-can be individually set using the function
-@code{pthread_attr_set@var{attrname}} and retrieved using the function
-@code{pthread_attr_get@var{attrname}}.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr})
-@code{pthread_attr_destroy} destroys the attribute object pointed to by
-@var{attr} releasing any resources associated with it.  @var{attr} is
-left in an undefined state, and you must not use it again in a call to
-any pthreads function until it has been reinitialized.
-@end deftypefun
-
-@findex pthread_attr_setdetachstate
-@findex pthread_attr_setguardsize
-@findex pthread_attr_setinheritsched
-@findex pthread_attr_setschedparam
-@findex pthread_attr_setschedpolicy
-@findex pthread_attr_setscope
-@findex pthread_attr_setstack
-@findex pthread_attr_setstackaddr
-@findex pthread_attr_setstacksize
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_attr_setattr (pthread_attr_t *@var{obj}, int @var{value})
-Set attribute @var{attr} to @var{value} in the attribute object pointed
-to by @var{obj}.  See below for a list of possible attributes and the
-values they can take.
-
-On success, these functions return 0.  If @var{value} is not meaningful
-for the @var{attr} being modified, they will return the error code
-@code{EINVAL}.  Some of the functions have other failure modes; see
-below.
-@end deftypefun
-
-@findex pthread_attr_getdetachstate
-@findex pthread_attr_getguardsize
-@findex pthread_attr_getinheritsched
-@findex pthread_attr_getschedparam
-@findex pthread_attr_getschedpolicy
-@findex pthread_attr_getscope
-@findex pthread_attr_getstack
-@findex pthread_attr_getstackaddr
-@findex pthread_attr_getstacksize
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_attr_getattr (const pthread_attr_t *@var{obj}, int *@var{value})
-Store the current setting of @var{attr} in @var{obj} into the variable
-pointed to by @var{value}.
-
-These functions always return 0.
-@end deftypefun
-
-The following thread attributes are supported:
-@table @samp
-@item detachstate
-Choose whether the thread is created in the joinable state (value
-@code{PTHREAD_CREATE_JOINABLE}) or in the detached state
-(@code{PTHREAD_CREATE_DETACHED}).  The default is
-@code{PTHREAD_CREATE_JOINABLE}.
-
-In the joinable state, another thread can synchronize on the thread
-termination and recover its termination code using @code{pthread_join},
-but some of the thread resources are kept allocated after the thread
-terminates, and reclaimed only when another thread performs
-@code{pthread_join} on that thread.
-
-In the detached state, the thread resources are immediately freed when
-it terminates, but @code{pthread_join} cannot be used to synchronize on
-the thread termination.
-
-A thread created in the joinable state can later be put in the detached
-thread using @code{pthread_detach}.
-
-@item schedpolicy
-Select the scheduling policy for the thread: one of @code{SCHED_OTHER}
-(regular, non-realtime scheduling), @code{SCHED_RR} (realtime,
-round-robin) or @code{SCHED_FIFO} (realtime, first-in first-out).
-The default is @code{SCHED_OTHER}.
-@c Not doc'd in our manual: FIXME.
-@c See @code{sched_setpolicy} for more information on scheduling policies.
-
-The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}
-are available only to processes with superuser privileges.
-@code{pthread_attr_setschedparam} will fail and return @code{ENOTSUP} if
-you try to set a realtime policy when you are unprivileged.
-
-The scheduling policy of a thread can be changed after creation with
-@code{pthread_setschedparam}.
-
-@item schedparam
-Change the scheduling parameter (the scheduling priority)
-for the thread.  The default is 0.
-
-This attribute is not significant if the scheduling policy is
-@code{SCHED_OTHER}; it only matters for the realtime policies
-@code{SCHED_RR} and @code{SCHED_FIFO}.
-
-The scheduling priority of a thread can be changed after creation with
-@code{pthread_setschedparam}.
-
-@item inheritsched
-Choose whether the scheduling policy and scheduling parameter for the
-newly created thread are determined by the values of the
-@var{schedpolicy} and @var{schedparam} attributes (value
-@code{PTHREAD_EXPLICIT_SCHED}) or are inherited from the parent thread
-(value @code{PTHREAD_INHERIT_SCHED}).  The default is
-@code{PTHREAD_EXPLICIT_SCHED}.
-
-@item scope
-Choose the scheduling contention scope for the created thread.  The
-default is @code{PTHREAD_SCOPE_SYSTEM}, meaning that the threads contend
-for CPU time with all processes running on the machine. In particular,
-thread priorities are interpreted relative to the priorities of all
-other processes on the machine. The other possibility,
-@code{PTHREAD_SCOPE_PROCESS}, means that scheduling contention occurs
-only between the threads of the running process: thread priorities are
-interpreted relative to the priorities of the other threads of the
-process, regardless of the priorities of other processes.
-
-@code{PTHREAD_SCOPE_PROCESS} is not supported in LinuxThreads.  If you
-try to set the scope to this value, @code{pthread_attr_setscope} will
-fail and return @code{ENOTSUP}.
-
-@item stackaddr
-Provide an address for an application managed stack.  The size of the
-stack must be at least @code{PTHREAD_STACK_MIN}.
-
-@item stacksize
-Change the size of the stack created for the thread.  The value defines
-the minimum stack size, in bytes.
-
-If the value exceeds the system's maximum stack size, or is smaller
-than @code{PTHREAD_STACK_MIN}, @code{pthread_attr_setstacksize} will
-fail and return @code{EINVAL}.
-
-@item stack
-Provide both the address and size of an application managed stack to
-use for the new thread.  The base of the memory area is @var{stackaddr}
-with the size of the memory area, @var{stacksize}, measured in bytes.
-
-If the value of @var{stacksize} is less than @code{PTHREAD_STACK_MIN},
-or greater than the system's maximum stack size, or if the value of
-@var{stackaddr} lacks the proper alignment, @code{pthread_attr_setstack}
-will fail and return @code{EINVAL}.
-
-@item guardsize
-Change the minimum size in bytes of the guard area for the thread's
-stack.  The default size is a single page.  If this value is set, it
-will be rounded up to the nearest page size.  If the value is set to 0,
-a guard area will not be created for this thread.  The space allocated
-for the guard area is used to catch stack overflow.  Therefore, when
-allocating large structures on the stack, a larger guard area may be
-required to catch a stack overflow.
-
-If the caller is managing their own stacks (if the @code{stackaddr}
-attribute has been set), then the @code{guardsize} attribute is ignored.
-
-If the value exceeds the @code{stacksize}, @code{pthread_atrr_setguardsize}
-will fail and return @code{EINVAL}.
-@end table
-
-@node Cancellation
-@section Cancellation
-
-Cancellation is the mechanism by which a thread can terminate the
-execution of another thread. More precisely, a thread can send a
-cancellation request to another thread. Depending on its settings, the
-target thread can then either ignore the request, honor it immediately,
-or defer it till it reaches a cancellation point.  When threads are
-first created by @code{pthread_create}, they always defer cancellation
-requests.
-
-When a thread eventually honors a cancellation request, it behaves as if
-@code{pthread_exit(PTHREAD_CANCELED)} was called.  All cleanup handlers
-are executed in reverse order, finalization functions for
-thread-specific data are called, and finally the thread stops executing.
-If the canceled thread was joinable, the return value
-@code{PTHREAD_CANCELED} is provided to whichever thread calls
-@var{pthread_join} on it. See @code{pthread_exit} for more information.
-
-Cancellation points are the points where the thread checks for pending
-cancellation requests and performs them.  The POSIX threads functions
-@code{pthread_join}, @code{pthread_cond_wait},
-@code{pthread_cond_timedwait}, @code{pthread_testcancel},
-@code{sem_wait}, and @code{sigwait} are cancellation points.  In
-addition, these system calls are cancellation points:
-
-@multitable @columnfractions .33 .33 .33
-@item @t{accept}	@tab @t{open}		@tab @t{sendmsg}
-@item @t{close}		@tab @t{pause}		@tab @t{sendto}
-@item @t{connect}	@tab @t{read}		@tab @t{system}
-@item @t{fcntl}		@tab @t{recv}		@tab @t{tcdrain}
-@item @t{fsync}		@tab @t{recvfrom}	@tab @t{wait}
-@item @t{lseek}		@tab @t{recvmsg}	@tab @t{waitpid}
-@item @t{msync}		@tab @t{send}		@tab @t{write}
-@item @t{nanosleep}
-@end multitable
-
-@noindent
-All library functions that call these functions (such as
-@code{printf}) are also cancellation points.
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_setcancelstate (int @var{state}, int *@var{oldstate})
-@code{pthread_setcancelstate} changes the cancellation state for the
-calling thread -- that is, whether cancellation requests are ignored or
-not. The @var{state} argument is the new cancellation state: either
-@code{PTHREAD_CANCEL_ENABLE} to enable cancellation, or
-@code{PTHREAD_CANCEL_DISABLE} to disable cancellation (cancellation
-requests are ignored).
-
-If @var{oldstate} is not @code{NULL}, the previous cancellation state is
-stored in the location pointed to by @var{oldstate}, and can thus be
-restored later by another call to @code{pthread_setcancelstate}.
-
-If the @var{state} argument is not @code{PTHREAD_CANCEL_ENABLE} or
-@code{PTHREAD_CANCEL_DISABLE}, @code{pthread_setcancelstate} fails and
-returns @code{EINVAL}.  Otherwise it returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_setcanceltype (int @var{type}, int *@var{oldtype})
-@code{pthread_setcanceltype} changes the type of responses to
-cancellation requests for the calling thread: asynchronous (immediate)
-or deferred.  The @var{type} argument is the new cancellation type:
-either @code{PTHREAD_CANCEL_ASYNCHRONOUS} to cancel the calling thread
-as soon as the cancellation request is received, or
-@code{PTHREAD_CANCEL_DEFERRED} to keep the cancellation request pending
-until the next cancellation point. If @var{oldtype} is not @code{NULL},
-the previous cancellation state is stored in the location pointed to by
-@var{oldtype}, and can thus be restored later by another call to
-@code{pthread_setcanceltype}.
-
-If the @var{type} argument is not @code{PTHREAD_CANCEL_DEFERRED} or
-@code{PTHREAD_CANCEL_ASYNCHRONOUS}, @code{pthread_setcanceltype} fails
-and returns @code{EINVAL}.  Otherwise it returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun void pthread_testcancel (@var{void})
-@code{pthread_testcancel} does nothing except testing for pending
-cancellation and executing it. Its purpose is to introduce explicit
-checks for cancellation in long sequences of code that do not call
-cancellation point functions otherwise.
-@end deftypefun
-
-@node Cleanup Handlers
-@section Cleanup Handlers
-
-Cleanup handlers are functions that get called when a thread terminates,
-either by calling @code{pthread_exit} or because of
-cancellation. Cleanup handlers are installed and removed following a
-stack-like discipline.
-
-The purpose of cleanup handlers is to free the resources that a thread
-may hold at the time it terminates. In particular, if a thread exits or
-is canceled while it owns a locked mutex, the mutex will remain locked
-forever and prevent other threads from executing normally. The best way
-to avoid this is, just before locking the mutex, to install a cleanup
-handler whose effect is to unlock the mutex. Cleanup handlers can be
-used similarly to free blocks allocated with @code{malloc} or close file
-descriptors on thread termination.
-
-Here is how to lock a mutex @var{mut} in such a way that it will be
-unlocked if the thread is canceled while @var{mut} is locked:
-
-@smallexample
-pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
-pthread_mutex_lock(&mut);
-/* do some work */
-pthread_mutex_unlock(&mut);
-pthread_cleanup_pop(0);
-@end smallexample
-
-Equivalently, the last two lines can be replaced by
-
-@smallexample
-pthread_cleanup_pop(1);
-@end smallexample
-
-Notice that the code above is safe only in deferred cancellation mode
-(see @code{pthread_setcanceltype}). In asynchronous cancellation mode, a
-cancellation can occur between @code{pthread_cleanup_push} and
-@code{pthread_mutex_lock}, or between @code{pthread_mutex_unlock} and
-@code{pthread_cleanup_pop}, resulting in both cases in the thread trying
-to unlock a mutex not locked by the current thread. This is the main
-reason why asynchronous cancellation is difficult to use.
-
-If the code above must also work in asynchronous cancellation mode,
-then it must switch to deferred mode for locking and unlocking the
-mutex:
-
-@smallexample
-pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
-pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
-pthread_mutex_lock(&mut);
-/* do some work */
-pthread_cleanup_pop(1);
-pthread_setcanceltype(oldtype, NULL);
-@end smallexample
-
-The code above can be rewritten in a more compact and efficient way,
-using the non-portable functions @code{pthread_cleanup_push_defer_np}
-and @code{pthread_cleanup_pop_restore_np}:
-
-@smallexample
-pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut);
-pthread_mutex_lock(&mut);
-/* do some work */
-pthread_cleanup_pop_restore_np(1);
-@end smallexample
-
-@comment pthread.h
-@comment POSIX
-@deftypefun void pthread_cleanup_push (void (*@var{routine}) (void *), void *@var{arg})
-
-@code{pthread_cleanup_push} installs the @var{routine} function with
-argument @var{arg} as a cleanup handler. From this point on to the
-matching @code{pthread_cleanup_pop}, the function @var{routine} will be
-called with arguments @var{arg} when the thread terminates, either
-through @code{pthread_exit} or by cancellation. If several cleanup
-handlers are active at that point, they are called in LIFO order: the
-most recently installed handler is called first.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun void pthread_cleanup_pop (int @var{execute})
-@code{pthread_cleanup_pop} removes the most recently installed cleanup
-handler. If the @var{execute} argument is not 0, it also executes the
-handler, by calling the @var{routine} function with arguments
-@var{arg}. If the @var{execute} argument is 0, the handler is only
-removed but not executed.
-@end deftypefun
-
-Matching pairs of @code{pthread_cleanup_push} and
-@code{pthread_cleanup_pop} must occur in the same function, at the same
-level of block nesting.  Actually, @code{pthread_cleanup_push} and
-@code{pthread_cleanup_pop} are macros, and the expansion of
-@code{pthread_cleanup_push} introduces an open brace @code{@{} with the
-matching closing brace @code{@}} being introduced by the expansion of the
-matching @code{pthread_cleanup_pop}.
-
-@comment pthread.h
-@comment GNU
-@deftypefun void pthread_cleanup_push_defer_np (void (*@var{routine}) (void *), void *@var{arg})
-@code{pthread_cleanup_push_defer_np} is a non-portable extension that
-combines @code{pthread_cleanup_push} and @code{pthread_setcanceltype}.
-It pushes a cleanup handler just as @code{pthread_cleanup_push} does,
-but also saves the current cancellation type and sets it to deferred
-cancellation. This ensures that the cleanup mechanism is effective even
-if the thread was initially in asynchronous cancellation mode.
-@end deftypefun
-
-@comment pthread.h
-@comment GNU
-@deftypefun void pthread_cleanup_pop_restore_np (int @var{execute})
-@code{pthread_cleanup_pop_restore_np} pops a cleanup handler introduced
-by @code{pthread_cleanup_push_defer_np}, and restores the cancellation
-type to its value at the time @code{pthread_cleanup_push_defer_np} was
-called.
-@end deftypefun
-
-@code{pthread_cleanup_push_defer_np} and
-@code{pthread_cleanup_pop_restore_np} must occur in matching pairs, at
-the same level of block nesting.
-
-The sequence
-
-@smallexample
-pthread_cleanup_push_defer_np(routine, arg);
-...
-pthread_cleanup_pop_restore_np(execute);
-@end smallexample
-
-@noindent
-is functionally equivalent to (but more compact and efficient than)
-
-@smallexample
-@{
-  int oldtype;
-  pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
-  pthread_cleanup_push(routine, arg);
-  ...
-  pthread_cleanup_pop(execute);
-  pthread_setcanceltype(oldtype, NULL);
-@}
-@end smallexample
-
-
-@node Mutexes
-@section Mutexes
-
-A mutex is a MUTual EXclusion device, and is useful for protecting
-shared data structures from concurrent modifications, and implementing
-critical sections and monitors.
-
-A mutex has two possible states: unlocked (not owned by any thread),
-and locked (owned by one thread). A mutex can never be owned by two
-different threads simultaneously. A thread attempting to lock a mutex
-that is already locked by another thread is suspended until the owning
-thread unlocks the mutex first.
-
-None of the mutex functions is a cancellation point, not even
-@code{pthread_mutex_lock}, in spite of the fact that it can suspend a
-thread for arbitrary durations. This way, the status of mutexes at
-cancellation points is predictable, allowing cancellation handlers to
-unlock precisely those mutexes that need to be unlocked before the
-thread stops executing. Consequently, threads using deferred
-cancellation should never hold a mutex for extended periods of time.
-
-It is not safe to call mutex functions from a signal handler.  In
-particular, calling @code{pthread_mutex_lock} or
-@code{pthread_mutex_unlock} from a signal handler may deadlock the
-calling thread.
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr})
-
-@code{pthread_mutex_init} initializes the mutex object pointed to by
-@var{mutex} according to the mutex attributes specified in @var{mutexattr}.
-If @var{mutexattr} is @code{NULL}, default attributes are used instead.
-
-The LinuxThreads implementation supports only one mutex attribute,
-the @var{mutex type}, which is either ``fast'', ``recursive'', or
-``error checking''. The type of a mutex determines whether
-it can be locked again by a thread that already owns it.
-The default type is ``fast''.
-
-Variables of type @code{pthread_mutex_t} can also be initialized
-statically, using the constants @code{PTHREAD_MUTEX_INITIALIZER} (for
-timed mutexes), @code{PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP} (for
-recursive mutexes), @code{PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP}
-(for fast mutexes(, and @code{PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP}
-(for error checking mutexes).
-
-@code{pthread_mutex_init} always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_lock (pthread_mutex_t *mutex))
-@code{pthread_mutex_lock} locks the given mutex. If the mutex is
-currently unlocked, it becomes locked and owned by the calling thread,
-and @code{pthread_mutex_lock} returns immediately. If the mutex is
-already locked by another thread, @code{pthread_mutex_lock} suspends the
-calling thread until the mutex is unlocked.
-
-If the mutex is already locked by the calling thread, the behavior of
-@code{pthread_mutex_lock} depends on the type of the mutex. If the mutex
-is of the ``fast'' type, the calling thread is suspended.  It will
-remain suspended forever, because no other thread can unlock the mutex.
-If  the mutex is of the ``error checking'' type, @code{pthread_mutex_lock}
-returns immediately with the error code @code{EDEADLK}.  If the mutex is
-of the ``recursive'' type, @code{pthread_mutex_lock} succeeds and
-returns immediately, recording the number of times the calling thread
-has locked the mutex. An equal number of @code{pthread_mutex_unlock}
-operations must be performed before the mutex returns to the unlocked
-state.
-@c This doesn't discuss PTHREAD_MUTEX_TIMED_NP mutex attributes. FIXME
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex})
-@code{pthread_mutex_trylock} behaves identically to
-@code{pthread_mutex_lock}, except that it does not block the calling
-thread if the mutex is already locked by another thread (or by the
-calling thread in the case of a ``fast'' mutex). Instead,
-@code{pthread_mutex_trylock} returns immediately with the error code
-@code{EBUSY}.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
-The @code{pthread_mutex_timedlock} is similar to the
-@code{pthread_mutex_lock} function but instead of blocking for in
-indefinite time if the mutex is locked by another thread, it returns
-when the time specified in @var{abstime} is reached.
-
-This function can only be used on standard (``timed'') and ``error
-checking'' mutexes.  It behaves just like @code{pthread_mutex_lock} for
-all other types.
-
-If the mutex is successfully locked, the function returns zero.  If the
-time specified in @var{abstime} is reached without the mutex being locked,
-@code{ETIMEDOUT} is returned.
-
-This function was introduced in the POSIX.1d revision of the POSIX standard.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex})
-@code{pthread_mutex_unlock} unlocks the given mutex. The mutex is
-assumed to be locked and owned by the calling thread on entrance to
-@code{pthread_mutex_unlock}. If the mutex is of the ``fast'' type,
-@code{pthread_mutex_unlock} always returns it to the unlocked state. If
-it is of the ``recursive'' type, it decrements the locking count of the
-mutex (number of @code{pthread_mutex_lock} operations performed on it by
-the calling thread), and only when this count reaches zero is the mutex
-actually unlocked.
-
-On ``error checking'' mutexes, @code{pthread_mutex_unlock} actually
-checks at run-time that the mutex is locked on entrance, and that it was
-locked by the same thread that is now calling
-@code{pthread_mutex_unlock}.  If these conditions are not met,
-@code{pthread_mutex_unlock} returns @code{EPERM}, and the mutex remains
-unchanged.  ``Fast'' and ``recursive'' mutexes perform no such checks,
-thus allowing a locked mutex to be unlocked by a thread other than its
-owner. This is non-portable behavior and must not be relied upon.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex})
-@code{pthread_mutex_destroy} destroys a mutex object, freeing the
-resources it might hold. The mutex must be unlocked on entrance. In the
-LinuxThreads implementation, no resources are associated with mutex
-objects, thus @code{pthread_mutex_destroy} actually does nothing except
-checking that the mutex is unlocked.
-
-If the mutex is locked by some thread, @code{pthread_mutex_destroy}
-returns @code{EBUSY}.  Otherwise it returns 0.
-@end deftypefun
-
-If any of the above functions (except @code{pthread_mutex_init})
-is applied to an uninitialized mutex, they will simply return
-@code{EINVAL} and do nothing.
-
-A shared global variable @var{x} can be protected by a mutex as follows:
-
-@smallexample
-int x;
-pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
-@end smallexample
-
-All accesses and modifications to @var{x} should be bracketed by calls to
-@code{pthread_mutex_lock} and @code{pthread_mutex_unlock} as follows:
-
-@smallexample
-pthread_mutex_lock(&mut);
-/* operate on x */
-pthread_mutex_unlock(&mut);
-@end smallexample
-
-Mutex attributes can be specified at mutex creation time, by passing a
-mutex attribute object as second argument to @code{pthread_mutex_init}.
-Passing @code{NULL} is equivalent to passing a mutex attribute object
-with all attributes set to their default values.
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutexattr_init (pthread_mutexattr_t *@var{attr})
-@code{pthread_mutexattr_init} initializes the mutex attribute object
-@var{attr} and fills it with default values for the attributes.
-
-This function always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr})
-@code{pthread_mutexattr_destroy} destroys a mutex attribute object,
-which must not be reused until it is
-reinitialized. @code{pthread_mutexattr_destroy} does nothing in the
-LinuxThreads implementation.
-
-This function always returns 0.
-@end deftypefun
-
-LinuxThreads supports only one mutex attribute: the mutex type, which is
-either @code{PTHREAD_MUTEX_ADAPTIVE_NP} for ``fast'' mutexes,
-@code{PTHREAD_MUTEX_RECURSIVE_NP} for ``recursive'' mutexes,
-@code{PTHREAD_MUTEX_TIMED_NP} for ``timed'' mutexes, or
-@code{PTHREAD_MUTEX_ERRORCHECK_NP} for ``error checking'' mutexes.  As
-the @code{NP} suffix indicates, this is a non-portable extension to the
-POSIX standard and should not be employed in portable programs.
-
-The mutex type determines what happens if a thread attempts to lock a
-mutex it already owns with @code{pthread_mutex_lock}. If the mutex is of
-the ``fast'' type, @code{pthread_mutex_lock} simply suspends the calling
-thread forever.  If the mutex is of the ``error checking'' type,
-@code{pthread_mutex_lock} returns immediately with the error code
-@code{EDEADLK}.  If the mutex is of the ``recursive'' type, the call to
-@code{pthread_mutex_lock} returns immediately with a success return
-code. The number of times the thread owning the mutex has locked it is
-recorded in the mutex. The owning thread must call
-@code{pthread_mutex_unlock} the same number of times before the mutex
-returns to the unlocked state.
-
-The default mutex type is ``timed'', that is, @code{PTHREAD_MUTEX_TIMED_NP}.
-@c This doesn't describe how a ``timed'' mutex behaves. FIXME
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutexattr_settype (pthread_mutexattr_t *@var{attr}, int @var{type})
-@code{pthread_mutexattr_settype} sets the mutex type attribute in
-@var{attr} to the value specified by @var{type}.
-
-If @var{type} is not @code{PTHREAD_MUTEX_ADAPTIVE_NP},
-@code{PTHREAD_MUTEX_RECURSIVE_NP}, @code{PTHREAD_MUTEX_TIMED_NP}, or
-@code{PTHREAD_MUTEX_ERRORCHECK_NP}, this function will return
-@code{EINVAL} and leave @var{attr} unchanged.
-
-The standard Unix98 identifiers @code{PTHREAD_MUTEX_DEFAULT},
-@code{PTHREAD_MUTEX_NORMAL}, @code{PTHREAD_MUTEX_RECURSIVE},
-and @code{PTHREAD_MUTEX_ERRORCHECK} are also permitted.
-
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_mutexattr_gettype (const pthread_mutexattr_t *@var{attr}, int *@var{type})
-@code{pthread_mutexattr_gettype} retrieves the current value of the
-mutex type attribute in @var{attr} and stores it in the location pointed
-to by @var{type}.
-
-This function always returns 0.
-@end deftypefun
-
-@node Condition Variables
-@section Condition Variables
-
-A condition (short for ``condition variable'') is a synchronization
-device that allows threads to suspend execution until some predicate on
-shared data is satisfied. The basic operations on conditions are: signal
-the condition (when the predicate becomes true), and wait for the
-condition, suspending the thread execution until another thread signals
-the condition.
-
-A condition variable must always be associated with a mutex, to avoid
-the race condition where a thread prepares to wait on a condition
-variable and another thread signals the condition just before the first
-thread actually waits on it.
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_init (pthread_cond_t *@var{cond}, pthread_condattr_t *cond_@var{attr})
-
-@code{pthread_cond_init} initializes the condition variable @var{cond},
-using the condition attributes specified in @var{cond_attr}, or default
-attributes if @var{cond_attr} is @code{NULL}. The LinuxThreads
-implementation supports no attributes for conditions, hence the
-@var{cond_attr} parameter is actually ignored.
-
-Variables of type @code{pthread_cond_t} can also be initialized
-statically, using the constant @code{PTHREAD_COND_INITIALIZER}.
-
-This function always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_signal (pthread_cond_t *@var{cond})
-@code{pthread_cond_signal} restarts one of the threads that are waiting
-on the condition variable @var{cond}. If no threads are waiting on
-@var{cond}, nothing happens. If several threads are waiting on
-@var{cond}, exactly one is restarted, but it is not specified which.
-
-This function always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_broadcast (pthread_cond_t *@var{cond})
-@code{pthread_cond_broadcast} restarts all the threads that are waiting
-on the condition variable @var{cond}. Nothing happens if no threads are
-waiting on @var{cond}.
-
-This function always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_wait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex})
-@code{pthread_cond_wait} atomically unlocks the @var{mutex} (as per
-@code{pthread_unlock_mutex}) and waits for the condition variable
-@var{cond} to be signaled. The thread execution is suspended and does
-not consume any CPU time until the condition variable is signaled. The
-@var{mutex} must be locked by the calling thread on entrance to
-@code{pthread_cond_wait}. Before returning to the calling thread,
-@code{pthread_cond_wait} re-acquires @var{mutex} (as per
-@code{pthread_lock_mutex}).
-
-Unlocking the mutex and suspending on the condition variable is done
-atomically. Thus, if all threads always acquire the mutex before
-signaling the condition, this guarantees that the condition cannot be
-signaled (and thus ignored) between the time a thread locks the mutex
-and the time it waits on the condition variable.
-
-This function always returns 0.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_timedwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
-@code{pthread_cond_timedwait} atomically unlocks @var{mutex} and waits
-on @var{cond}, as @code{pthread_cond_wait} does, but it also bounds the
-duration of the wait. If @var{cond} has not been signaled before time
-@var{abstime}, the mutex @var{mutex} is re-acquired and
-@code{pthread_cond_timedwait} returns the error code @code{ETIMEDOUT}.
-The wait can also be interrupted by a signal; in that case
-@code{pthread_cond_timedwait} returns @code{EINTR}.
-
-The @var{abstime} parameter specifies an absolute time, with the same
-origin as @code{time} and @code{gettimeofday}: an @var{abstime} of 0
-corresponds to 00:00:00 GMT, January 1, 1970.
-@end deftypefun
-
-@comment pthread.h
-@comment POSIX
-@deftypefun int pthread_cond_destroy (pthread_cond_t *@var{cond})
-@code{pthread_cond_destroy} destroys the condition variable @var{cond},
-freeing the resources it might hold.  If any threads are waiting on the
-condition variable, @code{pthread_cond_destroy} leaves @var{cond}
-untouched and returns @code{EBUSY}.  Otherwise it re