r2489 - in glibc-doc-reference/trunk: debian manual
Author: aurel32
Date: 2007-08-01 05:52:43 +0000 (Wed, 01 Aug 2007)
New Revision: 2489
Added:
glibc-doc-reference/trunk/manual/linuxthreads.texi
Modified:
glibc-doc-reference/trunk/debian/README.source
glibc-doc-reference/trunk/debian/changelog
glibc-doc-reference/trunk/debian/copyright
glibc-doc-reference/trunk/manual/Makefile
glibc-doc-reference/trunk/manual/argp.texi
glibc-doc-reference/trunk/manual/charset.texi
glibc-doc-reference/trunk/manual/conf.texi
glibc-doc-reference/trunk/manual/errno.texi
glibc-doc-reference/trunk/manual/filesys.texi
glibc-doc-reference/trunk/manual/lang.texi
glibc-doc-reference/trunk/manual/maint.texi
glibc-doc-reference/trunk/manual/memory.texi
glibc-doc-reference/trunk/manual/message.texi
glibc-doc-reference/trunk/manual/resource.texi
glibc-doc-reference/trunk/manual/search.texi
glibc-doc-reference/trunk/manual/signal.texi
glibc-doc-reference/trunk/manual/startup.texi
glibc-doc-reference/trunk/manual/stdio.texi
glibc-doc-reference/trunk/manual/string.texi
glibc-doc-reference/trunk/manual/sysinfo.texi
glibc-doc-reference/trunk/manual/syslog.texi
glibc-doc-reference/trunk/manual/time.texi
Log:
Sync with debian package + new upstream version
Modified: glibc-doc-reference/trunk/debian/README.source
===================================================================
--- glibc-doc-reference/trunk/debian/README.source 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/debian/README.source 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1,6 +1,6 @@
glibc-doc-reference_<version>.orig.tar.gz contains the glibc-<version>/manual
directory of upstream http://ftp.gnu.org/gnu/glibc/glibc-<version>.tar.bz2
It has been created with the following commands:
- bzip2 -c -d glibc-2.5.tar.bz2 |\
- tarcust -x 'glibc-2.5/(?!manual).*' |\
- gzip -9 > glibc-doc-reference_2.5.orig.tar.gz
+ bzip2 -c -d glibc-2.6.1.tar.bz2 |\
+ tarcust -x 'glibc-2.6.1/(?!manual).*' |\
+ gzip -9 > glibc-doc-reference_2.6.1.orig.tar.gz
Modified: glibc-doc-reference/trunk/debian/changelog
===================================================================
--- glibc-doc-reference/trunk/debian/changelog 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/debian/changelog 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1,3 +1,22 @@
+glibc-doc-reference (2.6.1-1) unstable; urgency=low
+
+ * New upstream version.
+
+ -- Aurelien Jarno <aurel32@debian.org> Wed, 01 Aug 2007 07:45:17 +0200
+
+glibc-doc-reference (2.6-2) unstable; urgency=low
+
+ * Upload to unstable.
+
+ -- Aurelien Jarno <aurel32@debian.org> Tue, 10 Jul 2007 09:31:24 +0200
+
+glibc-doc-reference (2.6-1) experimental; urgency=low
+
+ * New upstream version.
+ * Add linuxthreads documentation (closes: bug#426558).
+
+ -- Aurelien Jarno <aurel32@debian.org> Wed, 30 May 2007 15:21:37 +0200
+
glibc-doc-reference (2.5-2) unstable; urgency=low
* Upload to unstable (closes: bug#418893).
Modified: glibc-doc-reference/trunk/debian/copyright
===================================================================
--- glibc-doc-reference/trunk/debian/copyright 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/debian/copyright 2007-08-01 05:52:43 UTC (rev 2489)
@@ -5,12 +5,12 @@
repackaged by the GNU Libc Maintainers <debian-glibc@lists.debian.org> from the
following source:
- <ftp://sources.redhat.com/pub/glibc/releases/glibc-2.5.tar.bz2>
+ <ftp://sources.redhat.com/pub/glibc/releases/glibc-2.6.1.tar.bz2>
The following applies to the GNU C Library Reference Manual (libc.info):
- Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2006 Free
- Software Foundation, Inc.
+ Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
+ 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
Modified: glibc-doc-reference/trunk/manual/Makefile
===================================================================
--- glibc-doc-reference/trunk/manual/Makefile 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/Makefile 2007-08-01 05:52:43 UTC (rev 2489)
@@ -58,7 +58,7 @@
pipe socket terminal syslog math arith time \
resource setjmp signal startup process job nss \
users sysinfo conf crypt debug)
-add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
+add-chapters = linuxthreads.texi
appendices = lang.texi header.texi install.texi maint.texi contrib.texi \
freemanuals.texi
Modified: glibc-doc-reference/trunk/manual/argp.texi
===================================================================
--- glibc-doc-reference/trunk/manual/argp.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/argp.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -832,7 +832,7 @@
@item ARGP_LONG_ONLY
Use the gnu getopt `long-only' rules for parsing arguments. This allows
long-options to be recognized with only a single @samp{-}
-(i.e. @samp{-help}). This results in a less useful interface, and its
+(i.e., @samp{-help}). This results in a less useful interface, and its
use is discouraged as it conflicts with the way most GNU programs work
as well as the GNU coding standards.
Modified: glibc-doc-reference/trunk/manual/charset.texi
===================================================================
--- glibc-doc-reference/trunk/manual/charset.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/charset.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -207,7 +207,7 @@
than one byte, they are effected by byte-ordering. Thus, machines with
different endianesses would see different values when accessing the same
data. This byte ordering concern also applies for communication protocols
-that are all byte-based and, thereforet require that the sender has to
+that are all byte-based and therefore require that the sender has to
decide about splitting the wide character in bytes. A last (but not least
important) point is that wide characters often require more storage space
than a customized byte-oriented character set.
@@ -737,7 +737,7 @@
multibyte character, the number of bytes belonging to this multibyte
character byte sequence is returned.
-If the the first @var{n} bytes possibly form a valid multibyte
+If the first @var{n} bytes possibly form a valid multibyte
character but the character is incomplete, the return value is
@code{(size_t) -2}. Otherwise the multibyte character sequence is invalid
and the return value is @code{(size_t) -1}.
@@ -2231,7 +2231,7 @@
same as the one required for UCS-4. This is done for performance reasons
as one does not want to perform unnecessary byte-swapping operations if
one is not interested in actually seeing the result in UCS-4. To avoid
-trouble with endianess, the internal representation consistently is named
+trouble with endianness, the internal representation consistently is named
@code{INTERNAL} even on big-endian systems where the representations are
identical.
Modified: glibc-doc-reference/trunk/manual/conf.texi
===================================================================
--- glibc-doc-reference/trunk/manual/conf.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/conf.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1455,11 +1455,6 @@
Inquire about the value of @code{_POSIX_PRIO_IO}.
@comment unistd.h
-@comment POSIX.1g
-@item _PC_SOCK_MAXBUF
-Inquire about the value of @code{_POSIX_PIPE_BUF}.
-
-@comment unistd.h
@comment LFS
@item _PC_FILESIZEBITS
Inquire about the availability of large files on the filesystem.
Modified: glibc-doc-reference/trunk/manual/errno.texi
===================================================================
--- glibc-doc-reference/trunk/manual/errno.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/errno.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1434,7 +1434,7 @@
arguments required for the format can follow the @var{format} parameter.
Just like @code{perror}, @code{error} also can report an error code in
textual form. But unlike @code{perror} the error value is explicitly
-passed to the function in the @var{errnum} parameter. This elimintates
+passed to the function in the @var{errnum} parameter. This eliminates
the problem mentioned above that the error reporting function must be
called immediately after the function causing the error since otherwise
@code{errno} might have a different value.
@@ -1479,7 +1479,7 @@
If the global variable @code{error_one_per_line} is set to a non-zero
value @code{error_at_line} will avoid printing consecutive messages for
-the same file anem line. Repetition which are not directly following
+the same file and line. Repetition which are not directly following
each other are not caught.
Just like @code{error} this function only returned if @var{status} is
Modified: glibc-doc-reference/trunk/manual/filesys.texi
===================================================================
--- glibc-doc-reference/trunk/manual/filesys.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/filesys.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -131,7 +131,7 @@
@comment GNU
@deftypefun {char *} get_current_dir_name (void)
@vindex PWD
-This @code{get_current_dir_name} function is bascially equivalent to
+This @code{get_current_dir_name} function is basically equivalent to
@w{@code{getcwd (NULL, 0)}}. The only difference is that the value of
the @code{PWD} variable is returned if this value is correct. This is a
subtle difference which is visible if the path described by the
@@ -917,7 +917,7 @@
the return value of @code{ftw}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
-32-bit system this function is in fact @code{ftw64}, i.e. the LFS
+32-bit system this function is in fact @code{ftw64}, i.e., the LFS
interface transparently replaces the old interface.
@end deftypefun
@@ -990,7 +990,7 @@
then that value is returned.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
-32-bit system this function is in fact @code{nftw64}, i.e. the LFS
+32-bit system this function is in fact @code{nftw64}, i.e., the LFS
interface transparently replaces the old interface.
@end deftypefun
@@ -1434,7 +1434,7 @@
One useful feature of @code{rename} is that the meaning of @var{newname}
changes ``atomically'' from any previously existing file by that name to
-its new meaning (i.e. the file that was called @var{oldname}). There is
+its new meaning (i.e., the file that was called @var{oldname}). There is
no instant at which @var{newname} is non-existent ``in between'' the old
meaning and the new meaning. If there is a system crash during the
operation, it is possible for both names to still exist; but
@@ -3104,7 +3104,7 @@
This function is reentrant.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
-32-bit system this function is in fact @code{tmpfile64}, i.e. the LFS
+32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS
interface transparently replaces the old interface.
@end deftypefun
Modified: glibc-doc-reference/trunk/manual/lang.texi
===================================================================
--- glibc-doc-reference/trunk/manual/lang.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/lang.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1274,7 +1274,7 @@
@comment ISO
@deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
This expands to a integer constant expression that is the offset of the
-structure member named @var{member} in a the structure type @var{type}.
+structure member named @var{member} in the structure type @var{type}.
For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
of the member @code{elem} in a @code{struct s}.
Added: glibc-doc-reference/trunk/manual/linuxthreads.texi
===================================================================
--- glibc-doc-reference/trunk/manual/linuxthreads.texi (rev 0)
+++ glibc-doc-reference/trunk/manual/linuxthreads.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -0,0 +1,1627 @@
+@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 *@var{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 returns 0, and
+@var{cond} must not be used again until it is reinitialized.
+
+In the LinuxThreads implementation, no resources are associated with
+condition variables, so @code{pthread_cond_destroy} actually does
+nothing.
+@end deftypefun
+
+@code{pthread_cond_wait} and @code{pthread_cond_timedwait} are
+cancellation points. If a thread is canceled while suspended in one of
+these functions, the thread immediately resumes execution, relocks the
+mutex specified by @var{mutex}, and finally executes the cancellation.
+Consequently, cleanup handlers are assured that @var{mutex} is locked
+when they are called.
+
+It is not safe to call the condition variable functions from a signal
+handler. In particular, calling @code{pthread_cond_signal} or
+@code{pthread_cond_broadcast} from a signal handler may deadlock the
+calling thread.
+
+Consider two shared variables @var{x} and @var{y}, protected by the
+mutex @var{mut}, and a condition variable @var{cond} that is to be
+signaled whenever @var{x} becomes greater than @var{y}.
+
+@smallexample
+int x,y;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
+@end smallexample
+
+Waiting until @var{x} is greater than @var{y} is performed as follows:
+
+@smallexample
+pthread_mutex_lock(&mut);
+while (x <= y) @{
+ pthread_cond_wait(&cond, &mut);
+@}
+/* operate on x and y */
+pthread_mutex_unlock(&mut);
+@end smallexample
+
+Modifications on @var{x} and @var{y} that may cause @var{x} to become greater than
+@var{y} should signal the condition if needed:
+
+@smallexample
+pthread_mutex_lock(&mut);
+/* modify x and y */
+if (x > y) pthread_cond_broadcast(&cond);
+pthread_mutex_unlock(&mut);
+@end smallexample
+
+If it can be proved that at most one waiting thread needs to be waken
+up (for instance, if there are only two threads communicating through
+@var{x} and @var{y}), @code{pthread_cond_signal} can be used as a slightly more
+efficient alternative to @code{pthread_cond_broadcast}. In doubt, use
+@code{pthread_cond_broadcast}.
+
+To wait for @var{x} to becomes greater than @var{y} with a timeout of 5
+seconds, do:
+
+@smallexample
+struct timeval now;
+struct timespec timeout;
+int retcode;
+
+pthread_mutex_lock(&mut);
+gettimeofday(&now);
+timeout.tv_sec = now.tv_sec + 5;
+timeout.tv_nsec = now.tv_usec * 1000;
+retcode = 0;
+while (x <= y && retcode != ETIMEDOUT) @{
+ retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
+@}
+if (retcode == ETIMEDOUT) @{
+ /* timeout occurred */
+@} else @{
+ /* operate on x and y */
+@}
+pthread_mutex_unlock(&mut);
+@end smallexample
+
+Condition attributes can be specified at condition creation time, by
+passing a condition attribute object as second argument to
+@code{pthread_cond_init}. Passing @code{NULL} is equivalent to passing
+a condition attribute object with all attributes set to their default
+values.
+
+The LinuxThreads implementation supports no attributes for
+conditions. The functions on condition attributes are included only for
+compliance with the POSIX standard.
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_condattr_init (pthread_condattr_t *@var{attr})
+@deftypefunx int pthread_condattr_destroy (pthread_condattr_t *@var{attr})
+@code{pthread_condattr_init} initializes the condition attribute object
+@var{attr} and fills it with default values for the attributes.
+@code{pthread_condattr_destroy} destroys the condition attribute object
+@var{attr}.
+
+Both functions do nothing in the LinuxThreads implementation.
+
+@code{pthread_condattr_init} and @code{pthread_condattr_destroy} always
+return 0.
+@end deftypefun
+
+@node POSIX Semaphores
+@section POSIX Semaphores
+
+@vindex SEM_VALUE_MAX
+Semaphores are counters for resources shared between threads. The
+basic operations on semaphores are: increment the counter atomically,
+and wait until the counter is non-null and decrement it atomically.
+
+Semaphores have a maximum value past which they cannot be incremented.
+The macro @code{SEM_VALUE_MAX} is defined to be this maximum value. In
+the GNU C library, @code{SEM_VALUE_MAX} is equal to @code{INT_MAX}
+(@pxref{Range of Type}), but it may be much smaller on other systems.
+
+The pthreads library implements POSIX 1003.1b semaphores. These should
+not be confused with System V semaphores (@code{ipc}, @code{semctl} and
+@code{semop}).
+@c !!! SysV IPC is not doc'd at all in our manual
+
+All the semaphore functions and macros are defined in @file{semaphore.h}.
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
+@code{sem_init} initializes the semaphore object pointed to by
+@var{sem}. The count associated with the semaphore is set initially to
+@var{value}. The @var{pshared} argument indicates whether the semaphore
+is local to the current process (@var{pshared} is zero) or is to be
+shared between several processes (@var{pshared} is not zero).
+
+On success @code{sem_init} returns 0. On failure it returns -1 and sets
+@var{errno} to one of the following values:
+
+@table @code
+@item EINVAL
+@var{value} exceeds the maximal counter value @code{SEM_VALUE_MAX}
+
+@item ENOSYS
+@var{pshared} is not zero. LinuxThreads currently does not support
+process-shared semaphores. (This will eventually change.)
+@end table
+@end deftypefun
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_destroy (sem_t * @var{sem})
+@code{sem_destroy} destroys a semaphore object, freeing the resources it
+might hold. If any threads are waiting on the semaphore when
+@code{sem_destroy} is called, it fails and sets @var{errno} to
+@code{EBUSY}.
+
+In the LinuxThreads implementation, no resources are associated with
+semaphore objects, thus @code{sem_destroy} actually does nothing except
+checking that no thread is waiting on the semaphore. This will change
+when process-shared semaphores are implemented.
+@end deftypefun
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_wait (sem_t * @var{sem})
+@code{sem_wait} suspends the calling thread until the semaphore pointed
+to by @var{sem} has non-zero count. It then atomically decreases the
+semaphore count.
+
+@code{sem_wait} is a cancellation point. It always returns 0.
+@end deftypefun
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_trywait (sem_t * @var{sem})
+@code{sem_trywait} is a non-blocking variant of @code{sem_wait}. If the
+semaphore pointed to by @var{sem} has non-zero count, the count is
+atomically decreased and @code{sem_trywait} immediately returns 0. If
+the semaphore count is zero, @code{sem_trywait} immediately returns -1
+and sets errno to @code{EAGAIN}.
+@end deftypefun
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_post (sem_t * @var{sem})
+@code{sem_post} atomically increases the count of the semaphore pointed to
+by @var{sem}. This function never blocks.
+
+@c !!! This para appears not to agree with the code.
+On processors supporting atomic compare-and-swap (Intel 486, Pentium and
+later, Alpha, PowerPC, MIPS II, Motorola 68k, Ultrasparc), the
+@code{sem_post} function is can safely be called from signal handlers.
+This is the only thread synchronization function provided by POSIX
+threads that is async-signal safe. On the Intel 386 and earlier Sparc
+chips, the current LinuxThreads implementation of @code{sem_post} is not
+async-signal safe, because the hardware does not support the required
+atomic operations.
+
+@code{sem_post} always succeeds and returns 0, unless the semaphore
+count would exceed @code{SEM_VALUE_MAX} after being incremented. In
+that case @code{sem_post} returns -1 and sets @var{errno} to
+@code{EINVAL}. The semaphore count is left unchanged.
+@end deftypefun
+
+@comment semaphore.h
+@comment POSIX
+@deftypefun int sem_getvalue (sem_t * @var{sem}, int * @var{sval})
+@code{sem_getvalue} stores in the location pointed to by @var{sval} the
+current count of the semaphore @var{sem}. It always returns 0.
+@end deftypefun
+
+@node Thread-Specific Data
+@section Thread-Specific Data
+
+Programs often need global or static variables that have different
+values in different threads. Since threads share one memory space, this
+cannot be achieved with regular variables. Thread-specific data is the
+POSIX threads answer to this need.
+
+Each thread possesses a private memory block, the thread-specific data
+area, or TSD area for short. This area is indexed by TSD keys. The TSD
+area associates values of type @code{void *} to TSD keys. TSD keys are
+common to all threads, but the value associated with a given TSD key can
+be different in each thread.
+
+For concreteness, the TSD areas can be viewed as arrays of @code{void *}
+pointers, TSD keys as integer indices into these arrays, and the value
+of a TSD key as the value of the corresponding array element in the
+calling thread.
+
+When a thread is created, its TSD area initially associates @code{NULL}
+with all keys.
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*destr_function) (void *))
+@code{pthread_key_create} allocates a new TSD key. The key is stored in
+the location pointed to by @var{key}. There is a limit of
+@code{PTHREAD_KEYS_MAX} on the number of keys allocated at a given
+time. The value initially associated with the returned key is
+@code{NULL} in all currently executing threads.
+
+The @var{destr_function} argument, if not @code{NULL}, specifies a
+destructor function associated with the key. When a thread terminates
+via @code{pthread_exit} or by cancellation, @var{destr_function} is
+called on the value associated with the key in that thread. The
+@var{destr_function} is not called if a key is deleted with
+@code{pthread_key_delete} or a value is changed with
+@code{pthread_setspecific}. The order in which destructor functions are
+called at thread termination time is unspecified.
+
+Before the destructor function is called, the @code{NULL} value is
+associated with the key in the current thread. A destructor function
+might, however, re-associate non-@code{NULL} values to that key or some
+other key. To deal with this, if after all the destructors have been
+called for all non-@code{NULL} values, there are still some
+non-@code{NULL} values with associated destructors, then the process is
+repeated. The LinuxThreads implementation stops the process after
+@code{PTHREAD_DESTRUCTOR_ITERATIONS} iterations, even if some
+non-@code{NULL} values with associated descriptors remain. Other
+implementations may loop indefinitely.
+
+@code{pthread_key_create} returns 0 unless @code{PTHREAD_KEYS_MAX} keys
+have already been allocated, in which case it fails and returns
+@code{EAGAIN}.
+@end deftypefun
+
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_key_delete (pthread_key_t @var{key})
+@code{pthread_key_delete} deallocates a TSD key. It does not check
+whether non-@code{NULL} values are associated with that key in the
+currently executing threads, nor call the destructor function associated
+with the key.
+
+If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise
+it returns 0.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{pointer})
+@code{pthread_setspecific} changes the value associated with @var{key}
+in the calling thread, storing the given @var{pointer} instead.
+
+If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise
+it returns 0.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key})
+@code{pthread_getspecific} returns the value currently associated with
+@var{key} in the calling thread.
+
+If there is no such key @var{key}, it returns @code{NULL}.
+@end deftypefun
+
+The following code fragment allocates a thread-specific array of 100
+characters, with automatic reclaimation at thread exit:
+
+@smallexample
+/* Key for the thread-specific buffer */
+static pthread_key_t buffer_key;
+
+/* Once-only initialisation of the key */
+static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
+
+/* Allocate the thread-specific buffer */
+void buffer_alloc(void)
+@{
+ pthread_once(&buffer_key_once, buffer_key_alloc);
+ pthread_setspecific(buffer_key, malloc(100));
+@}
+
+/* Return the thread-specific buffer */
+char * get_buffer(void)
+@{
+ return (char *) pthread_getspecific(buffer_key);
+@}
+
+/* Allocate the key */
+static void buffer_key_alloc()
+@{
+ pthread_key_create(&buffer_key, buffer_destroy);
+@}
+
+/* Free the thread-specific buffer */
+static void buffer_destroy(void * buf)
+@{
+ free(buf);
+@}
+@end smallexample
+
+@node Threads and Signal Handling
+@section Threads and Signal Handling
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_sigmask (int @var{how}, const sigset_t *@var{newmask}, sigset_t *@var{oldmask})
+@code{pthread_sigmask} changes the signal mask for the calling thread as
+described by the @var{how} and @var{newmask} arguments. If @var{oldmask}
+is not @code{NULL}, the previous signal mask is stored in the location
+pointed to by @var{oldmask}.
+
+The meaning of the @var{how} and @var{newmask} arguments is the same as
+for @code{sigprocmask}. If @var{how} is @code{SIG_SETMASK}, the signal
+mask is set to @var{newmask}. If @var{how} is @code{SIG_BLOCK}, the
+signals specified to @var{newmask} are added to the current signal mask.
+If @var{how} is @code{SIG_UNBLOCK}, the signals specified to
+@var{newmask} are removed from the current signal mask.
+
+Recall that signal masks are set on a per-thread basis, but signal
+actions and signal handlers, as set with @code{sigaction}, are shared
+between all threads.
+
+The @code{pthread_sigmask} function returns 0 on success, and one of the
+following error codes on error:
+@table @code
+@item EINVAL
+@var{how} is not one of @code{SIG_SETMASK}, @code{SIG_BLOCK}, or @code{SIG_UNBLOCK}
+
+@item EFAULT
+@var{newmask} or @var{oldmask} point to invalid addresses
+@end table
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_kill (pthread_t @var{thread}, int @var{signo})
+@code{pthread_kill} sends signal number @var{signo} to the thread
+@var{thread}. The signal is delivered and handled as described in
+@ref{Signal Handling}.
+
+@code{pthread_kill} returns 0 on success, one of the following error codes
+on error:
+@table @code
+@item EINVAL
+@var{signo} is not a valid signal number
+
+@item ESRCH
+The thread @var{thread} does not exist (e.g. it has already terminated)
+@end table
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int sigwait (const sigset_t *@var{set}, int *@var{sig})
+@code{sigwait} suspends the calling thread until one of the signals in
+@var{set} is delivered to the calling thread. It then stores the number
+of the signal received in the location pointed to by @var{sig} and
+returns. The signals in @var{set} must be blocked and not ignored on
+entrance to @code{sigwait}. If the delivered signal has a signal handler
+function attached, that function is @emph{not} called.
+
+@code{sigwait} is a cancellation point. It always returns 0.
+@end deftypefun
+
+For @code{sigwait} to work reliably, the signals being waited for must be
+blocked in all threads, not only in the calling thread, since
+otherwise the POSIX semantics for signal delivery do not guarantee
+that it's the thread doing the @code{sigwait} that will receive the signal.
+The best way to achieve this is block those signals before any threads
+are created, and never unblock them in the program other than by
+calling @code{sigwait}.
+
+Signal handling in LinuxThreads departs significantly from the POSIX
+standard. According to the standard, ``asynchronous'' (external) signals
+are addressed to the whole process (the collection of all threads),
+which then delivers them to one particular thread. The thread that
+actually receives the signal is any thread that does not currently block
+the signal.
+
+In LinuxThreads, each thread is actually a kernel process with its own
+PID, so external signals are always directed to one particular thread.
+If, for instance, another thread is blocked in @code{sigwait} on that
+signal, it will not be restarted.
+
+The LinuxThreads implementation of @code{sigwait} installs dummy signal
+handlers for the signals in @var{set} for the duration of the
+wait. Since signal handlers are shared between all threads, other
+threads must not attach their own signal handlers to these signals, or
+alternatively they should all block these signals (which is recommended
+anyway).
+
+@node Threads and Fork
+@section Threads and Fork
+
+It's not intuitively obvious what should happen when a multi-threaded POSIX
+process calls @code{fork}. Not only are the semantics tricky, but you may
+need to write code that does the right thing at fork time even if that code
+doesn't use the @code{fork} function. Moreover, you need to be aware of
+interaction between @code{fork} and some library features like
+@code{pthread_once} and stdio streams.
+
+When @code{fork} is called by one of the threads of a process, it creates a new
+process which is copy of the calling process. Effectively, in addition to
+copying certain system objects, the function takes a snapshot of the memory
+areas of the parent process, and creates identical areas in the child.
+To make matters more complicated, with threads it's possible for two or more
+threads to concurrently call fork to create two or more child processes.
+
+The child process has a copy of the address space of the parent, but it does
+not inherit any of its threads. Execution of the child process is carried out
+by a new thread which returns from @code{fork} function with a return value of
+zero; it is the only thread in the child process. Because threads are not
+inherited across fork, issues arise. At the time of the call to @code{fork},
+threads in the parent process other than the one calling @code{fork} may have
+been executing critical regions of code. As a result, the child process may
+get a copy of objects that are not in a well-defined state. This potential
+problem affects all components of the program.
+
+Any program component which will continue being used in a child process must
+correctly handle its state during @code{fork}. For this purpose, the POSIX
+interface provides the special function @code{pthread_atfork} for installing
+pointers to handler functions which are called from within @code{fork}.
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_atfork (void (*@var{prepare})(void), void (*@var{parent})(void), void (*@var{child})(void))
+
+@code{pthread_atfork} registers handler functions to be called just
+before and just after a new process is created with @code{fork}. The
+@var{prepare} handler will be called from the parent process, just
+before the new process is created. The @var{parent} handler will be
+called from the parent process, just before @code{fork} returns. The
+@var{child} handler will be called from the child process, just before
+@code{fork} returns.
+
+@code{pthread_atfork} returns 0 on success and a non-zero error code on
+error.
+
+One or more of the three handlers @var{prepare}, @var{parent} and
+@var{child} can be given as @code{NULL}, meaning that no handler needs
+to be called at the corresponding point.
+
+@code{pthread_atfork} can be called several times to install several
+sets of handlers. At @code{fork} time, the @var{prepare} handlers are
+called in LIFO order (last added with @code{pthread_atfork}, first
+called before @code{fork}), while the @var{parent} and @var{child}
+handlers are called in FIFO order (first added, first called).
+
+If there is insufficient memory available to register the handlers,
+@code{pthread_atfork} fails and returns @code{ENOMEM}. Otherwise it
+returns 0.
+
+The functions @code{fork} and @code{pthread_atfork} must not be regarded as
+reentrant from the context of the handlers. That is to say, if a
+@code{pthread_atfork} handler invoked from within @code{fork} calls
+@code{pthread_atfork} or @code{fork}, the behavior is undefined.
+
+Registering a triplet of handlers is an atomic operation with respect to fork.
+If new handlers are registered at about the same time as a fork occurs, either
+all three handlers will be called, or none of them will be called.
+
+The handlers are inherited by the child process, and there is no
+way to remove them, short of using @code{exec} to load a new
+pocess image.
+
+@end deftypefun
+
+To understand the purpose of @code{pthread_atfork}, recall that
+@code{fork} duplicates the whole memory space, including mutexes in
+their current locking state, but only the calling thread: other threads
+are not running in the child process. The mutexes are not usable after
+the @code{fork} and must be initialized with @code{pthread_mutex_init}
+in the child process. This is a limitation of the current
+implementation and might or might not be present in future versions.
+
+To avoid this, install handlers with @code{pthread_atfork} as follows: have the
+@var{prepare} handler lock the mutexes (in locking order), and the
+@var{parent} handler unlock the mutexes. The @var{child} handler should reset
+the mutexes using @code{pthread_mutex_init}, as well as any other
+synchronization objects such as condition variables.
+
+Locking the global mutexes before the fork ensures that all other threads are
+locked out of the critical regions of code protected by those mutexes. Thus
+when @code{fork} takes a snapshot of the parent's address space, that snapshot
+will copy valid, stable data. Resetting the synchronization objects in the
+child process will ensure they are properly cleansed of any artifacts from the
+threading subsystem of the parent process. For example, a mutex may inherit
+a wait queue of threads waiting for the lock; this wait queue makes no sense
+in the child process. Initializing the mutex takes care of this.
+
+@node Streams and Fork
+@section Streams and Fork
+
+The GNU standard I/O library has an internal mutex which guards the internal
+linked list of all standard C FILE objects. This mutex is properly taken care
+of during @code{fork} so that the child receives an intact copy of the list.
+This allows the @code{fopen} function, and related stream-creating functions,
+to work correctly in the child process, since these functions need to insert
+into the list.
+
+However, the individual stream locks are not completely taken care of. Thus
+unless the multithreaded application takes special precautions in its use of
+@code{fork}, the child process might not be able to safely use the streams that
+it inherited from the parent. In general, for any given open stream in the
+parent that is to be used by the child process, the application must ensure
+that that stream is not in use by another thread when @code{fork} is called.
+Otherwise an inconsistent copy of the stream object be produced. An easy way to
+ensure this is to use @code{flockfile} to lock the stream prior to calling
+@code{fork} and then unlock it with @code{funlockfile} inside the parent
+process, provided that the parent's threads properly honor these locks.
+Nothing special needs to be done in the child process, since the library
+internally resets all stream locks.
+
+Note that the stream locks are not shared between the parent and child.
+For example, even if you ensure that, say, the stream @code{stdout} is properly
+treated and can be safely used in the child, the stream locks do not provide
+an exclusion mechanism between the parent and child. If both processes write
+to @code{stdout}, strangely interleaved output may result regardless of
+the explicit use of @code{flockfile} or implicit locks.
+
+Also note that these provisions are a GNU extension; other systems might not
+provide any way for streams to be used in the child of a multithreaded process.
+POSIX requires that such a child process confines itself to calling only
+asynchronous safe functions, which excludes much of the library, including
+standard I/O.
+
+@node Miscellaneous Thread Functions
+@section Miscellaneous Thread Functions
+
+@comment pthread.h
+@comment POSIX
+@deftypefun {pthread_t} pthread_self (@var{void})
+@code{pthread_self} returns the thread identifier for the calling thread.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_equal (pthread_t thread1, pthread_t thread2)
+@code{pthread_equal} determines if two thread identifiers refer to the same
+thread.
+
+A non-zero value is returned if @var{thread1} and @var{thread2} refer to
+the same thread. Otherwise, 0 is returned.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_detach (pthread_t @var{th})
+@code{pthread_detach} puts the thread @var{th} in the detached
+state. This guarantees that the memory resources consumed by @var{th}
+will be freed immediately when @var{th} terminates. However, this
+prevents other threads from synchronizing on the termination of @var{th}
+using @code{pthread_join}.
+
+A thread can be created initially in the detached state, using the
+@code{detachstate} attribute to @code{pthread_create}. In contrast,
+@code{pthread_detach} applies to threads created in the joinable state,
+and which need to be put in the detached state later.
+
+After @code{pthread_detach} completes, subsequent attempts to perform
+@code{pthread_join} on @var{th} will fail. If another thread is already
+joining the thread @var{th} at the time @code{pthread_detach} is called,
+@code{pthread_detach} does nothing and leaves @var{th} in the joinable
+state.
+
+On success, 0 is returned. On error, one of the following codes is
+returned:
+@table @code
+@item ESRCH
+No thread could be found corresponding to that specified by @var{th}
+@item EINVAL
+The thread @var{th} is already in the detached state
+@end table
+@end deftypefun
+
+@comment pthread.h
+@comment GNU
+@deftypefun void pthread_kill_other_threads_np (@var{void})
+@code{pthread_kill_other_threads_np} is a non-portable LinuxThreads extension.
+It causes all threads in the program to terminate immediately, except
+the calling thread which proceeds normally. It is intended to be
+called just before a thread calls one of the @code{exec} functions,
+e.g. @code{execve}.
+
+Termination of the other threads is not performed through
+@code{pthread_cancel} and completely bypasses the cancellation
+mechanism. Hence, the current settings for cancellation state and
+cancellation type are ignored, and the cleanup handlers are not
+executed in the terminated threads.
+
+According to POSIX 1003.1c, a successful @code{exec*} in one of the
+threads should automatically terminate all other threads in the program.
+This behavior is not yet implemented in LinuxThreads. Calling
+@code{pthread_kill_other_threads_np} before @code{exec*} achieves much
+of the same behavior, except that if @code{exec*} ultimately fails, then
+all other threads are already killed.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_once (pthread_once_t *once_@var{control}, void (*@var{init_routine}) (void))
+
+The purpose of @code{pthread_once} is to ensure that a piece of
+initialization code is executed at most once. The @var{once_control}
+argument points to a static or extern variable statically initialized
+to @code{PTHREAD_ONCE_INIT}.
+
+The first time @code{pthread_once} is called with a given
+@var{once_control} argument, it calls @var{init_routine} with no
+argument and changes the value of the @var{once_control} variable to
+record that initialization has been performed. Subsequent calls to
+@code{pthread_once} with the same @code{once_control} argument do
+nothing.
+
+If a thread is cancelled while executing @var{init_routine}
+the state of the @var{once_control} variable is reset so that
+a future call to @code{pthread_once} will call the routine again.
+
+If the process forks while one or more threads are executing
+@code{pthread_once} initialization routines, the states of their respective
+@var{once_control} variables will appear to be reset in the child process so
+that if the child calls @code{pthread_once}, the routines will be executed.
+
+@code{pthread_once} always returns 0.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_setschedparam (pthread_t target_@var{thread}, int @var{policy}, const struct sched_param *@var{param})
+
+@code{pthread_setschedparam} sets the scheduling parameters for the
+thread @var{target_thread} as indicated by @var{policy} and
+@var{param}. @var{policy} can be either @code{SCHED_OTHER} (regular,
+non-realtime scheduling), @code{SCHED_RR} (realtime, round-robin) or
+@code{SCHED_FIFO} (realtime, first-in first-out). @var{param} specifies
+the scheduling priority for the two realtime policies. 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.
+
+On success, @code{pthread_setschedparam} returns 0. On error it returns
+one of the following codes:
+@table @code
+@item EINVAL
+@var{policy} is not one of @code{SCHED_OTHER}, @code{SCHED_RR},
+@code{SCHED_FIFO}, or the priority value specified by @var{param} is not
+valid for the specified policy
+
+@item EPERM
+Realtime scheduling was requested but the calling process does not have
+sufficient privileges.
+
+@item ESRCH
+The @var{target_thread} is invalid or has already terminated
+
+@item EFAULT
+@var{param} points outside the process memory space
+@end table
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_getschedparam (pthread_t target_@var{thread}, int *@var{policy}, struct sched_param *@var{param})
+
+@code{pthread_getschedparam} retrieves the scheduling policy and
+scheduling parameters for the thread @var{target_thread} and stores them
+in the locations pointed to by @var{policy} and @var{param},
+respectively.
+
+@code{pthread_getschedparam} returns 0 on success, or one of the
+following error codes on failure:
+@table @code
+@item ESRCH
+The @var{target_thread} is invalid or has already terminated.
+
+@item EFAULT
+@var{policy} or @var{param} point outside the process memory space.
+
+@end table
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_setconcurrency (int @var{level})
+@code{pthread_setconcurrency} is unused in LinuxThreads due to the lack
+of a mapping of user threads to kernel threads. It exists for source
+compatibility. It does store the value @var{level} so that it can be
+returned by a subsequent call to @code{pthread_getconcurrency}. It takes
+no other action however.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_getconcurrency ()
+@code{pthread_getconcurrency} is unused in LinuxThreads due to the lack
+of a mapping of user threads to kernel threads. It exists for source
+compatibility. However, it will return the value that was set by the
+last call to @code{pthread_setconcurrency}.
+@end deftypefun
Modified: glibc-doc-reference/trunk/manual/maint.texi
===================================================================
--- glibc-doc-reference/trunk/manual/maint.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/maint.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -156,7 +156,7 @@
to look for a system-dependent version of a file that's not in
@file{generic}. This means that any system-dependent source file must
have an analogue in @file{generic}, even if the routines defined by that
-file are not implemented on other platforms. Second. the @file{generic}
+file are not implemented on other platforms. Second, the @file{generic}
version of a system-dependent file is used if the makefiles do not find
a version specific to the system you're compiling for.
Modified: glibc-doc-reference/trunk/manual/memory.texi
===================================================================
--- glibc-doc-reference/trunk/manual/memory.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/memory.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -31,7 +31,7 @@
There are a lot of different ways systems organize memory, but in a
typical one, each process has one linear virtual address space, with
addresses running from zero to some huge maximum. It need not be
-contiguous; i.e. not all of these addresses actually can be used to
+contiguous; i.e., not all of these addresses actually can be used to
store data.
The virtual memory is divided into pages (4 kilobytes is typical).
@@ -1065,7 +1065,7 @@
@item int keepcost
This is the size of the top-most releasable chunk that normally
-borders the end of the heap (i.e. the high end of the virtual address
+borders the end of the heap (i.e., the high end of the virtual address
space's data segment).
@end table
@@ -2407,7 +2407,7 @@
@cindex paging
You can tell the system to associate a particular virtual memory page
-with a real page frame and keep it that way --- i.e. cause the page to
+with a real page frame and keep it that way --- i.e., cause the page to
be paged in if it isn't already and mark it so it will never be paged
out and consequently will never cause a page fault. This is called
@dfn{locking} a page.
@@ -2467,7 +2467,7 @@
paging rule is: If a frame backs at least one locked page, don't page it
out.
-Memory locks do not stack. I.e. you can't lock a particular page twice
+Memory locks do not stack. I.e., you can't lock a particular page twice
so that it has to be unlocked twice before it is truly unlocked. It is
either locked or it isn't.
Modified: glibc-doc-reference/trunk/manual/message.texi
===================================================================
--- glibc-doc-reference/trunk/manual/message.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/message.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1189,7 +1189,7 @@
with every language this is the only viable solution except for
hardcoding the information in the code (which still would require the
possibility of extensions to not prevent the use of new languages). The
-details are explained in the GNU @code{gettext} manual. Here only a a
+details are explained in the GNU @code{gettext} manual. Here only a
bit of information is provided.
The information about the plural form selection has to be stored in the
@@ -1590,7 +1590,7 @@
them.
The POSIX locale model uses the environment variables @code{LC_COLLATE},
-@code{LC_CTYPE}, @code{LC_MESSAGES}, @code{LC_MONETARY}, @code{NUMERIC},
+@code{LC_CTYPE}, @code{LC_MESSAGES}, @code{LC_MONETARY}, @code{LC_NUMERIC},
and @code{LC_TIME} to select the locale which is to be used. This way
the user can influence lots of functions. As we mentioned above the
@code{gettext} functions also take advantage of this.
@@ -1810,8 +1810,8 @@
Other programs help to manage development cycle when new messages appear
in the source files or when a new translation of the messages appear.
-here it should only be noted that using all the tools in GNU gettext it
-is possible to @emph{completely} automize the handling of message
+Here it should only be noted that using all the tools in GNU gettext it
+is possible to @emph{completely} automate the handling of message
catalog. Beside marking the translatable string in the source code and
generating the translations the developers do not have anything to do
themselves.
Modified: glibc-doc-reference/trunk/manual/resource.texi
===================================================================
--- glibc-doc-reference/trunk/manual/resource.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/resource.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -584,7 +584,7 @@
@cindex preemptive scheduling
When two processes are in contention to use the CPU at any instant, the
one with the higher absolute priority always gets it. This is true even if the
-process with the lower priority is already using the CPU (i.e. the
+process with the lower priority is already using the CPU (i.e., the
scheduling is preemptive). Of course, we're only talking about
processes that are running or ``ready to run,'' which means they are
ready to execute instructions right now. When a process blocks to wait
@@ -819,7 +819,7 @@
@item
The calling process does not have @code{CAP_SYS_NICE} permission and its
-owner is not the target process' owner. I.e. the effective uid of the
+owner is not the target process' owner. I.e., the effective uid of the
calling process is neither the effective nor the real uid of process
@var{pid}.
@c We need a cross reference to the capabilities section, when written.
@@ -1185,7 +1185,7 @@
@item EPERM
The call would set the nice value of a process which is owned by a different
-user than the calling process (i.e. the target process' real or effective
+user than the calling process (i.e., the target process' real or effective
uid does not match the calling process' effective uid) and the calling
process does not have @code{CAP_SYS_NICE} permission.
@@ -1215,7 +1215,7 @@
@comment sys/resource.h
@comment BSD
@item PRIO_USER
-All the processes owned by a particular user (i.e. whose real uid
+All the processes owned by a particular user (i.e., whose real uid
indicates the user). The argument @var{id} is a user ID (uid).
@end vtable
@@ -1272,7 +1272,7 @@
@item
The access to certain resources (RAM, I/O ports) has different costs
from different CPUs. This is the case in NUMA (Non-Uniform Memory
-Architecture) machines. Preferrably memory should be accessed locally
+Architecture) machines. Preferably memory should be accessed locally
but this requirement is usually not visible to the scheduler.
Therefore forcing a process or thread to the CPUs which have local
access to the mostly used memory helps to significantly boost the
Modified: glibc-doc-reference/trunk/manual/search.texi
===================================================================
--- glibc-doc-reference/trunk/manual/search.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/search.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -82,7 +82,7 @@
available @code{NULL} is returned.
The mean runtime of this function is @code{*@var{nmemb}}/2. This
-function should only be used elements often get added to or deleted from
+function should only be used if elements often get added to or deleted from
the array in which case it might not be useful to sort the array before
searching.
@end deftypefun
@@ -247,21 +247,21 @@
@node Hash Search Function
@section The @code{hsearch} function.
-The functions mentioned so far in this chapter are searching in a sorted
+The functions mentioned so far in this chapter are for searching in a sorted
or unsorted array. There are other methods to organize information
which later should be searched. The costs of insert, delete and search
differ. One possible implementation is using hashing tables.
-The following functions are declared in the the header file @file{search.h}.
+The following functions are declared in the header file @file{search.h}.
@comment search.h
@comment SVID
@deftypefun int hcreate (size_t @var{nel})
The @code{hcreate} function creates a hashing table which can contain at
least @var{nel} elements. There is no possibility to grow this table so
-it is necessary to choose the value for @var{nel} wisely. The used
-methods to implement this function might make it necessary to make the
+it is necessary to choose the value for @var{nel} wisely. The method
+used to implement this function might make it necessary to make the
number of elements in the hashing table larger than the expected maximal
-number of elements. Hashing tables usually work inefficient if they are
+number of elements. Hashing tables usually work inefficiently if they are
filled 80% or more. The constant access time guaranteed by hashing can
only be achieved if few collisions exist. See Knuth's ``The Art of
Computer Programming, Part 3: Searching and Sorting'' for more
@@ -368,9 +368,9 @@
dynamically. It must be initialized with zero before calling this
function.
-The return value is non-zero if the operation were successful. if the
-return value is zero something went wrong which probably means the
-programs runs out of memory.
+The return value is non-zero if the operation was successful. If the
+return value is zero, something went wrong, which probably means the
+programs ran out of memory.
@end deftypefun
@comment search.h
Modified: glibc-doc-reference/trunk/manual/signal.texi
===================================================================
--- glibc-doc-reference/trunk/manual/signal.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/signal.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -2567,7 +2567,7 @@
Note that you must not use @code{sigprocmask} in multi-threaded processes,
because each thread has its own signal mask and there is no single process
signal mask. According to POSIX, the behavior of @code{sigprocmask} in a
-multi-threaded process is ``unspeficied''.
+multi-threaded process is ``unspecified''.
Instead, use @code{pthread_sigmask}.
@ifset linuxthreads
@xref{Threads and Signal Handling}.
Modified: glibc-doc-reference/trunk/manual/startup.texi
===================================================================
--- glibc-doc-reference/trunk/manual/startup.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/startup.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -830,7 +830,7 @@
Don't confuse a program's exit status with a process' termination status.
There are lots of ways a process can terminate besides having it's program
finish. In the event that the process termination @emph{is} caused by program
-termination (i.e. @code{exit}), though, the program's exit status becomes
+termination (i.e., @code{exit}), though, the program's exit status becomes
part of the process' termination status.
@node Cleanups on Exit
Modified: glibc-doc-reference/trunk/manual/stdio.texi
===================================================================
--- glibc-doc-reference/trunk/manual/stdio.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/stdio.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -433,7 +433,7 @@
@cindex multi-threaded application
Streams can be used in multi-threaded applications in the same way they
are used in single-threaded applications. But the programmer must be
-aware of a the possible complications. It is important to know about
+aware of the possible complications. It is important to know about
these also if the program one writes never use threads since the design
and implementation of many stream functions is heavily influenced by the
requirements added by multi-threaded programming.
@@ -1992,7 +1992,7 @@
The @samp{%g} and @samp{%G} conversions print the argument in the style
of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
than -4 or greater than or equal to the precision; otherwise they use
-the @samp{%f} style. A precision of @code{0}, is taken as 1. is
+the @samp{%f} style. A precision of @code{0}, is taken as 1.
Trailing zeros are removed from the fractional portion of the result and
a decimal-point character appears only if it is followed by a digit.
@@ -2393,8 +2393,9 @@
allocates a string (as with @code{malloc}; @pxref{Unconstrained
Allocation}) to hold the output, instead of putting the output in a
buffer you allocate in advance. The @var{ptr} argument should be the
-address of a @code{char *} object, and @code{asprintf} stores a pointer
-to the newly allocated string at that location.
+address of a @code{char *} object, and a successful call to
+@code{asprintf} stores a pointer to the newly allocated string at that
+location.
The return value is the number of characters allocated for the buffer, or
less than zero if an error occurred. Usually this means that the buffer
Modified: glibc-doc-reference/trunk/manual/string.texi
===================================================================
--- glibc-doc-reference/trunk/manual/string.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/string.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -1187,8 +1187,8 @@
@comment ISO
@deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size})
This function is the similar to @code{strcmp}, except that no more than
-@var{size} wide characters are compared. In other words, if the two
-strings are the same in their first @var{size} wide characters, the
+@var{size} characters are compared. In other words, if the two
+strings are the same in their first @var{size} characters, the
return value is zero.
@end deftypefun
@@ -1966,11 +1966,6 @@
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
-
-Note that ``character'' is here used in the sense of byte. In a string
-using a multibyte character encoding (abstract) character consisting of
-more than one byte are not treated as an entity. Each byte is treated
-separately. The function is not locale-dependent.
@end deftypefun
@comment wchar.h
Modified: glibc-doc-reference/trunk/manual/sysinfo.texi
===================================================================
--- glibc-doc-reference/trunk/manual/sysinfo.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/sysinfo.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -872,7 +872,7 @@
@item MS_SYNCHRONOUS
This bit on specifies that all writes to the filesystem while it is
-mounted shall be synchronous; i.e. data shall be synced before each
+mounted shall be synchronous; i.e., data shall be synced before each
write completes rather than held in the buffer cache.
@item MS_MANDLOCK
Modified: glibc-doc-reference/trunk/manual/syslog.texi
===================================================================
--- glibc-doc-reference/trunk/manual/syslog.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/syslog.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -370,7 +370,7 @@
Results are undefined if the priority code is anything else.
-If the process does not presently have a Syslog connection open (i.e.
+If the process does not presently have a Syslog connection open (i.e.,
it did not call @code{openlog}), @code{syslog} implicitly opens the
connection the same as @code{openlog} would, with the following defaults
for information that would otherwise be included in an @code{openlog}
Modified: glibc-doc-reference/trunk/manual/time.texi
===================================================================
--- glibc-doc-reference/trunk/manual/time.texi 2007-07-31 14:26:43 UTC (rev 2488)
+++ glibc-doc-reference/trunk/manual/time.texi 2007-08-01 05:52:43 UTC (rev 2489)
@@ -193,7 +193,7 @@
arbitrary event. On the GNU system, that event is the creation of the
process. While arbitrary in general, the event is always the same event
for any particular process, so you can always measure how much time on
-the CPU a particular computation takes by examinining the process' CPU
+the CPU a particular computation takes by examining the process' CPU
time before and after the computation.
@cindex CPU time
@cindex clock ticks
@@ -447,7 +447,7 @@
@comment time.h
@comment SVID, XPG
@deftypefun int stime (time_t *@var{newtime})
-@code{stime} sets the system clock, i.e. it tells the system that the
+@code{stime} sets the system clock, i.e., it tells the system that the
current calendar time is @var{newtime}, where @code{newtime} is
interpreted as described in the above definition of @code{time_t}.
@@ -1470,7 +1470,7 @@
@node Low-Level Time String Parsing
@subsubsection Interpret string according to given format
-he first function is rather low-level. It is nevertheless frequently
+The first function is rather low-level. It is nevertheless frequently
used in software since it is better known. Its interface and
implementation are heavily influenced by the @code{getdate} function,
which is defined and implemented in terms of calls to @code{strptime}.
@@ -1790,7 +1790,7 @@
the format string the return value points right after the last consumed
input character. If the whole input string is consumed the return value
points to the @code{NULL} byte at the end of the string. If an error
-occurs, i.e. @code{strptime} fails to match all of the format string,
+occurs, i.e., @code{strptime} fails to match all of the format string,
the function returns @code{NULL}.
@end deftypefun
Reply to: