Update.

1998-07-10 18:14 -0400  Zack Weinberg  <zack@rabi.phys.columbia.edu>

	* manual/Makefile: Overhauled.  Generate libc.texinfo from the
	chapter files.  Exorcise the chapters, chapters-incl mess.
	Support inserting doc chapters from add-on modules.
	(chapters): New variable.
	(add-chapters): New variable.
	(appendices): New variable.
	(libc.texinfo): New target.
	(clean): Fix bugs.
	(realclean): Fix bugs.

	* manual/texis.awk: New file.
	* manual/libc-texinfo.sh: New file.
	* manual/libc-texinfo.in: New file.

	* manual/conf.texi (top @node): Remove next pointer.
	* manual/lang.texi (top @node): Remove prev pointer.

	* manual/job.texi (top @node): Add explicit pointers.
	* manual/message.texi (top @node): Add explicit pointers.
	* manual/nss.texi (top @node): Add explicit pointers.
	* manual/process.texi (top @node): Add explicit pointers.
	* manual/startup.texi (top @node): Add explicit pointers.
	* manual/terminal.texi (top @node): Add explicit pointers.
	* manual/users.texi (top @node): Add explicit pointers.

	* manual/arith.texi: Add %MENU% tag.
	* manual/conf.texi: Add %MENU% tag.
	* manual/contrib.texi: Add %MENU% tag.
	* manual/ctype.texi: Add %MENU% tag.
	* manual/errno.texi: Add %MENU% tag.
	* manual/filesys.texi: Add %MENU% tag.
	* manual/header.texi: Add %MENU% tag.
	* manual/install.texi: Add %MENU% tag.
	* manual/intro.texi: Add %MENU% tag.
	* manual/io.texi: Add %MENU% tag.
	* manual/job.texi: Add %MENU% tag.
	* manual/lang.texi: Add %MENU% tag.
	* manual/llio.texi: Add %MENU% tag.
	* manual/locale.texi: Add %MENU% tag.
	* manual/maint.texi: Add %MENU% tag.
	* manual/math.texi: Add %MENU% tag.
	* manual/mbyte.texi: Add %MENU% tag.
	* manual/memory.texi: Add %MENU% tag.
	* manual/message.texi: Add %MENU% tag.
	* manual/nss.texi: Add %MENU% tag.
	* manual/pattern.texi: Add %MENU% tag.
	* manual/pipe.texi: Add %MENU% tag.
	* manual/process.texi: Add %MENU% tag.
	* manual/search.texi: Add %MENU% tag.
	* manual/setjmp.texi: Add %MENU% tag.
	* manual/signal.texi: Add %MENU% tag.
	* manual/socket.texi: Add %MENU% tag.
	* manual/startup.texi: Add %MENU% tag.
	* manual/stdio.texi: Add %MENU% tag.
	* manual/string.texi: Add %MENU% tag.
	* manual/sysinfo.texi: Add %MENU% tag.
	* manual/terminal.texi: Add %MENU% tag.
	* manual/time.texi: Add %MENU% tag.
	* manual/users.texi: Add %MENU% tag.

1998-07-13  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/unix/sysv/linux/i386/dl-procinfo.h (x86_cap_flags):
	Update.

1998-07-11  Andreas Jaeger  <aj@arthur.rhein-neckar.de>

	* sysdeps/unix/sysv/linux/recvmsg.c (__libc_recvmsg): Use ANSI
	style declaration to avoid warning.
	* sysdeps/unix/sysv/linux/sendmsg.c (__libc_sendmsg): Likewise.

1998-07-04  Mark Kettenis  <kettenis@phys.uva.nl>

	* elf/rtld.c (process_dl_debug): Add missing continue.

1998-07-12  Mark Kettenis  <kettenis@phys.uva.nl>

	* elf/rtld.c (_dl_skip_args): Make global because the Hurd startup
	code needs it.

1998-07-10  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* Makeconfig ($(common-objpfx)sysd-dirs): Write out definition of
	sysd-dirs-done.
	* Makerules: Don't generate version maps too early.
	($(common-objpfx)sysd-versions): Force regeneration if the list of
	subdirs has changed.

1998-07-10  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* elf/dlfcn.h (DL_CALL_FCT): Use portable comma expression.

1998-07-11  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* iconv/gconv_db.c (gen_steps): Always set *handle and *nsteps.
	* iconv/gconv_dl.c (__gconv_find_shlib): Correct use of tfind
	return value.

1998-07-12  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* elf/dl-open.c (dl_open_worker): New function.
	(_dl_open): Call it to do the actual work while catching errors.
	* elf/dl-close.c (_dl_close): Only call termination function if
	the initialisation function was called.

1998-07-13  Ulrich Drepper  <drepper@cygnus.com>

	* libio/libioP.h (_IO_cleanup_registration_needed): Use __PMT.
	Reported by Felix von Leitner <leitner@amdiv.de>.

1998-07-13 10:28  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>
	* elf/rtld.c (process_dl_debug): Add missing continue.

1998-06-23  Mark Kettenis  <kettenis@phys.uva.nl>

1 files changed, 1427 insertions, 0 deletions

diff --git a/linuxthreads/linuxthreads.texi b/linuxthreads/linuxthreads.texi
new file mode 100644
index 0000000000..dc1b14649a
--- /dev/null
+++ b/linuxthreads/linuxthreads.texi
@@ -0,0 +1,1427 @@
+@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
+                                  cancelled.
+* 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.
+* 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 cancelled.
+
+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 cancelled.
+
+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_setinheritsched
+@findex pthread_attr_setschedparam
+@findex pthread_attr_setschedpolicy
+@findex pthread_attr_setscope
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_attr_set@var{attr} (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_getinheritsched
+@findex pthread_attr_getschedparam
+@findex pthread_attr_getschedpolicy
+@findex pthread_attr_getscope
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_attr_get@var{attr} (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}.
+@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 cancelled 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 cancelled 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_defer_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