OSSP CVS Repository

ossp - Check-in [74]
Not logged in 		[Honeypot]  [Browse]  [Home]  [Login]  [Reports] 
[Search]  [Ticket]  [Timeline] 
  [Patchset]  [Tagging/Branching] 

Check-in Number: 74
Date: 2000-Jun-30 16:07:10 (local)
2000-Jun-30 14:07:10 (UTC)
User:rse
Branch:PTH_1_3
Comment: *** empty log message ***
Tickets:
Inspections:
Files:
ossp-pkg/pth/ChangeLog      added-> 1.488.2.9
ossp-pkg/pth/README      added-> 1.173.2.5
ossp-pkg/pth/pth.3      added-> 1.208.2.5
ossp-pkg/pth/pth_p.h.in      added-> 1.24.2.1
ossp-pkg/pth/pthread-config.1      added-> 1.81.2.5
ossp-pkg/pth/pthread.3      added-> 1.85.2.5
ossp-pkg/pth/ChangeLog -> 1.488.2.9 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,2128 ----
+    ____  _   _
+   |  _ \| |_| |__
+   | |_) | __| '_ \             ``Just because everything is different
+   |  __/| |_| | | |              doesn't mean anything has changed.''
+   |_|    \__|_| |_|                             -- Irene Peter
+ 
+   GNU Pth - The GNU Portable Threads
+ 
+   ChangeLog
+   =========
+ 
+   This is the list of all(!) changes to this Pth source tree. For a list
+   of just the user-visible and/or major changes please have a look at
+   the NEWS file.
+ 
+      _   _____
+     / | |___ /
+     | |   |_ \
+     | |_ ___) |
+   __|_(_)____/____________________________________________________________
+ 
+   Changes between 1.3.5 and 1.3.6 (17-Apr-2000 to 01-Jul-2000)
+ 
+    *) Backport from GNU Pth 1.4a2: 
+       Upgraded to GNU Shtool 1.5.0
+       [Ralf S. Engelschall]
+ 
+    *) Backport from GNU Pth 1.4a2: 
+       Added OS/390 support to config.sub.
+       [Greg Ames <gregames@raleigh.ibm.com>]
+ 
+    *) Backport from GNU Pth 1.4a2: 
+       Upgraded rse-pmt.ps paper to latest version as it was
+       published on USENIX 2000.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from GNU Pth 1.4a2: 
+       Upgraded to GNU libtool 1.3.5
+       [Ralf S. Engelschall]
+ 
+    *) Backport from GNU Pth 1.4a2: 
+       Allow for convinience reasons pth_usleep() to accept also
+       arguments greater than 1000000.
+       [Harvinder Sawhney <hsawhney@hotmail.com>]
+ 
+   Changes between 1.3.4 and 1.3.5 (16-Apr-2000 to 17-Apr-2000)
+ 
+    *) Fixed the <sys/select.h> checks in Autoconf: the logic
+       was reversed and this way <sys/select.h> wasn't included on
+       platforms were it existed and included where it wasn't present.
+       [M. Lavasani <lavasani@connect.org.uk>]
+ 
+   Changes between 1.3.3 and 1.3.4 (10-Mar-2000 to 16-Apr-2000)
+ 
+    *) Merged from Pth 1.4a1:
+       Fixed usage of `volatile' qualifier in pointer context.
+       [Ralf S. Engelschall]
+    
+    *) Merged from Pth 1.4a1:
+       Now pth.h and pthread.h include the non-standard <sys/select.h>
+       header on brain-dead platforms (like AIX) to get the definition of
+       fd_set (which is required for the pth_select prototype).
+       [Ralf S. Engelschall, Stian Seeberg <stian@nimsoft.no>]
+ 
+    *) Merged from Pth 1.4a1:
+       Fixed auto-configuration for ISC and Win32/Cygwin platforms.
+       [Ralf S. Engelschall, Giwon On <Giwon.On@KOM.tu-darmstadt.de>]
+ 
+    *) Merged from Pth 1.4a1:
+       Removed -L. from $(LDFLAGS) in Makefile.in, because this
+       is not required (libtool already takes care of this).
+       [Ralf S. Engelschall]
+ 
+    *) Merged from Pth 1.4a1:
+       Removed the too explicit `-m 644' from the libtool/shtool
+       installation command for libpth.la and instead use a `umask 022'.
+       The reason is because some platforms require the shared libraries
+       to be executable, so we cannot use an explicit mode. But we use the
+       umask to make sure we don't result in world or group writeable files.
+       [Ralf S. Engelschall, Daniel Richard G. <straker@MIT.EDU>]
+ 
+    *) Merged from Pth 1.4a1:
+       Use full-path /sbin/sysctl in config.guess on FreeBSD because
+       not all users have /sbin in their $PATH.
+       [Jeff Trawick <trawick@ibm.net>]
+ 
+    *) Merged from Pth 1.4a1:
+       Upgraded to GNU shtool 1.4.9
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.3.2 and 1.3.3 (24-Feb-2000 to 10-Mar-2000)
+ 
+    *) Under Solaris and --enable-optimize we now also check for the
+       compiler option -fast which is supported by the Sun vendor compilers.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed AC_COMPILER_OPTION macro in aclocal.m4: it wasn't aware of
+       the fact that running gcc with not supported options just leads to a
+       warning (but gcc still compiles the test program and exists with a 0
+       return value).
+       [Ralf S. Engelschall]
+ 
+    *) Fixed semantics of pth_cond_notify() to match POSIX: if one
+       notifies a condition variable which has still no waiter, the notify
+       operation is a no-op. Previously the condition signal was remembered
+       until a waiter arrived. This is now no longer the case.
+       [Ralf S. Engelschall, Chris Leishman <chris_leishman@freeonline.com.au>]
+ 
+    *) Allow pth_yield(<tid>) to yield also to <tid> if <tid> is a
+       freshly spawned thread, i.e. in state PTH_STATE_NEW instead of
+       PTH_STATE_READY, directly after a pth_spawn. This allows one better
+       control under co-routine programming.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed internal pth_pqueue_delete() and pth_pqueue_tail()
+       functions to pth_pqueue.c for convinience reasons.
+       [Ralf S. Engelschall]
+ 
+    *) API CHANGE: Changed pth_time(int,int) to pth_time(long,long) and
+       pth_timeout(int,int) to pth_timeout(long,long), because pth_time_t
+       is a struct timeval and this structure is defined always via two
+       long's and not just int's.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up source code even more by making sure "signed",
+       "unsigned" and "const" qualifiers are used correctly and
+       consistently.
+       [Ralf S. Engelschall]
+ 
+    *) Changed default stack size from 32KB to 64KB, because
+       on Solaris and other platforms where one can set FD_SETSIZE to
+       values up to 65535 an fd_set is up to 8KB. Pth internally (in
+       the scheduler in pth_select_ev) has up to three fd_sets (up to
+       24KB) on the stack, so a 32KB stack is too risky. Nevertheless
+       one can still spawn threads with smaller stacks by using
+       PTH_ATTR_STACK_SIZE, of course. Only the scheduler thread remains
+       with a 64KB stack, because this thread cannot be configured by the
+       application.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed "make depend": a backslash was missing.
+       [Edwin Brown <Edwin.Brown@sdrc.com>]
+ 
+    *) Fixed "make install" for pth.m4 and the situation where
+       one compiles from a different sub-directory.
+       [Raphael Bossek <raphael.bossek@solutions4linux.de>]
+ 
+   Changes between 1.3.1 and 1.3.2 (20-Feb-2000 to 24-Feb-2000)
+ 
+    *) Do no longer use -woff in CFLAGS for IRIX 6.5.2 and above.
+       [Edwin Brown <Edwin.Brown@sdrc.com>, Ralf S. Engelschall]
+ 
+    *) Replaced ``while (1)'' constructs with ``for (;;)'' because some
+       compilers like this more and do not warn about constant expressions.
+       [Ralf S. Engelschall]
+ 
+    *) Added hint to pth.pod that ``pth_join(<tid>, NULL)'' is allowed.
+       [Ralf S. Engelschall]
+ 
+    *) Cancel and join the ticker thread explicitly in test_select.c
+       [Edwin Brown <Edwin.Brown@sdrc.com>, Ralf S. Engelschall]
+ 
+    *) Removed unnecessary code in pth_event.c
+       [Edwin Brown <Edwin.Brown@sdrc.com>, Ralf S. Engelschall]
+ 
+    *) Add special namespace workarounds to pthread.h.in for HPUX
+       platforms where the pthread_kill() prototypes conflict without this.
+       [M. Lavasani <lavasani@connect.org.uk>, Ralf S. Engelschall]
+ 
+   Changes between 1.3.0 and 1.3.1 (19-Feb-2000 to 20-Feb-2000)
+ 
+    *) Added HISTORY document where we now write down the evolution
+       and release dates of Pth to have a concise history reference.
+       [Ralf S. Engelschall]
+ 
+    *) Added USERS document where we now collect references to
+       software packages utilizing GNU Pth.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a subtle typo in pth.pod about thread-safe functions
+       and finished documentation of pth_attr_set/pth_attr_get functions.
+       [James Robinson <jlrobins@uncc.edu>, Jeremie <jeremie@jabber.org>]
+ 
+   Changes between 1.3b3 and 1.3.0 (13-Feb-2000 to 19-Feb-2000)
+ 
+    *) Polished the various document files.
+       [Ralf S. Engelschall]
+ 
+    *) Use -w in $CFLAGS also on UnixWare 2.1, because its cc
+       complains about "not reached" situations because of our macros.
+       [Ralf S. Engelschall]
+ 
+    *) Replaced "NOT REACHED" with "NOTREACHED" in comments
+       to be more correct for lint(1).
+       [Ralf S. Engelschall]
+ 
+    *) Updated config.param and fixed its parsing procedure.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a few typos in pth.pod and adjusted example program
+       to make sure it doesn't segfault accidently for the users.
+       [Tim Harris <tim_harris@snellwilcox.com>, Raphael Bossek
+       <raphael.bossek@solutions4linux.de>, Ralf S. Engelschall]
+ 
+   Changes between 1.3b2 and 1.3b3 (28-Jan-2000 to 13-Feb-2000)
+ 
+    *) Fixed PTH_EVENT_FUNC handling (it was not polled really
+       in regular intervals if there were no other FUNC events which
+       helped) by extending it with an interval time argument. This way
+       a PTH_EVENT_FUNC event is likewise a PTH_EVENT_TIME event which
+       calls the check function after elapsing and resets itself again if
+       it failed.
+       [Ralf S. Engelschall]
+ 
+    *) Removed PTH_EVENT_PID because the waiting on a process id was not
+       working as expected (the polling was not done in intervals) and this
+       type of event doesn't really fit very well into the multi-threading
+       environment of Pth (where the events should be thread-related and not
+       process-related). So instead of fixing the pid waiting event handling
+       through some unclean workarounds or kludges (it cannot be done very
+       different), it was decided to kick it out at all.
+       [Ralf S. Engelschall]
+ 
+    *) Make sure pth_connect[_ev]() doesn't block by internally 
+       switching to non-blocking mode temporarily if necessary.
+       [Chris Leishman <chris_leishman@freeonline.com.au>, Ralf S. Engelschall]
+ 
+    *) Fix pthread_cond_timedwait by making it more POSIX compliant:
+       return ETIMEDOUT instead of 0 if the timeout occurred.
+       [Emanuele Fornara <efornara@hotmail.com>, Ralf S. Engelschall]
+ 
+   Changes between 1.3b1 and 1.3b2 (26-Jan-2000 to 28-Jan-2000)
+ 
+    *) Let "make striptease" be aware of $TMPDIR and remove temporary
+       directory from this dir, too.
+       [Ralf S. Engelschall]
+ 
+    *) Again cleaned up and enhanced the manual page pth.pod.
+       [Ralf S. Engelschall]
+ 
+    *) Added a few more errno_shield { ... } sections to prevent
+       the destruction of errno values on error returns.
+       [Ralf S. Engelschall]
+ 
+    *) Added more complete Linux support for --enable-syscall-hard by
+       using SYS_socketcall+SOCKOP_{accept,connect} if
+       SYS_{accept,connect} doesn't exist.
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_suspend() and pth_resume together with an additional
+       SUSPENDED queue. This can be used to temporarily park threads in
+       order to move them out of the schedulers scope.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.3a5 and 1.3b1 (15-Jan-2000 to 26-Jan-2000)
+ 
+    *) Completely cleaned up the manual page.
+       [Eric Hanchrow <offby1@blarg.net>]
+ 
+    *) Use SYS__newselect instead of SYS_select under Linux and
+       --enable-syscall-hard because SYS_select is a dummy stub which 
+       always just returns -1 and errno = EFAULT.
+       [Artem Gr <artem@bizlink.ru>, Ralf S. Engelschall]
+ 
+   Changes between 1.3a4 and 1.3a5 (08-Jan-2000 to 15-Jan-2000)
+ 
+    *) Updated HACKING document.
+       [Ralf S. Engelschall]
+ 
+    *) Removed '+DAportable' from HPUX flags to avoid problems.
+       [M. Lavasani <lavasani@connect.org.uk>]
+ 
+    *) Added a workround in Makefile.in (replaced "rm -r" with
+       "rm" + "rmdir") for brain-dead AmigaOS.
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+ 
+    *) Fixed example in Pth manual page: peer_len wasn't initialized.
+       [Sami Niemi <saminiemi@usa.net>, Ralf S. Engelschall]
+ 
+    *) Fixed cleanup handling in test_sig.c.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed memory leaks in some test programs.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.3a3 and 1.3a4 (08-Jan-2000 to 08-Jan-2000)
+ 
+    *) Translated The Open Group's SUSv2 Threading HTML documentation
+       into POD format to form an appendix for pthread.pod. This is for
+       convinience reasons when programming with the Pthread API of GNU Pth.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed introduced debugging with "==== THREAD CONTEXT SWITCH ===="
+       lines. They were printed always.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.3a2 and 1.3a3 (30-Dec-1999 to 08-Jan-2000)
+ 
+    *) Added a PTH_CTRL_DUMPSTATE to pth_ctrl() which helps in debugging.
+       a pth_ctrl(PTH_CTRL_DUMPSTATE, stderr) for instance writes out a summary
+       page of the internal Pth library state to stderr. This is intended for
+       debugging purposes only, of course.
+       [Ralf S. Engelschall, Lubos Lunak <l.lunak@sh.cvut.cz>]
+ 
+    *) Fixed destructor for statically initialized events which failed
+       under asynchronous cancellation if those events were merged
+       together at the time of cancellation.
+       [Igor A. Minyukoff, Ralf S. Engelschall]
+ 
+    *) Updated the INSTALL document.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a memory leak in pth_kill(): the TCBs (plus one
+       stack) of the main and scheduler thread were not freed.
+       [Pete <pfv@grex.org>, Ralf S. Engelschall]
+ 
+    *) Added developer support for compiling and linking against the
+       Dmalloc library (for debugging memory allocation) through the
+       --with-dmalloc[=DIR] Autoconf option.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed pth_compat.c: the #define for strerror was buggy.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.3a1 and 1.3a2 (09-Nov-1999 to 30-Dec-1999)
+ 
+    *) Added first cut of experimental Win32 support through Cygwin B20.1.
+       [Ralf S. Engelschall, Schizoid <schizoid21@yahoo.com>]
+ 
+    *) Fixed autoheader step by using AC_CHECK_HEADERS() instead of
+       AC_CHECK_HEADER() because Autoconf's autoheader.m4 isn't aware of
+       AC_CHECK_HEADER().
+       [Ralf S. Engelschall]
+ 
+    *) Adjusted all copyright messages to include the forthcoming
+       new year 2000, too. 
+       [Ralf S. Engelschall]
+ 
+    *) Fixed $DIFS in pth-config.in and pthread-config.in
+       (the tab was lost) and cleaned up pth-config.in a little bit.
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded from GNU libtool 1.3.3 to 1.3.4 
+       and from GNU shtool 1.4.6 to 1.4.7.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed cleanup handling for main thread. Now pth_kill()
+       and pth_exit() in the main thread work as expected.
+       [Ralf S. Engelschall, Anton Umnikov <anton@uic.dvgu.ru>]
+ 
+    *) Fixed Autoconf --host option.
+       [Ralf S. Engelschall, Kent Overstreet <kent@hotmail.com>]
+ 
+    *) Fixed pth_mctx.c by making sure ss_base is mapped to ss_sp
+       only if sigaltstack(2) is used for the stack trick.
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+ 
+    *) Fixed return code semantics for error situation in both
+       pth_write(3) and pth_writev(3).
+       [Rob Quinn <rquinn@sec.sprint.net>, Ralf S. Engelschall]
+ 
+    *) Stripped trailing whitespaces from all source files.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2.0 and 1.3a1 (31-Oct-1999 to 09-Nov-1999)
+ 
+    *) Changed AC_CHECK_STRUCTATTR macro from a too weak AC_TRY_EGREP to a
+       AC_TRY_LINK based approach to make sure the ss_sp/ss_base checks do not
+       fail on platforms where sys/signal.h contains both sigstack and
+       sigaltstack defines.
+       [Ralf S. Engelschall]
+ 
+    *) Added a large "BUILD ENVIRONMENT" section to pth.pod which describes
+       three ways to establish build environments for Pth based packages.
+       [Ralf S. Engelschall]
+ 
+    *) Updated the pth-config.pod and pthread-config.pod for
+       missing option entries.
+       [Ralf S. Engelschall]
+ 
+    *) Added --datadir and --acdir options to pth-config. Especially
+       --acdir can be used in conjunction with Autoconf's aclocal program to
+       retrieve the AC_CHECK_PTH macro, e.g. aclocal --output-
+       --acdir=`pth-config --acdir` prints the macro definition to stdout.
+       [Ralf S. Engelschall]
+ 
+    *) Added a new, very flexible and robust pth.m4 Autoconf macro file which
+       is installed under $datadir/aclocal/ and can be used by third-party
+       Autoconf scripts to locate GNU Pth.  Syntax is:
+       AC_CHECK_PTH([MIN-VERSION [,DEFAULT-WITH-PTH [,DEFAULT-WITH-PTH-TEST
+       [,EXTEND-VARS [,ACTION-IF-FOUND [,ACTION-IF-NOT-FOUND]]]]]]).
+       [Ralf S. Engelschall, Markus Fischer <mfischer@josefine.ben.tuwien.ac.at>]
+ 
+    *) Added PTH_VERSION_{STR,HEX} to pth.h
+       [Ralf S. Engelschall]
+ 
+    *) Fixed AC_CHECK_EXTLIB macro.
+       [Ralf S. Engelschall]
+ 
+    *) Added a new developer target `make striptease' which uses the
+       new striptease.{pl,mk} files to strip down the Pth source tree to a
+       minimum (approx. 1/3 of size). The generated striptease.dir/ area can be
+       then imported into third-party source trees and there blows up the stuff
+       only as minimal as possible.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up copyright messages in source files.
+       [Ralf S. Engelschall]
+ 
+    *) Rewritten the Linux guessing part in config.guess to
+       create more useful GNU platform triples for Linux flavors.
+       [Ralf S. Engelschall]
+ 
+      _   ____
+     / | |___ \
+     | |   __) |
+     | |_ / __/
+   __|_(_)_____|___________________________________________________________
+ 
+   Changes between 1.2.2 and 1.2.3 (08-Jan-2000 to 04-Feb-2000)
+ 
+    *) Backport from Pth 1.3b3:
+       Fix pthread_cond_timedwait by making it more POSIX compliant:
+       return ETIMEDOUT instead of 0 if the timeout occurred.
+       [Emanuele Fornara <efornara@hotmail.com>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3b2:
+       Added more complete Linux support for --enable-syscall-hard by
+       using SYS_socketcall+SOCKOP_{accept,connect} if
+       SYS_{accept,connect} doesn't exist.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3b2:
+       Added a few more errno_shield { ... } sections to prevent
+       the destruction of errno values on error returns.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3b1:
+       Use SYS__newselect instead of SYS_select under Linux and
+       --enable-syscall-hard because SYS_select is a dummy stub which 
+       always just returns -1 and errno = EFAULT.
+       [Artem Gr <artem@bizlink.ru>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a5:
+       Removed '+DAportable' from HPUX flags to avoid problems.
+       [M. Lavasani <lavasani@connect.org.uk>]
+ 
+    *) Backport from Pth 1.3a5:
+       Added a workround in Makefile.in (replaced "rm -r" with
+       "rm" + "rmdir") for brain-dead AmigaOS.
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+    
+    *) Backport from Pth 1.3a5:
+       Fixed example in Pth manual page: peer_len wasn't initialized.
+       [Sami Niemi <saminiemi@usa.net>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a5:
+       Fixed memory leaks in some test programs.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2.1 and 1.2.2 (14-Nov-1999 to 08-Jan-2000)
+ 
+    *) Backport from Pth 1.3a3:
+       Updated the INSTALL document.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a3:
+       Fixed a memory leak in pth_kill(): the TCBs (plus one
+       stack) of the main and scheduler thread were not freed.
+       [Pete <pfv@grex.org>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a3:
+       Fixed pth_compat.c: the #define for strerror was buggy.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a3:
+       Fixed destructor for statically initialized events which failed
+       under asynchronous cancellation if those events were merged
+       together at the time of cancellation.
+       [Igor A. Minyukoff, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a2:
+       Upgraded from GNU libtool 1.3.3 to 1.3.4 
+       and from GNU shtool 1.4.6 to 1.4.7.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a2:
+       Fixed pth_mctx.c by making sure ss_base is mapped to ss_sp
+       only if sigaltstack(2) is used for the stack trick.
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+ 
+   Changes between 1.2.0 and 1.2.1 (31-Oct-1999 to 14-Nov-1999)
+ 
+    *) Backport from Pth 1.3a2:
+       Fixed return code semantics for error situation in both
+       pth_write(3) and pth_writev(3).
+       [Rob Quinn <rquinn@sec.sprint.net>, Ralf S. Engelschall]
+    
+    *) Backport from Pth 1.3a1:
+       Changed AC_CHECK_STRUCTATTR macro from a too weak AC_TRY_EGREP to a
+       AC_TRY_LINK based approach to make sure the ss_sp/ss_base checks do not
+       fail on platforms where sys/signal.h contains both sigstack and
+       sigaltstack defines.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a1:
+       Fixed AC_CHECK_EXTLIB macro.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.3a1:
+       Cleaned up copyright messages in source files.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2b8 and 1.2.0 (26-Oct-1999 to 31-Oct-1999)
+ 
+    *) Finally tested the package on all major Unix platforms to which
+       I've direct access (see PORTING document for details).
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a few remaining typos in pth.pod; adjusted README file for
+       release and included ANNOUNCE document in source tree.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed special Autoconf detections for UnixWare 2.x platform.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed special Autoconf detections for Linux platforms.
+       [Ralf S. Engelschall]
+ 
+    *) Updated INSTALL document.
+       [Ralf S. Engelschall]
+ 
+    *) Added -w option to CFLAGS under HP-UX with CC.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2b7 and 1.2b8 (22-Oct-1999 to 26-Oct-1999)
+ 
+    *) Fixed Pthread compilation under NetBSD 1.4 and Solaris.  The pth.h
+       header has to skip the fallbacks (and not the pthread.h header) when
+       compiling pthread.c. This subtle difference is important because
+       ordering is important for correct namespace hiding.
+       [Ralf S. Engelschall, John A. Maier <johnam@mail.kemper.org>]
+ 
+    *) Greatly enhanced AC_CHECK_ARGTYPE macro to support more
+       vendor headers and their syntax.
+       [Ralf S. Engelschall]
+ 
+    *) Added two new Autoconf options: --enable-maintainer for enabling
+       maintainer targets (now the x.pod -> x.N translation is disabled per
+       default and is enabled with this option only) and --enable-tests which
+       is on per default and can be used (as --disable-tests) to disable the
+       building of the test programs.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed autoheader processing with a new acheader.m4 file.
+       [Ralf S. Engelschall]
+ 
+    *) Stripped down shtool script to 7 of 17 ingredients to reduce source
+       tree by approx. 40KB.
+       [Ralf S. Engelschall]
+ 
+    *) Updated acconfig.h: HAVE_NFDS_T was missing.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed `make dist': CVS temporary files (.#xx) were included
+       into the distribution tarball.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2b6 and 1.2b7 (28-Sep-1999 to 22-Oct-1999)
+ 
+    *) Add the .gdbinit file also to the distribution tarball.
+       [Ralf S. Engelschall]
+ 
+    *) Re-acquire the mutex corresponding to a condition variable when
+       pth_cond_await() is cancelled, in order to restore the condition
+       variable semantics.
+       [Lubos Lunak <l.lunak@email.cz>]
+ 
+    *) Fixed cancellation point handling.
+       [Lubos Lunak <l.lunak@email.cz>]
+ 
+    *) Added support for poll(2)'s POSIX nfds_t argument type.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed AC_CHECK_ARGTYPE: it now handles wrapped lines, too.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed regex in aclocal.m4: tabs were expanded to spaced.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a casting problem related to `void *' in pth_high.c
+       which g++ 2.95.1 hated.
+       [Ralf S. Engelschall]
+ 
+    *) Replaced Autoconf AC_CHECK_FUNCS macro with an own local copy named
+       AC_CHECK_FUNCTIONS which _always_ uses ``extern "C"'' if __cplusplus is
+       defined. This way one can configure Pth even if $CC is a C++ compiler.
+       [Ralf S. Engelschall]
+ 
+    *) Updated rse-pmt.ps document.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a few typos in the manual page.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed aclocal.m4: CFXXLAGS -> CXXFLAGS ;)
+       [Alexandre Oliva <oliva@dcc.unicamp.br>]
+ 
+   Changes between 1.2b5 and 1.2b6 (21-Sep-1999 to 28-Sep-1999)
+ 
+    *) Added platform support for GNU/Linux kernel 2.2 / glibc 2.1
+       for both Alpha and Intel platforms via sjlj/ssjlj/sas.
+       (tested with both RedHat 6.0 and SuSE 6.1)
+       [Ralf S. Engelschall]
+ 
+    *) Added platform support for Tru64/OSF1 4.x and 5.0.
+       [Ralf S. Engelschall]
+ 
+    *) Added --prefix, --bindir, --libdir, --includedir and --mandir
+       options to pth-config and pthread-config. Mainly for convinience
+       and consistency reasons.
+       [Ralf S. Engelschall]
+ 
+    *) Avoid compiler complains in pth_mctx.c for assigning a `volatile
+       sigset_t'. Instead use a plain memcpy() with sizeof(sigset_t).
+       This now makes also IRIX' 6.5 cc happy.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed the Autoconf AC_CHECK_MCSC check which tests whether
+       SVR4/SUSv2 makecontext(2), swapcontext(2) and friends can be used for
+       user-space context switching. It was broken because the uc_link and
+       uc_stack structure attributes were not initialized correctly.
+       [Ralf S. Engelschall, Ben Harris <bjh21@cam.ac.uk>]
+ 
+    *) Updated dependencies in Makefile.in.
+       [Ralf S. Engelschall]
+ 
+    *) Mention the new pth-users@gnu.org mailing list in SUPPORT
+       and added hint to Makefile.in.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2b4 and 1.2b5 (17-Sep-1999 to 21-Sep-1999)
+ 
+    *) Added new Autoconf macro AC_COMPILER_OPTION which is now
+       used to check whether -pipe, -ggdb3 and -W<xxx> really work
+       before they are implicitly used.
+       [Ralf S. Engelschall, Alexandre Oliva <oliva@dcc.unicamp.br>]
+ 
+    *) Make sure pthread.c compiles even if the platforms lacks `struct
+       timespec'. The pthread_cond_timedwait() function will then still be
+       unuseable by the application, of course.  But that's the intended
+       behavour, because the Pthread API cannot be changed at this point.
+       [Michele Satriani <satriani@info.uniroma2.it>, Ralf S. Engelschall]
+ 
+    *) Document it more clearly that PTH_ATTR_DEFAULT is _not_ the values an
+       pth_attr_init() creates. It means that priority, joinability and
+       cancelstate are _inherited_.
+       [Eric Newton <ecn@smart.net>]
+ 
+   Changes between 1.2b3 and 1.2b4 (17-Sep-1999 to 17-Sep-1999)
+ 
+    *) Fixed test_httpd.c: highest port is 65535 and not 65553 ;)
+       [Alex Fiori <alex@linuxbr.com>]
+ 
+    *) Fix Makefile.in: $(S)shtool -> $(srcdir)shtool
+       [Ben Harris <bjh21@cam.ac.uk>, Ralf S. Engelschall]
+ 
+    *) Make Rhapsody happy with pth_errno.c by statically initializing
+       the contained variables.
+       [Ben Harris <bjh21@cam.ac.uk>, Ralf S. Engelschall]
+ 
+   Changes between 1.2b2 and 1.2b3 (04-Sep-1999 to 17-Sep-1999)
+ 
+    *) Added first cut of support for building Pth outside it's source tree.
+       [Ben Harris <bjh21@cam.ac.uk>, Ralf S. Engelschall]
+ 
+    *) Updated pth.pod for new socklen_t usage and updated NEWS file.
+       [Ralf S. Engelschall]
+ 
+    *) Officially switched from ``GNU Library General License v2.0''
+       to successor license: ``GNU Lesser General License v2.1''.
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced ss_sp to ss_base mapping: There is now Autoconf
+       support for the mapping decision.
+       [Ralf S. Engelschall, Ben Harris <bjh21@cam.ac.uk>]
+ 
+    *) Add `PTHREAD' also to defines for namespace protection.
+       [Hans v. Sommerfeld <snoopy@redbaron.bir.uunet.de>]
+ 
+    *) Made the temporary errno saving more elegant with a new
+       `errno_shield { .... }' construct.
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.4.6
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.2b1 and 1.2b2 (02-Sep-1999 to 04-Sep-1999)
+ 
+    *) Ported Pth to another esoteric, anchient and brain-dead
+       platform which needs jmp_buf fiddling: Interactive Unix (ISC) 4.0.
+       [Ralf S. Engelschall, Brandon Reynolds <bmr@comtime.com>]
+ 
+    *) Make sys/resource.h an optional header.
+       [Ralf S. Engelschall]
+ 
+    *) Added CPPFLAGS to Makefile.in and configure.in
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1.4 and 1.2b1 (30-Aug-1999 to 02-Sep-1999)
+ 
+    *) Added TESTS document which shows success stories with
+       Apache, MySQL, Perl, Python, OpenLDAP, pident, etc.
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced pth-config/pthread-config scripts: first they
+       are now concatenating the output of the options into a single
+       string and print this at the end once. This way one can use things
+       like LIBS="`pthread-config --ldflags --libs`" without getting an
+       intermediate newline which causes trouble in various packages.
+       Second per default only pth-specific CFLAGS/LDFLAGS/LIBS are
+       printed. If one wants also additional flags one has used while
+       building Pth one now can add the --all option. This is to avoid
+       conflicts between Pth flags and flags of the application.
+       [Ralf S. Engelschall]
+ 
+    *) Added -w to CFLAGS for Solaris if $CC is not GCC to avoid the
+       warnings about "end of loop not reached" because of our
+       ``do { ...return;... } while(0)'' macros.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed two bugs in internal pth_pqueue_delete() and one in
+       pth_pqueue_insert(): it accidently also adjusted the priority
+       queue top element if one deleted the last element of the queue and it
+       calculated the priority of the following element incorrectly.
+       [Jens Andersen <Jens@trw.nl>, Ralf S. Engelschall]
+ 
+    *) Optimized the signal mask handling: The application is now required to
+       use pth_sigmask(3) and no longer can use sigprocmask(2) directly
+       (as it's already the case for Pthreads where POSIX states that the
+       behaviour of sigprocmask(2) is not defined in a MT application).
+       The side-effect of this consistencency restriction is that
+       internally the machine context switching no longer has to remember
+       the signal mask on _every_ context switch. It's now sufficient
+       that pth_sigmask(3) sets the mask to allow the scheduler to
+       calculate its own mask. The result is a faster and more clean
+       thread dispatching. Additionally a soft and hard syscall mapping
+       for sigprocmask(2) was added, of course.
+       [Ralf S. Engelschall]
+ 
+    *) Added support for socklen_t to both avoid warnings under
+       some platforms and to avoid problems on 64 bit machines.
+       [Ralf S. Engelschall]
+ 
+    *) Added UnixWare7 support to config.guess
+       [Ralf S. Engelschall]
+ 
+    *) Added config.param facility.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up bootstrap stuff from configure.in and moved it to aclocal.m4.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed autoconf's `--silent' flag: it wasn't passed to ltconfig.sh
+       [Ralf S. Engelschall]
+ 
+    *) Rewritten the "make test" message and refreshed the PORTING file to
+       start with a new format which now includes also the machine context and
+       stack growth direction.
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced the interactive (not --enable-batch) mode: The Makefile now
+       displays real hints what to do as the next step. All messages can
+       be disabled via --enable-batch, of course.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed aclocal.m4: Tabs were lost by accident.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a type warning in pth_debug.c: pid_t vs. int
+       [Ralf S. Engelschall]
+ 
+      _   _
+     / | / |
+     | | | |
+     | |_| |
+   __|_(_)_|_______________________________________________________________
+ 
+   Changes between 1.1.5 and 1.1.6 (02-Sep-1999 to 28-Sep-1999)
+ 
+    *) Backport from Pth 1.2b6:
+       Fixed the Autoconf AC_CHECK_MCSC check which tests whether
+       SVR4/SUSv2 makecontext(2), swapcontext(2) and friends can be used for
+       user-space context switching. It was broken because the uc_link and
+       uc_stack structure attributes were not initialized correctly.
+       [Ralf S. Engelschall, Ben Harris <bjh21@cam.ac.uk>]
+ 
+    *) Backport from Pth 1.2b5:
+       Document it more clearly that PTH_ATTR_DEFAULT is _not_ the values an
+       pth_attr_init() creates. It means that priority, joinability and
+       cancelstate are _inherited_.
+       [Eric Newton <ecn@smart.net>]
+ 
+    *) Backport from Pth 1.2b4:
+       Fixed test_httpd.c: highest port is 65535 and not 65553 ;)
+       [Alex Fiori <alex@linuxbr.com>]
+ 
+    *) Backport from Pth 1.2b4:
+       Make Rhapsody happy with pth_errno.c by statically initializing
+       the contained variables.
+       [Ben Harris <bjh21@cam.ac.uk>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b3:
+       Add `PTHREAD' also to defines for namespace protection.
+       [Hans v. Sommerfeld <snoopy@redbaron.bir.uunet.de>]
+ 
+    *) Upgraded to GNU shtool 1.4.6
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1.4 and 1.1.5 (30-Aug-1999 to 02-Sep-1999)
+ 
+    *) Backport from Pth 1.2b1:
+       Enhanced pth-config/pthread-config scripts: first they
+       are now concatenating the output of the options into a single
+       string and print this at the end once. This way one can use things
+       like LIBS="`pthread-config --ldflags --libs`" without getting an
+       intermediate newline which causes trouble in various packages.
+       Second per default only pth-specific CFLAGS/LDFLAGS/LIBS are
+       printed. If one wants also additional flags one has used while
+       building Pth one now can add the --all option. This is to avoid
+       conflicts between Pth flags and flags of the application.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b1:
+       Fixed two bugs in internal pth_pqueue_delete() and one in
+       pth_pqueue_insert(): it accidently also adjusted the priority
+       queue top element if one deleted the last element of the queue and it
+       calculated the priority of the following element incorrectly.
+       [Jens Andersen <Jens@trw.nl>, Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b1:
+       Added -w to CFLAGS for Solaris if $CC is not GCC to avoid the
+       warnings about "end of loop not reached" because of our
+       ``do { ...return;... } while(0)'' macros.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b1:
+       Fixed autoconf's `--silent' flag: it wasn't passed to ltconfig.sh
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b1:
+       Fixed aclocal.m4: Tabs were lost by accident.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.2b1:
+       Fixed a type warning in pth_debug.c: pid_t vs. int
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1.3 and 1.1.4 (27-Aug-1999 to 30-Aug-1999)
+ 
+    *) Changed internal handling of spawned threads: they are now really
+       inserted to the top of the priority queue to make sure a thread is
+       guarrantied to be dispatched next when one calls pth_yield(NULL)
+       directly after a pth_spawn(). This is especially interesting for
+       programming with the co-routine paradigm where it allows one to better
+       control the startup of a co-routine.
+       [Ralf S. Engelschall, Jens Andersen <Jens@trw.nl>]
+ 
+    *) Fixed pthread_cancel(): a switch statement was incorrect (three
+       breaks were missing to stop falling through).
+       [Jens Andersen <Jens@trw.nl>]
+ 
+    *) Change internal `_pthread' prefix to `__pthread'.
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced backward compatibility stuff for Pthread draft 4 (DCE Threads)
+       in pthread.h.in: When _POSIX_BACKCOMPAT is defined before the pthread.h
+       header is included one now gets a lot more backward compatibility
+       mappings.
+       [Ralf S. Engelschall]
+ 
+    *) Optimize internal processing by inlining various small functions from
+       pth_ring.c, pth_pqueue.c and pth_sched.c which are called a lot.
+       [Ralf S. Engelschall]
+ 
+    *) Optimized readline() in test_common.c
+       [Ralf S. Engelschall]
+ 
+    *) Added specific support for Linux/glibc/mc68000 to pth_mctx.c
+       [Roman Hodek <Roman.Hodek@informatik.uni-erlangen.de>]
+ 
+    *) Updated INSTALL document for --enable-optimize.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1.2 and 1.1.3 (23-Aug-1999 to 27-Aug-1999)
+ 
+    *) Enhanced test program of AC_CHECK_STACKGROWTH in aclocal.m4 to
+       make sure the test variables are not optimized away by the
+       compiler and this way lead to incorrect check results.
+       [Martin Kraemer <martin.kraemer@mch.sni.de>, Ralf S. Engelschall]
+ 
+    *) Fixed default stack size: was 32*16384 (=512KB) instead
+       of the intended 32*1024 (=32KB).
+       [Ralf S. Engelschall]
+ 
+    *) Added --enable-optimize flag to configure with selected
+       standard optimization flags of GCC.
+       [Ralf S. Engelschall]
+ 
+    *) Added SUPPORT file to source tree.
+       [Ralf S. Engelschall]
+ 
+    *) Added test_philo, Dijkstra's Five Dining Philosophers ;)
+       [Ralf S. Engelschall]
+ 
+    *) Add "auto" qualifier to PTH_STACKGROWTH test program
+       to make sure the variables are placed into the stack.
+       [Ralf S. Engelschall]
+ 
+    *) Use predetermined $PLATFORM of configure also in Makefile
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1.1 and 1.1.2 (21-Aug-1999 to 23-Aug-1999)
+ 
+    *) Fixed Makefile.in: pth_acdef.h and pth_acmac.h were not removed on
+       "distclean" and this way they were accidently distributed.
+       [Ralf S. Engelschall]
+ 
+    *) Changed return type of pth_yield() from `void' to `int' to
+       be able to return an error FALSE/EINVAL in case the `tid'
+       argument specified an invalid or still not ready thread.
+       [Kurt D. Zeilenga <Kurt@OpenLDAP.Org>, Ralf S. Engelschall]
+ 
+    *) Fixed description of pth_yield() in pth.pod.
+       [Kurt D. Zeilenga <Kurt@OpenLDAP.Org>, Ralf S. Engelschall]
+ 
+   Changes between 1.1.0 and 1.1.1 (19-Aug-1999 to 21-Aug-1999)
+ 
+    *) Changed pthread_yield_np() from `void' return type to `int' to allow the
+       `#define sched_yield pthread_yield_np' work as expected, because
+       sched_yield has `int' return type per SUSv2.
+       [Kurt D. Zeilenga <Kurt@OpenLDAP.Org>, Ralf S. Engelschall]
+ 
+    *) Fixed problems related to pthread_exit() and pth_exit(): The
+       PTH_EVENT_FUNC internally was used incorrectly by pth_exit() and the
+       implicit initialization was forgotten in pthread_exit().
+       [Kurt D. Zeilenga <Kurt@OpenLDAP.Org>, Ralf S. Engelschall]
+ 
+    *) Added consistency check for `timeout' attribute of pth_poll
+       and various other EINVAL related checks to pth_event.c.
+       [Ralf S. Engelschall]
+ 
+    *) Added consistency check for `abstime' attribute of
+       pthread_cond_timedwait().
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1b7 and 1.1.0 (18-Aug-1999 to 19-Aug-1999)
+ 
+    *) Disable vendor typedefs in pthread.h.in because
+       it caused problems under Solaris.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up the sources a little bit more.
+       [Ralf S. Engelschall]
+ 
+    *) Updated rse-pmt.ps to v0.9.15
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1b6 and 1.1b7 (18-Aug-1999 to 18-Aug-1999)
+ 
+    *) Added test for nested thread operation to test_std.c
+       [Ralf S. Engelschall]
+ 
+    *) Updated rse-pmt.ps to talk about the sigsetjmp(3) problems.
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced the heart of Pth: pth_mctx_set().
+       Instead of the real dispatching functions a plain setjmp(3)/longjmp(3)
+       pair is used for the trampoline trick in order to avoid problems with
+       sigjmp_buf-attached signal stacks on platforms where sigsetjmp(3) does
+       more than it is usuallly expected. This especially fixes `thread spawns
+       thread' problems under HPUX.
+       [Ralf S. Engelschall, Aaron Metzger <ametzger@varcom.com>]
+ 
+   Changes between 1.1b5 and 1.1b6 (17-Aug-1999 to 18-Aug-1999)
+ 
+    *) Fixed return value of pth_write/pth_read.
+       [Eric Newton <ecn@smart.net>, Ralf S. Engelschall]
+ 
+    *) Fixed example in manual page (pth.pod): pth_load()
+       is now pth_ctrl(PTH_CTRL_GETAVLOAD, ...)
+       [Eric Newton <ecn@smart.net>]
+ 
+    *) Fixed warning in pth_high.c related to implicit casting.
+       [Ralf S. Engelschall]
+ 
+    *) Added BS2000 support to config.guess/config.sub.
+       [Martin Kraemer]
+ 
+    *) Fixed a sigaltstack() call in pth_mctx.c: the return code
+       was checked incorrectly.
+       [Ralf S. Engelschall]
+ 
+    *) Updated rse-pmt.ps
+       [Ralf S. Engelschall, Eric Newton <ecn@smart.net>]
+ 
+    *) Fixed a nasty bug in the thread stack allocation: A stack was also
+       allocated for the main thread, but not used. The problem was that an
+       allocated stack has a guardian and this way was checked each time and
+       could lead to a bogus STACK OVERFLOW for the "main" thread.
+       [Ralf S. Engelschall, Martin Kraemer]
+ 
+   Changes between 1.1b4 and 1.1b5 (13-Aug-1999 to 17-Aug-1999)
+ 
+    *) Added draft of forthcoming paper ``Portable Multithreading - The Signal
+       Stack Trick Of User-Space Thread Creation'' to source tree under
+       rse-pmt.ps. Hackers are encouraged to read this if they want to
+       understand Pth's internals.
+       [Ralf S. Engelschall]
+ 
+    *) Source cleanups: added `extern' qualifier to function prototypes in
+       pth.h.in and pthread.h.in; make compilation silent with both gcc 2.95.1 C
+       and C++ frontends by fixing implicit type conversion situations, etc.
+       [Ralf S. Engelschall]
+ 
+    *) Return EBUSY instead of EAGAIN for pth_mutex_acquire() when the "try"
+       argument is TRUE. This fixes especially the POSIX semantics of
+       pthread_mutex_trylock().
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_compat.c with strerror(3) replacement for SunOS.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed pthread_{mutex,rwlock,cond}_destroy() functions.
+       [Ralf S. Engelschall]
+ 
+    *) Added support for `configure <platform-id>'.
+       [Ralf S. Engelschall, Martin Kraemer <Martin.Kraemer@mch.sni.de>]
+ 
+   Changes between 1.1b3 and 1.1b4 (11-Aug-1999 to 13-Aug-1999)
+ 
+    *) Fixed blocking semantics of pth_writev().
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a very nasty bug in pth_select(): The write fd_set was passed
+       twice to the scheduler (once as the write fd_set and once as the
+       execptional fd_set). This caused problems, because the event loop this
+       way deleted bits in the write fd_set by accident and the return semantic
+       was broken.
+       [Ralf S. Engelschall]
+ 
+    *) Added fallbacks for UIO_MAXIOV to pth.h and pthread.h
+       [Ralf S. Engelschall]
+ 
+    *) Remove locking check in pth_mutex_init() because this would only work
+       with static vars where ANSI C guarranties an initialization with 0
+       bytes.
+       [Martin Kraemer <Martin.Kraemer@mch.sni.de>]
+ 
+    *) Fixed pth_write() semantics.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1b2 and 1.1b3 (10-Aug-1999 to 11-Aug-1999)
+ 
+    *) Overhauled pthread.h to make it better compile-able also under
+       platforms where a vendor Pthread library exists.
+       [Ralf S. Engelschall]
+ 
+    *) Reordered ingredients of configure.in.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed aclocal.m4: -g was incorrectly stripped.
+       [Ralf S. Engelschall]
+ 
+    *) Enhance pth_write(): In non-blocking (default) mode it now mimics the
+       behaviour of write(2) more correctly by iterating until all data is
+       written or an error occurs.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.1b1 and 1.1b2 (07-Aug-1999 to 10-Aug-1999)
+ 
+    *) Fixed ring walking inside both public pth_msgport_find() function and
+       the internal pth_mutex_releaseall() function.
+       [Laurent Vaucher <laurent.vaucher@ficsgrp.com>]
+ 
+   Changes between 1.0.4 and 1.1b1 (03-Aug-1999 to 07-Aug-1999)
+ 
+    *) Fixed test_select.c: a char has to be used for read(2) and not an int.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed AC_CHECK_NSIG test and this way PTH_NSIG define.
+       [Ralf S. Engelschall]
+ 
+    *) Overhauled pth_mctx.c's internals according to latest algorithm of my
+       paper ``Portable Multithreading - The Signal Stack Trick For User-Space
+       Thread Creation''. Especially: sigstack had not restored stack
+       correctly, the signal mask was not inherited correctly; Linux
+       signal mask handling was incorrect, etc.
+       [Ralf S. Engelschall]
+ 
+    *) Adjusted variables in pth_mctx.c to use `volatile' qualifier.
+       [Ralf S. Engelschall]
+ 
+    *) Simplified Makefile.in a little bit by removing $(OBJS)
+       [Ralf S. Engelschall]
+ 
+    *) Replaced the run-time stack growth decision for the guardian in
+       pth_tcb.c with a compile-time decision.
+       [Ralf S. Engelschall]
+ 
+    *) Completly rewritten the configure.in part which deals
+       with the machine context (mctx) implementation: First SVR4/SUSv2
+       makecontext(2) and friends are generally preferred.  Second, the user
+       now can override the decisions via --with-mctx-{mth,dsp,stk}. Third, the
+       pth_mctx.c source was enhanced by using skaddr_xxx() and sksize_xxx()
+       macros which know through Autoconf checks how a stack has to be setup
+       correctly for makecontext(2), sigaltstack(2) and sigstack(2).
+       [Ralf S. Engelschall]
+ 
+    *) Add support to pth_mctx.c for SVR4/SUSv2 makecontext(2)/swapcontext(2)
+       and friends. This way Pth now is best prepared to cover forthcoming Unix
+       flavors, because these are didicated and standadized functions for
+       user-space context switching.
+       [Ralf S. Engelschall]
+ 
+    *) Completely overhauled aclocal.m4
+       [Ralf S. Engelschall]
+ 
+    *) Use GNU config.guess/config.sub instead of GNU shtool guessos
+       for wider support inside GNU libtool.
+       [Ralf S. Engelschall]
+ 
+    *) Replaced switch() over long variables (which aren't covered by
+       traditional C) with an if-else construct in pth_event.c to be more
+       portable.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed timeout handling in pth_select().
+       [Ralf S. Engelschall]
+ 
+    *) Don't free(2) application-supplied stacks on cleanups.
+       [Ralf S. Engelschall]
+ 
+    *) Don't allow an application to change the stack size or address on an
+       pth_attr_t object when its attached to a thread (see pth_attr_of).
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_ext.c for extensional functionality. As a first
+       cut Sfio support is provided by an additional function pth_sfiodisc.
+       This functions is always available, but only reasonably useable when Pth
+       was built with Sfio support (--with-sfio option) and PTH_EXT_SFIO is
+       then defined by pth.h. It is useful for applications which want to use
+       the comprehensive Sfio I/O library with the Pth threading library. Then
+       this function can be used to get an Sfio discipline structure (Sfdisc_t)
+       which can be pushed onto Sfio streams (Sfio_t) in order to let this
+       stream use pth_read(3)/pth_write(2) instead of read(2)/write(2). The
+       benefit is that this way I/O on the Sfio stream does only block the
+       current thread instead of the whole process. The application has to
+       free(3) the Sfdisc_t structure when it is no longer needed.
+       [Ralf S. Engelschall]
+ 
+    *) Added `barrier' synchronization objects. These provide a way to let a
+       group of threads wait at a barrier until the last reached the barrier.
+       It's implemented on top of mutex and condition variable.
+       [Ralf S. Engelschall]
+ 
+    *) Replaced a bogus stdio fgetc() in test_select with pth_read().
+       [Ralf S. Engelschall]
+ 
+    *) Fixed internal pth_debug(3): it now preserved errno to make sure there
+       is no run-time difference in semantics just because of debug messages.
+       [Ralf S. Engelschall]
+ 
+    *) Overhauled the filedescriptor handling:
+       1. There is no longer a requirement to manually switch a filedescriptor
+       into non-blocking mode in order to use it. This is automatically done
+       temporarily inside Pth now. Instead when you now switch a filedescriptor
+       explicitly into non-blocking mode, pth_read(3) or pth_write(3) will
+       never block the current thread as it is the expected behaviour for
+       non-blocking I/O.
+       2. pth_nonblocking(3) was replaced by a more convinient pth_fdmode(3)
+       function which can perform both get and set operations at once.
+       [Ralf S. Engelschall]
+ 
+      _   ___
+     / | / _ \
+     | || | | |
+     | || |_| |
+   __|_(_)___/_____________________________________________________________
+ 
+   Changes between 1.0.4 and 1.0.5 (03-Aug-1999 to 10-Aug-1999)
+ 
+    *) Backport from Pth 1.1b2:
+       Fixed ring walking inside both public pth_msgport_find() function
+       and the internal pth_mutex_releaseall() function.
+       [Laurent Vaucher <laurent.vaucher@ficsgrp.com>]
+ 
+    *) Backport from Pth 1.1b1:
+       In pth_mctx.c the signal stack was not restored correctly.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.1b1:
+       Fixed test_select.c: a char has to be used for read(2) and not an int.
+       And replaced a bogus stdio fgetc() in test_select with pth_read().
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.1b1:
+       Fixed AC_CHECK_NSIG test and this way PTH_NSIG define.
+       [Ralf S. Engelschall]
+ 
+    *) Backport from Pth 1.1b1:
+       Fixed timeout handling in pth_select().
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0.3 and 1.0.4 (30-Jul-1999 to 03-Aug-1999)
+ 
+    *) Fixed two read/write calls: they didn't use the pth_sc wrapper.
+       [Ralf S. Engelschall]
+ 
+    *) Make pth_{read,write}() functions more POSIX compliant by returning 0
+       when the nbytes argument is given as 0.  And make pth_{readv,writev}()
+       functions more POSIX compliant by returning -1/EINVAL when the iovcnt
+       argument is less or equal to 0.
+       [Ralf S. Engelschall]
+ 
+    *) Added missing readv/writev wrappers to pthread.c
+       [Ralf S. Engelschall]
+ 
+    *) Typo fixes in pth.pod
+       [Eric Newton <ecn@smart.net>]
+ 
+    *) Fixed special `--disable-static --enable-shared' situation.
+       [Felix von Leitner <leitner@fefe.de>, Ralf S. Engelschall]
+ 
+    *) Fixed `debug-xx' targets.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0.2 and 1.0.3 (28-Jul-1999 to 30-Jul-1999)
+ 
+    *) Fixed inconsistent and wrong API value: PTH_ATTR_NULL existed and was
+       documented as PTH_ATTR_NONE. But actually the intended and intuitive
+       value was PTH_ATTR_DEFAULT. !BE CAREFUL: This is an API change and
+       requires adjustments in Pth applications!
+       [Ralf S. Engelschall, Eric Newton <ecn@smart.net>]
+ 
+    *) Make sure pthread.h.in doesn't redefine the poll(2) environment
+       under built-time because it's already defined by the included pth.h.
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+ 
+    *) Add readv/writev environment fallback definitions to pthread.h.in.
+       [Ralf S. Engelschall]
+ 
+    *) Support for AmigaOS in pthreads.c: timespec attributes have (correct)
+       ts_ prefix under AmigaOS and not the (bogus) POSIX tv_ prefix
+       [Kriton Kyrimis <kyrimis@cti.gr>]
+ 
+    *) Add `#include <time.h>' for struct timespec to pthread.h.in
+       and removed timespec references in pth.h.in.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed documentation for pth_spawn() and pth_wait().
+       [Ralf S. Engelschall, Eric Newton <ecn@smart.net>]
+ 
+   Changes between 1.0.1 and 1.0.2 (22-Jul-1999 to 28-Jul-1999)
+ 
+    *) Upgraded to GNU shtool 1.4.5.
+       [Ralf S. Engelschall]
+ 
+    *) Added `uninstall' target to Makefile
+       [Ralf S. Engelschall]
+ 
+    *) Cleanup package to conform to the GNU standards: added AUTHORS document;
+       renamed CHANGES to ChangeLog and added NEWS document; renamed LICENSE to
+       COPYING; renamed CREDITS to THANKS; added hint to bug-pth@gnu.org to
+       pth.pod manual.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed HAVE_SIGSTACK alternative in pth_mctx.c
+       [Jim Jagielski <jim@jaguNET.com>]
+ 
+    *) Removed internal "was_blocking" attribute in event structure
+       because it was never used.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed documentation of pth_xxx_init() synchronization functions.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0.0 and 1.0.1 (16-Jul-1999 to 22-Jul-1999)
+ 
+    *) Added missing documentation for pth_timeout().
+       [Ralf S. Engelschall]
+ 
+    *) Moved pthread_p{read,write}() to pth_high.c as pth_p{read,write}()
+       and added syscall wrapper support for it.
+       [Ralf S. Engelschall]
+ 
+    *) Added support for readv(2) and writev(2): There are now
+       four new API functions pth_readv, pth_readv_ev, pth_writev and
+       pth_writev_ev. Additionally on platforms where no native
+       readv(2)/writev(2) exists, the struct iovec is faked and the internal
+       implementation is based on read(2)/write(2). This way the functionality
+       is available everywhere. Finally, the syscall support was extended to
+       cover readv and writev now, too.
+       [Ralf S. Engelschall]
+ 
+    *) Added support for FNDELAY to pth_nonblocking.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up pthread.h and pth.h and added extra forward definitions for
+       struct timeval/timespec to avoid problems on some platforms (like SCO).
+       [Ralf S. Engelschall]
+ 
+    *) Added "make check" as an alias for "make test"
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.4.4 and use new `shtool tarball'
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b8 and 1.0.0 (16-Jul-1999 to 16-Jul-1999)
+ 
+    *) Fixed scheduler reinitialization.
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.4.4-dev.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up syscall stuff: usleep() is not longer mapped because it's too
+       unstandardized, sigwait() is again mapped because it is standardized and
+       those platforms which fail are broken.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed pthread-config.in: -lpth => -lpthread
+       [Ralf S. Engelschall]
+ 
+    *) Downgraded required Autoconf version to 2.12
+       [Ralf S. Engelschall]
+ 
+    *) Moved pth_readline[_ev]() from the Pth API into test_common.c because
+       this function is just a half-way solution (pth_read doesn't use the same
+       buffer) and when one needs buffered I/O it's better to use a _real_ I/O
+       library like Sfio, etc.
+       [Ralf S. Engelschall]
+ 
+    *) Cleanup to Makefile.in
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b7 and 1.0b8 (14-Jul-1999 to 16-Jul-1999)
+ 
+    *) Fixed result handling of stack growth detection.
+       [Ralf S. Engelschall, Frank Carpenter <carpen@nortelnetworks.com>]
+ 
+    *) Added explicit libtool --mode flags in Makefile.in
+       to avoid compiler guessing problems on esoteric platforms.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed broken condition variable handling: the scheduler
+       incorrectly checked the condition variable flags.
+       [Ralf S. Engelschall, Andrew Hunter <esvce@dcs.warwick.ac.uk>]
+ 
+    *) Allow main thread to be joinable to fulfill POSIX.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a nasty bug in the scheduler: the write and exceptional
+       filedescriptor sets were not passed to the select(): ARGL!
+       [Ralf S. Engelschall]
+ 
+    *) Added implicit initialization to pth_syscall.c stuff
+       and pthread.c stuff.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed again static initializations via PTHREAD_XXX_INITIALIZER
+       [Ralf S. Engelschall]
+ 
+    *) Fixed again PTHREAD_ONCE_INIT
+       [Ralf S. Engelschall]
+ 
+    *) Added PTHREAD_CANCELED to pthread.h.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed POSIX pthread_testcancel(): it is defined to have
+       void return type and not int.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b6 and 1.0b7 (14-Jul-1999 to 14-Jul-1999)
+ 
+    *) Replaced FALSE value for PTHREAD_ONCE_INIT in pthread.h with 0 to
+       be not dependent on such defines.
+       [Ralf S. Engelschall, Rick Brownrigg]
+ 
+    *) Disabled syscall soft mapping for usleep because it causes prototype
+       conflicts with unistd.h on some platforms due to the fact that usleep(3)
+       is bad standardized.
+       [Ralf S. Engelschall, Rick Brownrigg]
+ 
+    *) Added pthread_cancel() to POSIX emulation.
+       [Ralf S. Engelschall, Rick Brownrigg]
+ 
+    *) Fixed poll(2)/poll.h detection in Autoconf.
+       [Ralf S. Engelschall, Igor A. Minyukoff <iam@inser.loniis.spb.su>]
+ 
+   Changes between 1.0b5 and 1.0b6 (11-Jul-1999 to 14-Jul-1999)
+ 
+    *) Fixed pth_attr_ctrl(): it failed with EACCES because
+       of incorrect comparisons
+       [Igor A. Minyukoff <iam@inser.loniis.spb.su>]
+ 
+    *) Replaced PTHREAD_{MUTEX,COND,RWLOCK}_INITIALIZER with an alternative
+       implementation to allow the assignment to `static' variables, too.
+       [Ralf S. Engelschall, Rick Brownrigg <brownrig@erg.sri.com>]
+ 
+   Changes between 1.0b4 and 1.0b5 (08-Jul-1999 to 11-Jul-1999)
+ 
+    *) Fixed pth_waitpid() semantics.
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_poll() and pth_poll_ev() with the following trick: it is always
+       present (independent whether the platform has poll(2) or not), because it
+       is (AND HAS TO BE) internally based on pth_select(). The poll function
+       wrapping support was added, too.
+       [Ralf S. Engelschall]
+ 
+    *) Moved pth_init() to the top of all test applications.
+       [Ralf S. Engelschall]
+ 
+    *) Added direct system call mapping support: --enable-syscall-soft
+       enables #define's in pth.h and pthread.h which do a soft-mapping of e.g.
+       read to pth_read. This is _always_ possible. --enable-syscall-hard
+       enables the exportation of syscall wrappers (e.g. read) by the Pth
+       library and the calling of the real system calls via syscall(2), hence
+       this variant is only available when the platform supports syscall(2)
+       [e.g. yes: *BSD, Linux, Solaris, HP/UX, IRIX, UnixWare; no: AIX, SCO5]
+ 
+       For the soft variant the whole application sources have to include
+       pth[read].h and existing libraries (like stdio!) can still block the
+       whole process, while for the hard variant the application sources do not
+       all have to include pth[read].h an existing libraries (including stdio!)
+       magically use Pth's system call wrappers.
+       [Ralf S. Engelschall]
+ 
+    *) Speeded up `configure --help' by not creating the header
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_select_ev() and pth_select() based on the new PTH_EVENT_SELECT
+       and the old PTH_EVENT_TIME events which emulate 4.2BSD's select(2), but
+       suspend only the current thread. Additionally added a select() wrapper to
+       the POSIX wrapper API.
+       [Ralf S. Engelschall]
+ 
+    *) Added PTH_EVENT_SELECT which can be used to suspend the current thread
+       until an event occured in one of three fd _sets_ similar to select(2) but
+       without the timeout facility.
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.4.3. This especially fixes
+       the shared library generation under GNU/Linux now.
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_abort() and a corresponding pthread_abort()
+       for cruel ways to cancel a thread.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed POSIX pread()/pwrite(): Their mutex variables have
+       to be static variables and not local variables.
+       [Ralf S. Engelschall]
+ 
+    *) Added #define for POSIX sched_yield() to pthread.h.in
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b3 and 1.0b4 (07-Jul-1999 to 08-Jul-1999)
+ 
+    *) Added POSIX pread() and pwrite() [parallel I/O] emulation
+       functions to pthread.{ch].
+       [Ralf S. Engelschall]
+ 
+    *) Removed double-definition of the fallback types in pthread.h.in.
+       [Ralf S. Engelschall]
+ 
+    *) Added pthread_atfork() to pthread.c
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_atfork_{push,pop}() functions and moved them together with
+       pth_fork() to a new pth_fork.c source files. Updated also the
+       documentation to describe the new at-fork handlers.
+       [Ralf S. Engelschall]
+ 
+    *) Write still missing documentation for pth_cleanup_{push,pop}()
+       [Ralf S. Engelschall]
+ 
+    *) Fixed again pth_event_concat(): The last attempt was
+       to inefficient and still had a bug.
+       [Igor A. Minyukoff <iam@inser.loniis.spb.su>, Ralf S.  Engelschall]
+ 
+    *) Cleaned up all name references: The official long name is `GNU Portable
+       Threads', the official short name is `GNU Pth' and the common prefix is
+       `pth_' and `PTH_'.
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b2 and 1.0b3 (04-Jul-1999 to 07-Jul-1999)
+ 
+    *) Remove a trailing comma inside an enum in pthread.h.in
+       [Martin Kraemer <martin.kraemer@mch.sni.de>]
+ 
+    *) Added two new API event-related functions which can be used to extract
+       the contents of existing events: pth_event_typeof() and
+       pth_event_extract().
+       [Ralf S. Engelschall]
+ 
+    *) Fixed pth_event_concat(): It was broken because it
+       handled real/non-single-event event rings not correctly.
+       [Igor A. Minyukoff <iam@inser.loniis.spb.su>, Ralf S. Engelschall]
+ 
+    *) Fixed pth_event_walk(): It was broken for PTH_WALK_NEXT
+       [Igor A. Minyukoff <iam@inser.loniis.spb.su>, Ralf S. Engelschall]
+ 
+    *) Fixed memory leak in pth_join()
+       [Igor A. Minyukoff <iam@inser.loniis.spb.su>]
+ 
+    *) Fixed manual page pthread-config.pod
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.4.1 and GNU libtool 1.3.3
+       [Ralf S. Engelschall]
+ 
+    *) Fixed test_pthread.c: sleep(3) requires unistd.h
+       [Ralf S. Engelschall, Martin Kraemer <martin.kraemer@mch.sni.de>]
+ 
+    *) Cleaned up --enable-batch/--enable-pthread
+       [Ralf S. Engelschall]
+ 
+   Changes between 1.0b1 and 1.0b2 (28-Jun-1999 to 04-Jul-1999)
+ 
+    *) Upgraded to GNU shtool 1.4.0
+       [Ralf S. Engelschall]
+ 
+    *) Changed return value type of pth_version() from "int" to "long"
+       to avoid problems with too large numbers.
+       [Ralf S. Engelschall]
+ 
+    *) Simplified internal representation of pth_once_t
+       [Ralf S. Engelschall]
+ 
+    *) !!ATTENTION!! Renamed _anything_ from the old
+       coding-name nps/NPS to the new official name pth/PTH.
+       [Ralf S. Engelschall]
+ 
+    *) Added the new POSIX.1c pthread emulation library
+       (pthread* files). It has to be enabled explicitly
+       via --enable-pthread because it's disabled per default)
+       [Ralf S. Engelschall]
+ 
+    *) Enhanced pthread.pod manual page.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.21 and 1.0b1 (25-Jun-1999 to 28-Jun-1999)
+ 
+    *) Added internal pth_util_cpystrn() to pth_util.c
+       [Ralf S. Engelschall]
+ 
+    *) removed pth_attr(), pth_priority(), pth_detach()
+       [Ralf S. Engelschall]
+ 
+    *) added new pth_attr_*() functions for manipulating pth_attr_t objects;
+       this is now more flexible because those objects now can be also bound to
+       threads when retrieved via pth_attr_of(). THIS IS A HEAVY BUT IMPORTANT
+       API CHANGE! READ THE DOCS AND THE TEST PROGRAMS FOR DETAILS.  SORRY, BUT
+       IS HAS TO BE DONE BEFORE WE ENTER THE STABLE 1.0 VERSIONS.
+       [Ralf S. Engelschall]
+ 
+    *) Added --enable-profile and --enable-batch to Autoconf
+       [Ralf S. Engelschall]
+ 
+    *) Updated pth.pod to reflect latest changes.
+       [Ralf S. Engelschall]
+ 
+    *) Renamed pth_state_* to upper case names.
+       [Ralf S. Engelschall]
+ 
+    *) Moved pth_sigmask() to pth_high.c
+       [Ralf S. Engelschall]
+ 
+    *) Renamed pth_sigraise() to pth_raise() and added support for
+       per-thread signal delivery via pth_raise().
+       [Ralf S. Engelschall]
+ 
+    *) Renamed pth.c to pth_lib.c
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU shtool 1.3.1
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_version() function
+       [Ralf S. Engelschall]
+ 
+    *) Added a real test Makefile target via new test_std.c
+       [Ralf S. Engelschall]
+ 
+    *) Added more references to pth.pod
+       [Ralf S. Engelschall]
+ 
+       ___   ___
+      / _ \ / _ \
+     | | | | (_) |
+     | |_| |\__, |
+   ___\___(_) /_/__________________________________________________________
+ 
+   Changes between 0.9.20 and 0.9.21 (24-Jun-1999 to 25-Jun-1999)
+ 
+    *) Upgraded to final shtool 1.3.0 release version
+       [Ralf S. Engelschall]
+ 
+    *) Removed all variables names from prototypes to avoid conflicts
+       [Ralf S. Engelschall]
+ 
+    *) Removed unnecessary casts for malloc() calls.
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_sigraise() function for later implementing pthread_kill() and
+       currently at least for testing whether a thread still exists in the
+       system (by sending it a signal 0).
+       [Ralf S. Engelschall]
+ 
+    *) Renamed remaining XXX_INITIALIZER to XXX_INIT to be consistent with
+       other init values.
+       [Ralf S. Engelschall]
+ 
+    *) Prefixed all pth_attr_t attributes with "at_"
+       [Ralf S. Engelschall]
+ 
+    *) Removed pth_equal(): we're not such crazy than POSIX...
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.19 and 0.9.20 (21-Jun-1999 to 24-Jun-1999)
+ 
+    *) Upgraded to latest shtool 1.3.0-dev
+       [Ralf S. Engelschall]
+ 
+    *) Changed pth_yield(void) to pth_yield(pth_t) to allow the specification of
+       a thread which should be favored.  This allows the usage of the old
+       concept of co-routines where a thread/routine switches to a particular
+       target thread.
+       [Ralf S. Engelschall]
+ 
+    *) Added hint about async-safety to pth.pod
+       [Ralf S. Engelschall]
+ 
+    *) Added POSIX-style consistency wrapper pth_sigmask() for sigprocmask().
+       [Ralf S. Engelschall]
+ 
+    *) Added try argument to pth_mutex_acquire() to allow us later to
+       emulate POSIX pthread_mutex_trylock()
+       [Ralf S. Engelschall]
+ 
+    *) Moved errno stuff to a new dedicated pth_errno.c source file
+       [Ralf S. Engelschall]
+ 
+    *) Changed function signatures to support return codes with errno
+       [Ralf S. Engelschall]
+ 
+    *) pth_exit(val) in the main() thread now really just terminated the thread
+       and not immediately the process, i.e. the thread goes sleeping until all
+       other threads are gone and then does an exit(val).
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.18 and 0.9.19 (20-Jun-1999 to 21-Jun-1999)
+ 
+    *) Added a POSIX style pth_detach()
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_sync.c with POSIX style mutual exclusion locks (mutex),
+       read-write locks (rwlock) and condition variable (cond) support
+       [Ralf S. Engelschall]
+ 
+    *) Added a trivial mutex demo to test_misc.c
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.17 and 0.9.18 (18-Jun-1999 to 20-Jun-1999)
+ 
+    *) Greatly extended the manual page pth.pod
+       [Ralf S. Engelschall]
+ 
+    *) Added inclusion hack to pthread.h.in
+       [Ralf S. Engelschall]
+ 
+    *) Added per thread cleanup functions pth_cleanup_{push,pop}() modeled
+       directly after the POSIX pthread_cleanup_{push,pop}() functions
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a memory leak related to pth_key_xxx().
+       [Ralf S. Engelschall]
+ 
+    *) Added internal pth_pqueue_contains() function
+       [Ralf S. Engelschall]
+ 
+    *) Added public API function pth_cancel(), pth_cancel_state() and
+       pth_cancel_point() for thread cancellation support modeled after the
+       POSIX thread cancellation facility.
+       [Ralf S. Engelschall]
+ 
+    *) Removed pthread.* stuff. It will be re-integrated later for Pth 1.1.x
+       [Ralf S. Engelschall]
+ 
+    *) Added cancellation flags to pth_attr().
+       [Ralf S. Engelschall]
+ 
+    *) Added cancellation demo support to test_sig.c
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.16 and 0.9.17 (09-Jun-1999 to 18-Jun-1999)
+ 
+    *) Removed pthread_p.h
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to latest shtool 1.3.0-dev
+       [Ralf S. Engelschall]
+ 
+    *) Added stack overflow detection: a SIGSEGV is created when a
+       guardian memory address at the bottom of the stack was
+       overridden. This SIGSEGV can be even catched by the
+       application.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.15 and 0.9.16 (04-Jun-1999 to 09-Jun-1999)
+ 
+    *) Some Autoconf related cleanups.
+       [Ralf S. Engelschall]
+ 
+    *) Added configure --enable-batch for FreeBSD port
+       [Ralf S. Engelschall]
+ 
+    *) Removed TODO file
+       [Ralf S. Engelschall]
+ 
+    *) Moved sigdelete stuff to new pth_util.c source
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_sigwait_ev()
+       [Ralf S. Engelschall]
+ 
+    *) Updated pth.pod for recent changes
+       [Ralf S. Engelschall]
+ 
+    *) Fixed GNU/Linux libc v5 pth_mctx_set() variant
+       [Ralf S. Engelschall, Felix von Leitner <leitner@fefe.de>]
+ 
+   Changes between 0.9.14 and 0.9.15 (01-Jun-1999 to 04-Jun-1999)
+ 
+    *) Upgraded to shtool 1.2.9
+       [Ralf S. Engelschall]
+ 
+    *) Avoid race conditions in emulated sigsetjmp() switching
+       [Ralf S. Engelschall]
+ 
+    *) Added test_sig.c
+       [Ralf S. Engelschall]
+ 
+    *) Fixed getsockopt() call: errlen wasn't initialized
+       [Ralf S. Engelschall, Anton Umnikov <anton@rest.dvgu.ru>]
+ 
+    *) Allow pth_event_walk() also to use PTH_UNTIL_OCCURRED
+       to walk to the next/prev. occurred event in a ring
+       [Ralf S. Engelschall]
+ 
+    *) Completely overhauled the signal processing in the scheduler
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_sigwait() with POSIX semantics
+       [Ralf S. Engelschall]
+ 
+    *) Fixed pth_join(): It returns -1 when only one thread is left
+       [Ralf S. Engelschall]
+ 
+    *) Autoconf now no longer adds -g for gcc unless --enable-debug
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.13 and 0.9.14 (01-Jun-1999 to 01-Jun-1999)
+ 
+    *) Simplified the event construction by removing unnecessary PTH_UNTIL_XX
+       flags and renaming the remaining ones to PTH_UNTIL_YY_XXX.
+       [Ralf S. Engelschall]
+ 
+    *) Renamed PTH_EVENT_IRQ to PTH_EVENT_SIG and implemented it the first time
+       via sigpending()/sigismember().
+       [Ralf S. Engelschall]
+ 
+    *) Documented the event facility in the manual page
+       [Ralf S. Engelschall]
+ 
+    *) Switched TCB's name attribute from "char *" to "char[40]" and copy in the
+       value when spawning. This allows applications to generate the name
+       temporarily only.
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up source code at lots of edges...
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.12 and 0.9.13 (30-May-1999 to 01-Jun-1999)
+ 
+    *) Cleaned up Makefile.in even more
+       [Ralf S. Engelschall]
+ 
+    *) Add stackaddr argument to pth_attr() to allow the application
+       to specificy a particular stack
+       [Ralf S. Engelschall]
+ 
+    *) Added pthread* files which will contain the POSIX.1c threading
+       ("pthread") API wrapper for PTH. This is still work in progress and not
+       enabled per default (one has to use --enable-pthread).
+       [Ralf S. Engelschall]
+ 
+    *) Added SunSoft's pthread_June95.ps document ("PThreads Summary")
+       as pthreads.ps
+       [Ralf S. Engelschall]
+ 
+    *) Update pth.pod to reflect recent changes.
+       [Ralf S. Engelschall]
+ 
+    *) Optimized pth_time_cmp()
+       [Ralf S. Engelschall]
+ 
+    *) Added support for per-thread signal masks
+       [Ralf S. Engelschall]
+ 
+    *) Made pth_mctx_set() more robust: It now uses sigsuspend for
+       waiting, correctly blocks signals and restores SIGUSR1 stuff
+       [Ralf S. Engelschall]
+ 
+    *) Fixed license messages in sources files
+       [Ralf S. Engelschall]
+ 
+    *) Removed const from pth_connect and pth_connect_ev to avoid problems
+       [Ralf S. Engelschall]
+ 
+    *) Make sure Autoconf doesn't add -lnsl twice
+       [Ralf S. Engelschall]
+ 
+    *) Cleaned up pth_mctx.c even more
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.11 and 0.9.12 (28-May-1999 to 30-May-1999)
+ 
+    *) Some fixes to test_httpd.c: init of addrlen, REQ_MAX handling
+       [Ralf S. Engelschall]
+ 
+    *) Allow pth_join(NULL) to join any available terminated thread
+       [Ralf S. Engelschall]
+ 
+    *) Fixed incorrect pth_event_concat() usages: terminated NULL was missing
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_connect, pth_connect_ev and pth_accept_ev functions
+       [Ralf S. Engelschall]
+ 
+    *) Removed unnecessary b_extra stuff from pth_read/pth_write
+       [Ralf S. Engelschall]
+ 
+    *) Removed "intern" on pth_time(), it's a public API function
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_timeout() constructor function
+       [Ralf S. Engelschall]
+ 
+    *) Fixed event handling for all pth_xxx_ev() functions
+       [Ralf S. Engelschall]
+ 
+    *) Use pth_readline_ev() in test_mp to show how pth_xxx_ev() works
+       [Ralf S. Engelschall]
+ 
+    *) Converted pth_nap() and pth_join() to use PTH_MODE_STATIC
+       [Ralf S. Engelschall]
+ 
+    *) Fixed event initialization in event rings
+       [Ralf S. Engelschall]
+ 
+    *) Kicked out the whole "occurred event ring" stuff because it's not really
+       necessary (one can walk through a single ring and check for occurred
+       events easily) and this way two nasty bugs can be fixed and the event
+       manager simplified a lot. pth_wait() not has only one argument
+       and this is a read-only one, i.e. only the occured flag is set
+       in the events in this ring, but the ring is no longer changed.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.10 and 0.9.11 (28-May-1999 to 28-May-1999)
+ 
+    *) Fix warnings in test_httpd.c
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to final shtool 1.2.8
+       [Ralf S. Engelschall]
+ 
+    *) Added PTH_KEY_INIT
+       [Ralf S. Engelschall]
+ 
+    *) Added PTH_MODE_STATIC for statically allocating
+       a per-thread event. This is now used by the various high-level functions
+       to avoid unnecessary alloc/free sequences.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.9 and 0.9.10 (25-May-1999 to 28-May-1999)
+ 
+    *) Cleaned up Makefile.in
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to GNU libtool 1.3.2
+       [Ralf S. Engelschall]
+ 
+    *) Upgraded to new shtool 1.2.8 which includes scpp
+       [Ralf S. Engelschall]
+ 
+    *) Merged all pth_foo.h's into pth_foo.c's with the help of shtool scpp
+       [Ralf S. Engelschall]
+ 
+    *) Updated dependencies after pth_p.h overhauling
+       [Ralf S. Engelschall]
+ 
+    *) Added TODO file
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.8 and 0.9.9 (24-May-1999 to 25-May-1999)
+ 
+    *) Finally converted library generation to use GNU libtool
+       [Ralf S. Engelschall]
+ 
+    *) Add hints to BIND 8 and adns to manual page
+       [Ralf S. Engelschall]
+ 
+    *) Fixed memory leaks in test_httpd and test_mp
+       [Ralf S. Engelschall, Flux <flux@iae.nl>]
+ 
+    *) Fixed typos in manual page
+       [Ralf S. Engelschall]
+ 
+    *) Fix -lsocket -lnsl tests for Siemens platforms
+       [Ralf S. Engelschall]
+ 
+    *) Fix chmod in Autoconf stuff
+       [Ralf S. Engelschall]
+ 
+    *) Removed unneccessary pth_ring_linked()
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.7 and 0.9.8 (23-May-1999 to 24-May-1999)
+ 
+    *) Fixed bug in priority queue element counting (q_num)
+       [Ralf S. Engelschall]
+ 
+    *) pth_spawn() now inherits the attributes from the parent thread
+       [Ralf S. Engelschall]
+ 
+    *) Merged pth_stat() and pth_load() into a generic extensible pth_ctrl()
+       [Ralf S. Engelschall]
+ 
+    *) Added new pth_fork() function
+       [Ralf S. Engelschall]
+ 
+    *) Added depend target to Makefile.in and generated dependencies
+       [Ralf S. Engelschall]
+ 
+    *) Moved joinable argument from pth_attr() to the flags argument
+       [Ralf S. Engelschall]
+ 
+    *) Added PTH_CTRL_GETPRIO and PTH_CTRL_GETNAME.
+       [Ralf S. Engelschall]
+ 
+    *) Typo was everywhere: preemtive => preemptive
+       [Ralf S. Engelschall]
+ 
+    *) Typo was everywhere: occured => occurred
+       [Ralf S. Engelschall]
+ 
+    *) Finished manual page
+       [Ralf S. Engelschall]
+ 
+    *) Removed useless PTH_UNTIL_RUNNING
+       [Ralf S. Engelschall]
+ 
+    *) Replaced errno support with a better variant
+       [Ralf S. Engelschall]
+ 
+    *) Lots of small fixes and portability cleanups
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.6 and 0.9.7 (22-May-1999 to 23-May-1999)
+ 
+    *) Added PORTING document.
+       [Ralf S. Engelschall]
+ 
+    *) Added errno support (pth_errno.[ch]).
+       [Ralf S. Engelschall]
+ 
+    *) Added exponential average load calculations for scheduler.  The current
+       load value can be retrieved by the application through pth_load().
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.5 and 0.9.6 (21-May-1999 to 22-May-1999)
+ 
+    *) Added more documentation.
+       [Ralf S. Engelschall]
+ 
+    *) Autoconf now determines the direction of stack grow and pth_mctx_set()
+       uses this information for sigstack() now.
+       [Ralf S. Engelschall]
+ 
+    *) Fixed acconfig.h
+       [Ralf S. Engelschall]
+ 
+    *) Increased stacksizes (was too small for Solaris and friends)
+       [Ralf S. Engelschall]
+ 
+    *) Switched from BSD-style license to LGPL license
+       [Ralf S. Engelschall]
+ 
+    *) Fixed a nasty bug in scheduler:
+       when a thread was moved from the wait to the ready queue, it's state
+       wasn't changed to pth_state_ready. This way the next time it was handled
+       it was incorrectly filed to the waiting queue (which caused core dumps
+       because the ev_waiting/ev_occurred pointers didn't exist).  This way now
+       the stuff works great also under Solaris!
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.4 and 0.9.5 (21-May-1999 to 21-May-1999)
+ 
+    *) Renamed pth_{get,set}specific() to pth_key_{get,set}data().
+       [Ralf S. Engelschall]
+ 
+    *) Renamed remaining pth_message_xxx() to pth_msgport_xxx()
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_{readline,read,write}_ev() functions which are similar to
+       pth_{readline,read,write}() but have an additional event argument which
+       can be used for timeouts and other parallel events.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.3 and 0.9.4 (14-May-1999 to 21-May-1999)
+ 
+    *) Added ring datastructures (pth_ring.[ch]).
+       [Ralf S. Engelschall]
+ 
+    *) Add an AmigaOS-style message port facility (pth_msg.[ch]).
+       [Ralf S. Engelschall]
+ 
+    *) Added a message port related test program (test_mp.c).
+       [Ralf S. Engelschall]
+ 
+    *) Fix scheduler event management bug: when no I/O events existed
+       plus a next timer but other events (e.g. message ports) already occurred,
+       the scheduler blocked instead of handling the already occurred events
+       first.
+       [Ralf S. Engelschall]
+ 
+    *) Fix bug in event creating: the event occurrence flag has to be cleared in
+       pth_wait() to avoid spinning events which were already occurred.
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.2 and 0.9.3 (14-May-1999 to 14-May-1999)
+ 
+    *) Added pth_once() for later (pthreads!)
+       [Ralf S. Engelschall]
+ 
+    *) Splitted pth.c into pth.c and pth_high.c
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_data.[ch] with pthread style data storage stuff
+       [Ralf S. Engelschall]
+ 
+    *) Moved readline stuff from test_httpd to pth_high.c as pth_readline()
+       [Ralf S. Engelschall]
+ 
+    *) Removed debugging fprintf from test_httpd to speed it up
+       [Ralf S. Engelschall]
+ 
+    *) Fixed listen() call: now uses REQ_MAX for backlog and tests for -1
+       [Ralf S. Engelschall]
+ 
+    *) Fix a polling-related timer bug in the event manager
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.1 and 0.9.2 (13-May-1999 to 14-May-1999)
+ 
+    *) renamed pth_asynchronize() to pth_nonblocking()
+       [Ralf S. Engelschall]
+ 
+    *) removed implicit pth_nonblocking() calls
+       [Ralf S. Engelschall]
+ 
+    *) speeded up pth_accept by optimizing event alloc/free
+       [Ralf S. Engelschall]
+ 
+    *) cleaned up pth_waitpid
+       [Ralf S. Engelschall]
+ 
+    *) Changed semantics of pth_wait(var, NULL): it now means
+       that the events in var are not removed (although their
+       chanining might be changed)
+       [Ralf S. Engelschall]
+ 
+    *) Renamed internal pth_usleep() to pth_time_usleep()
+       [Ralf S. Engelschall]
+ 
+    *) Replaced pth_sleep() with pth_nap() and added
+       two replacement functions: pth_sleep() for a variant
+       of sleep(3) and pth_usleep() for a variant of usleep(3).
+       [Ralf S. Engelschall]
+ 
+    *) Optimized scheduler a little bit by inlining pth_time_{set,add,sub}
+       [Ralf S. Engelschall]
+ 
+    *) Added pth_pqueue_{head,walk} functions and used it in eventmanager
+       [Ralf S. Engelschall]
+ 
+    *) Rewrote pth_sched_eventmanager() without a surrounding loop
+       [Ralf S. Engelschall]
+ 
+    *) Implemented a readline() function to speedup test_httpd
+       [Ralf S. Engelschall]
+ 
+   Changes between 0.9.0 and 0.9.1 (12-May-1999 to 13-May-1999)
+ 
+    *) Imported into CVS repository
+       [Ralf S. Engelschall]
+ 
+   Changes between GENESIS and 0.9.0 (Feb-1999 to 12-May-1999)
+ 
+    *) Created initial version on FreeBSD
+       [Ralf S. Engelschall]
+ 
+    *) Ported to Linux
+       [Ralf S. Engelschall]
+

ossp-pkg/pth/README -> 1.173.2.5 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,83 ----
+    ____  _   _
+   |  _ \| |_| |__
+   | |_) | __| '_ \                    ``Only those who attempt
+   |  __/| |_| | | |                     the absurd can achieve
+   |_|    \__|_| |_|                     the impossible.''
+ 
+   GNU Pth - The GNU Portable Threads
+   Version 1.3.6 (01-Jul-2000)
+ 
+   ABSTRACT
+ 
+   Pth is a very portable POSIX/ANSI-C based library for Unix platforms
+   which provides non-preemptive priority-based scheduling for multiple
+   threads of execution (aka `multithreading') inside event-driven
+   applications. All threads run in the same address space of the server
+   application, but each thread has its own individual program-counter,
+   run-time stack, signal mask and errno variable.
+ 
+   The thread scheduling itself is done in a cooperative way, i.e., the
+   threads are managed by a priority- and event-based non-preemptive
+   scheduler. The intention is, that this way one can achieve better
+   portability and run-time performance than with preemptive scheduling.
+   The event facility allows threads to wait until various types of
+   events occur, including pending I/O on filedescriptors, asynchronous
+   signals, elapsed timers, pending I/O on message ports, thread and
+   process termination, and even customized callback functions.
+ 
+   Additionally Pth provides an optional emulation API for POSIX.1c
+   threads (`Pthreads') which can be used for backward compatibility to
+   existing multithreaded applications.
+ 
+   Finally, Pth guarranties its fixed set of API functionality on
+   all platforms, i.e., functions like pth_poll(3), pth_readv(3) or
+   pth_writev(3) are always available, even if the particular underlaying
+   platform does not actually support their functionality (through the
+   system calls poll(2), readv(2), writev(2), etc).
+ 
+   Although Pth is very feature-rich, it is a rather small threading
+   library. It consists only of approximately 7,000 line (or 300 KB) of
+   ANSI C code which are auto-configured with approximately 400 lines (or
+   60 KB) of Autoconf/m4 macros and which are documented by approximately
+   3,000 lines (or 150 KB) of documentation. Additionally the sources
+   are documented with approximately 3,600 additional lines of comments.
+   As a result, the whole source tree is just about 1.5 MB in size and
+   fits into a small tarball less than 350 KB in size. This allows Pth to
+   fit very well even into the source tree of other applications without
+   bloating it up very much.
+ 
+   Pth was successfully tested on FreeBSD, NetBSD, OpenBSD, BSDI,
+   GNU/Linux, Solaris, HPUX, Tru64 (OSF/1), AIX, IRIX, UnixWare, SCO
+   OpenServer, SINIX, ReliantUNIX, ISC, AmigaOS, Rhapsody (MacOS X), FTX
+   and AUX. And it should should automatically adjust itself to remaining
+   Unix platforms, too.
+ 
+   COPYRIGHT AND LICENSE
+ 
+   Copyright (c) 1999-2000 Ralf S. Engelschall <rse@engelschall.com>
+ 
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+ 
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+   Lesser General Public License for more details.
+ 
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library (see file COPYING); if not, write
+   to the Free Software Foundation, Inc., 59 Temple Place, Suite
+   330, Boston, MA 02111-1307 USA, or contact Ralf S. Engelschall
+   <rse@engelschall.com>.
+ 
+   HOME AND DOCUMENTATION
+ 
+   The documentation and latest release can be found on
+ 
+   http://www.gnu.org/software/pth/
+   ftp://ftp.gnu.org/gnu/pth/
+                                        Ralf S. Engelschall
+                                        rse@engelschall.com
+                                        www.engelschall.com

ossp-pkg/pth/pth.3 -> 1.208.2.5 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,2367 ----
+ .rn '' }`
+ ''' $RCSfile$$Revision$$Date$
+ '''
+ ''' $Log$
+ '''
+ .de Sh
+ .br
+ .if t .Sp
+ .ne 5
+ .PP
+ \fB\\$1\fR
+ .PP
+ ..
+ .de Sp
+ .if t .sp .5v
+ .if n .sp
+ ..
+ .de Ip
+ .br
+ .ie \\n(.$>=3 .ne \\$3
+ .el .ne 3
+ .IP "\\$1" \\$2
+ ..
+ .de Vb
+ .ft CW
+ .nf
+ .ne \\$1
+ ..
+ .de Ve
+ .ft R
+ 
+ .fi
+ ..
+ '''
+ '''
+ '''     Set up \*(-- to give an unbreakable dash;
+ '''     string Tr holds user defined translation string.
+ '''     Bell System Logo is used as a dummy character.
+ '''
+ .tr \(*W-|\(bv\*(Tr
+ .ie n \{\
+ .ds -- \(*W-
+ .ds PI pi
+ .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+ .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+ .ds L" ""
+ .ds R" ""
+ '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+ '''   \*(L" and \*(R", except that they are used on ".xx" lines,
+ '''   such as .IP and .SH, which do another additional levels of
+ '''   double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
+ .ds L' '
+ .ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
+ 'br\}
+ .el\{\
+ .ds -- \(em\|
+ .tr \*(Tr
+ .ds L" ``
+ .ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
+ .ds L' `
+ .ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
+ .ds PI \(*p
+ 'br\}
+ .\"    If the F register is turned on, we'll generate
+ .\"    index entries out stderr for the following things:
+ .\"            TH      Title 
+ .\"            SH      Header
+ .\"            Sh      Subsection 
+ .\"            Ip      Item
+ .\"            X<>     Xref  (embedded
+ .\"    Of course, you have to process the output yourself
+ .\"    in some meaninful fashion.
+ .if \nF \{
+ .de IX
+ .tm Index:\\$1\t\\n%\t"\\$2"
+ ..
+ .nr % 0
+ .rr F
+ .\}
+ .TH pth 3 "01-Jul-2000" "GNU Pth 1.3.5" "GNU Portable Threads"
+ .UC
+ .if n .hy 0
+ .if n .na
+ .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+ .de CQ          \" put $1 in typewriter font
+ .ft CW
+ 'if n "\c
+ 'if t \\&\\$1\c
+ 'if n \\&\\$1\c
+ 'if n \&"
+ \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+ '.ft R
+ ..
+ .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+ .      \" AM - accent mark definitions
+ .bd B 3
+ .      \" fudge factors for nroff and troff
+ .if n \{\
+ .      ds #H 0
+ .      ds #V .8m
+ .      ds #F .3m
+ .      ds #[ \f1
+ .      ds #] \fP
+ .\}
+ .if t \{\
+ .      ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+ .      ds #V .6m
+ .      ds #F 0
+ .      ds #[ \&
+ .      ds #] \&
+ .\}
+ .      \" simple accents for nroff and troff
+ .if n \{\
+ .      ds ' \&
+ .      ds ` \&
+ .      ds ^ \&
+ .      ds , \&
+ .      ds ~ ~
+ .      ds ? ?
+ .      ds ! !
+ .      ds /
+ .      ds q
+ .\}
+ .if t \{\
+ .      ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+ .      ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+ .      ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+ .      ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+ .      ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+ .      ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+ .      ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+ .      ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+ .      ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+ .\}
+ .      \" troff and (daisy-wheel) nroff accents
+ .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+ .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+ .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+ .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+ .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+ .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+ .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+ .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+ .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+ .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+ .ds ae a\h'-(\w'a'u*4/10)'e
+ .ds Ae A\h'-(\w'A'u*4/10)'E
+ .ds oe o\h'-(\w'o'u*4/10)'e
+ .ds Oe O\h'-(\w'O'u*4/10)'E
+ .      \" corrections for vroff
+ .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+ .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+ .      \" for low resolution devices (crt and lpr)
+ .if \n(.H>23 .if \n(.V>19 \
+ \{\
+ .      ds : e
+ .      ds 8 ss
+ .      ds v \h'-1'\o'\(aa\(ga'
+ .      ds _ \h'-1'^
+ .      ds . \h'-1'.
+ .      ds 3 3
+ .      ds o a
+ .      ds d- d\h'-1'\(ga
+ .      ds D- D\h'-1'\(hy
+ .      ds th \o'bp'
+ .      ds Th \o'LP'
+ .      ds ae ae
+ .      ds Ae AE
+ .      ds oe oe
+ .      ds Oe OE
+ .\}
+ .rm #[ #] #H #V #F C
+ .SH "NAME"
+ \fBpth\fR \- GNU Portable Threads
+ .SH "VERSION"
+ GNU Pth 1.3.5 (01-Jul-2000)
+ .SH "SYNOPSIS"
+ .Ip "\fBGlobal Library Management\fR" 4
+ pth_init,
+ pth_kill,
+ pth_ctrl,
+ pth_version.
+ .Ip "\fBThread Attribute Handling\fR" 4
+ pth_attr_of,
+ pth_attr_new,
+ pth_attr_init,
+ pth_attr_set,
+ pth_attr_get,
+ pth_attr_destroy.
+ .Ip "\fBThread Control\fR" 4
+ pth_spawn,
+ pth_once,
+ pth_self,
+ pth_suspend,
+ pth_resume,
+ pth_yield,
+ pth_nap,
+ pth_wait,
+ pth_cancel,
+ pth_abort,
+ pth_raise,
+ pth_join,
+ pth_exit.
+ .Ip "\fBUtilities\fR" 4
+ pth_fdmode,
+ pth_time,
+ pth_timeout,
+ pth_sfiodisc.
+ .Ip "\fBCancellation Management\fR" 4
+ pth_cancel_point,
+ pth_cancel_state.
+ .Ip "\fBEvent Handling\fR" 4
+ pth_event,
+ pth_event_typeof,
+ pth_event_extract,
+ pth_event_concat,
+ pth_event_isolate,
+ pth_event_walk,
+ pth_event_occurred,
+ pth_event_free.
+ .Ip "\fBKey-Based Storage\fR" 4
+ pth_key_create,
+ pth_key_delete,
+ pth_key_setdata,
+ pth_key_getdata.
+ .Ip "\fBMessage Port Communication\fR" 4
+ pth_msgport_create,
+ pth_msgport_destroy,
+ pth_msgport_find,
+ pth_msgport_pending,
+ pth_msgport_put,
+ pth_msgport_get,
+ pth_msgport_reply.
+ .Ip "\fBThread Cleanups\fR" 4
+ pth_cleanup_push,
+ pth_cleanup_pop.
+ .Ip "\fBProcess Forking\fR" 4
+ pth_atfork_push,
+ pth_atfork_pop,
+ pth_fork.
+ .Ip "\fBSynchronization\fR" 4
+ pth_mutex_init,
+ pth_mutex_acquire,
+ pth_mutex_release,
+ pth_rwlock_init,
+ pth_rwlock_acquire,
+ pth_rwlock_release,
+ pth_cond_init,
+ pth_cond_await,
+ pth_cond_notify,
+ pth_barrier_init,
+ pth_barrier_reach.
+ .Ip "\fBGeneralized \s-1POSIX\s0 Replacement \s-1API\s0\fR" 4
+ pth_sigwait_ev,
+ pth_accept_ev,
+ pth_connect_ev,
+ pth_select_ev,
+ pth_poll_ev,
+ pth_read_ev,
+ pth_readv_ev,
+ pth_write_ev,
+ pth_writev_ev.
+ .Ip "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR" 4
+ pth_usleep,
+ pth_sleep,
+ pth_waitpid,
+ pth_sigmask,
+ pth_sigwait,
+ pth_accept,
+ pth_connect,
+ pth_select,
+ pth_poll,
+ pth_read,
+ pth_readv,
+ pth_write,
+ pth_writev,
+ pth_pread,
+ pth_pwrite.
+ .SH "DESCRIPTION"
+ .PP
+ .Vb 5
+ \&  ____  _   _
+ \& |  _ \e| |_| |__
+ \& | |_) | __| '_ \e         ``Only those who attempt
+ \& |  __/| |_| | | |          the absurd can achieve
+ \& |_|    \e__|_| |_|          the impossible.''
+ .Ve
+ \fBPth\fR is a very portable POSIX/ANSI\-C based library for Unix platforms which
+ provides non-preemptive priority-based scheduling for multiple threads of
+ execution (aka `multithreading') inside event-driven applications. All threads
+ run in the same address space of the application process, but each thread has
+ its own individual program counter, run-time stack, signal mask and \f(CWerrno\fR
+ variable.
+ .PP
+ The thread scheduling itself is done in a cooperative way, i.e., the threads
+ are managed and dispatched by a priority- and event-driven non-preemptive
+ scheduler. The intention is that this way both better portability and run-time
+ performance is achieved than with preemptive scheduling. The event facility
+ allows threads to wait until various types of internal and external events
+ occur, including pending I/O on file descriptors, asynchronous signals,
+ elapsed timers, pending I/O on message ports, thread and process termination,
+ and even results of customized callback functions.
+ .PP
+ \fBPth\fR also provides an optional emulation API for POSIX.1c threads
+ (`Pthreads') which can be used for backward compatibility to existing
+ multithreaded applications. See \fBPth\fR's \fIpthread\fR\|(3) manual page for
+ details.
+ .Sh "Threading Background"
+ When programming event-driven applications, usually servers, lots of
+ regular jobs and one-shot requests have to be processed in parallel.
+ To efficiently simulate this parallel processing on uniprocessor
+ machines, we use `multitasking\*(R' -- that is, we have the application
+ ask the operating system to spawn multiple instances of itself. On
+ Unix, typically the kernel implements multitasking in a preemptive and
+ priority-based way through heavy-weight processes spawned with \fIfork\fR\|(2).
+ These processes usually do \fInot\fR share a common address space. Instead
+ they are clearly separated from each other, and are created by direct
+ cloning a process address space (although modern kernels use memory
+ segment mapping and copy-on-write semantics to avoid unnecessary copying
+ of physical memory).
+ .PP
+ The drawbacks are obvious: Sharing data between the processes is
+ complicated, and can usually only be done efficiently through shared
+ memory (but which itself is not very portable). Synchronization is
+ complicated because of the preemptive nature of the Unix scheduler
+ (one has to use \fIatomic\fR locks, etc). The machine's resources can be
+ exhausted very quickly when the server application has to serve too many
+ long-running requests (heavy-weight processes cost memory). And when
+ each request spawns a sub-process to handle it, the server performance
+ and responsiveness is horrible (heavy-weight processes cost time to
+ spawn). Finally, the server application doesn't scale very well with the
+ load because of these resource problems. In practice, lots of tricks
+ are usually used to overcome these problems \- ranging from pre-forked
+ sub-process pools to semi-serialized processing, etc.
+ .PP
+ One of the most elegant ways to solve these resource- and data-sharing
+ problems is to have multiple \fIlight-weight\fR threads of execution
+ inside a single (heavy-weight) process, i.e., to use \fImultithreading\fR.
+ Those \fIthreads\fR usually improve responsiveness and performance of the
+ application, often improve and simplify the internal program structure,
+ and most important, require less system resources than heavy-weight
+ processes. Threads are neither the optimal run-time facility for all
+ types of applications, nor can all applications benefit from them. But
+ at least event-driven server applications usually benefit greatly from
+ using threads.
+ .Sh "The World of Threading"
+ Even though lots of documents exists which describe and define the world
+ of threading, to understand \fBPth\fR, you need only basic knowledge about
+ threading. The following definitions of thread-related terms should at
+ least help you understand thread programming enough to allow you to use
+ \fBPth\fR.
+ .Ip "\fBo\fR \fBprocess\fR vs. \fBthread\fR" 2
+ A process on Unix systems consists of at least the following fundamental
+ ingredients: \fIvirtual memory table\fR, \fIprogram code\fR, \fIprogram
+ counter\fR, \fIheap memory\fR, \fIstack memory\fR, \fIstack pointer\fR, \fIfile
+ descriptor set\fR, \fIsignal table\fR. On every process switch, the kernel
+ saves and restores these ingredients for the individual processes. On
+ the other hand, a thread consists of only a private program counter,
+ stack memory, stack pointer and signal table. All other ingredients, in
+ particular the virtual memory, it shares with the other threads of the
+ same process.
+ .Ip "\fBo\fR \fBkernel-space\fR vs. \fBuser-space\fR threading" 2
+ Threads on a Unix platform traditionally can be implemented either
+ inside kernel-space or user-space. When threads are implemented by the
+ kernel, the thread context switches are performed by the kernel without
+ the application's knowledge. Similarly, when threads are implemented in
+ user-space, the thread context switches are performed by an application
+ library, without the kernel's knowledge. There also are hybrid threading
+ approaches where, typically, a user-space library binds one or more
+ user-space threads to one or more kernel-space threads (there usually
+ called light-weight processes \- or in short LWPs).
+ .Sp
+ User-space threads are usually more portable and can perform faster
+ and cheaper context switches (for instance via \fIswapcontext\fR\|(2) or
+ \fIsetjmp\fR\|(3)/\fIlongjmp\fR\|(3)) than kernel based threads. On the other hand,
+ kernel-space threads can take advantage of multiprocessor machines and
+ don't have any inherent I/O blocking problems. Kernel-space threads are
+ usually scheduled in preemptive way side-by-side with the underlying
+ processes. User-space threads on the other hand use either preemptive or
+ non-preemptive scheduling.
+ .Ip "\fBo\fR \fBpreemtive\fR vs. \fBnon-preemtive\fR thread scheduling" 2
+ In preemptive scheduling, the scheduler lets a thread execute until a
+ blocking situation occurs (usually a function call which would block)
+ or the assigned timeslice elapses. Then it detracts control from the
+ thread without a chance for the thread to object. This is usually
+ realized by interrupting the thread through a hardware interrupt
+ signal (for kernel-space threads) or a software interrupt signal (for
+ user-space threads), like \f(CWSIGALRM\fR or \f(CWSIGVTALRM\fR. In non-preemptive
+ scheduling, once a thread received control from the scheduler it keeps
+ it until either a blocking situation occurs (again a function call which
+ would block and instead switches back to the scheduler) or the thread
+ explicitly yields control back to the scheduler in a cooperative way.
+ .Ip "\fBo\fR \fBconcurrency\fR vs. \fBparallelism\fR" 2
+ Concurrency exists when at least two threads are \fIin progress\fR at the
+ same time. Parallelism arises when at least two threads are \fIexecuting\fR
+ simultaneously. Real parallelism can be only achieved on multiprocessor
+ machines, of course. But one also usually speaks of parallelism or
+ \fIhigh concurrency\fR in the context of preemptive thread scheduling
+ and of \fIlow concurrency\fR in the context of non-preemptive thread
+ scheduling.
+ .Ip "\fBo\fR \fBresponsiveness\fR" 2
+ The responsiveness of a system can be described by the user visible
+ delay until the system responses to an external request. When this delay
+ is small enough and the user doesn't recognize a noticeable delay,
+ the responsiveness of the system is considered good. When the user
+ recognizes or is even annoyed by the delay, the responsiveness of the
+ system is considered bad.
+ .Ip "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasynchronous-safe\fR functions" 2
+ A reentrant function is one that behaves correctly if it is called
+ simultaneously by several threads and then also executes simultaneously.
+ Functions that access global state, such as memory or files, of course,
+ need to be carefully designed in order to be reentrant. Two traditional
+ approaches to solve these problems are caller-supplied states and
+ thread-specific data.
+ .Sp
+ Thread-safety is the avoidance of \fIdata races\fR, i.e., situations
+ in which data is set to either correct or incorrect value depending
+ upon the (unpredictable) order in which multiple threads access and
+ modify the data. So a function is thread-safe when it still behaves
+ semantically correct when called simultaneously by several threads (it
+ is not required that the functions also execute simultaneously). The
+ traditional approach to achieve thread-safety is to wrap a function body
+ with an internal mutual exclusion lock (aka `mutex'). As you should
+ recognize, reentrant is a stronger attribute than thread-safe, because
+ it is harder to achieve and results especially in no run-time contention
+ between threads. So, a reentrant function is always thread-safe, but not
+ vice versa.
+ .Sp
+ Additionally there is a related attribute for functions named
+ asynchronous-safe, which comes into play in conjunction with signal
+ handlers. This is very related to the problem of reentrant functions. An
+ asynchronous-safe function is one that can be called safe and without
+ side-effects from within a signal handler context. Usually very few
+ functions are of this type, because an application is very restricted in
+ what it can perform from within a signal handler (especially what system
+ functions it is allowed to call). The reason mainly is, because only a
+ few system functions are officially declared by \s-1POSIX\s0 as guaranteed to
+ be asynchronous-safe. Asynchronous-safe functions usually have to be
+ already reentrant.
+ .Sh "User-Space Threads"
+ User-space threads can be implemented in various way. The two
+ traditional approaches are:
+ .Ip "\fB1.\fR" 3
+ \fBMatrix-based explicit dispatching between small units of execution:\fR
+ .Sp
+ Here the global procedures of the application are split into small
+ execution units (each is required to not run for more than a few
+ milliseconds) and those units are implemented by separate functions.
+ Then a global matrix is defined which describes the execution (and
+ perhaps even dependency) order of these functions. The main server
+ procedure then just dispatches between these units by calling one
+ function after each other controlled by this matrix. The threads are
+ created by more than one jump-trail through this matrix and by switching
+ between these jump-trails controlled by corresponding occurred events.
+ .Sp
+ This approach gives the best possible performance, because one can
+ fine-tune the threads of execution by adjusting the matrix, and the
+ scheduling is done explicitly by the application itself. It is also very
+ portable, because the matrix is just an ordinary data structure, and
+ functions are a standard feature of \s-1ANSI\s0 C.
+ .Sp
+ The disadvantage of this approach is that it is complicated to write
+ large applications with this approach, because in those applications
+ one quickly gets \fIhundreds\fR\|(!) of execution units and the control flow
+ inside such an application is very hard to understand (because it is
+ interrupted by function borders and one always has to remember the
+ global dispatching matrix to follow it). Additionally, all threads
+ operate on the same execution stack. Although this saves memory, it is
+ often nasty, because one cannot switch between threads in the middle of
+ a function. Thus the scheduling borders are the function borders.
+ .Ip "\fB2.\fR" 3
+ \fBContext-based implicit scheduling between threads of execution:\fR
+ .Sp
+ Here the idea is that one programs the application as with forked
+ processes, i.e., one spawns a thread of execution and this runs from the
+ begin to the end without an interrupted control flow. But the control
+ flow can be still interrupted \- even in the middle of a function.
+ Actually in a preemptive way, similar to what the kernel does for the
+ heavy-weight processes, i.e., every few milliseconds the user-space
+ scheduler switches between the threads of execution. But the thread
+ itself doesn't recognize this and usually (except for synchronization
+ issues) doesn't have to care about this.
+ .Sp
+ The advantage of this approach is that it's very easy to program,
+ because the control flow and context of a thread directly follows
+ a procedure without forced interrupts through function borders.
+ Additionally, the programming is very similar to a traditional and well
+ understood \fIfork\fR\|(2) based approach.
+ .Sp
+ The disadvantage is that although the general performance is increased,
+ compared to using approaches based on heavy-weight processes, it is decreased
+ compared to the matrix-approach above. Because the implicit preemptive
+ scheduling does usually a lot more context switches (every user-space context
+ switch costs some overhead even when it is a lot cheaper than a kernel-level
+ context switch) than the explicit cooperative/non-preemptive scheduling.
+ Finally, there is no really portable \s-1POSIX/ANSI\s0\-C based way to implement
+ user-space preemptive threading. Either the platform already has threads,
+ or one has to hope that some semi-portable package exists for it. And
+ even those semi-portable packages usually have to deal with assembler
+ code and other nasty internals and are not easy to port to forthcoming
+ platforms.
+ .PP
+ So, in short: the matrix-dispatching approach is portable and fast, but
+ nasty to program. The thread scheduling approach is easy to program,
+ but suffers from synchronization and portability problems caused by its
+ preemptive nature.
+ .Sh "The Compromise of Pth"
+ But why not combine the good aspects of both approaches while avoiding
+ their bad aspects? That's the goal of \fBPth\fR. \fBPth\fR implements
+ easy-to-program threads of execution, but avoids the problems of
+ preemptive scheduling by using non-preemptive scheduling instead.
+ .PP
+ This sounds like, and is, a useful approach. Nevertheless, one has to
+ keep the implications of non-preemptive thread scheduling in mind when
+ working with \fBPth\fR. The following list summarizes a few essential
+ points:
+ .Ip "\fBo\fR" 2
+ \fBPth provides maximum portability, but \s-1NOT\s0 the fanciest features\fR.
+ .Sp
+ This is, because it uses a nifty and portable \s-1POSIX/ANSI\s0\-C approach for
+ thread creation (and this way doesn't require any platform dependent
+ assembler hacks) and schedules the threads in non-preemptive way (which
+ doesn't require unportable facilities like \f(CWSIGVTALRM\fR). On the other
+ hand, this way not all fancy threading features can be implemented.
+ Nevertheless the available facilities are enough to provide a robust and
+ full-featured threading system.
+ .Ip "\fBo\fR" 2
+ \fBPth increases the responsiveness and concurrency of an event-driven
+ application, but \s-1NOT\s0 the concurrency of number-crunching applications\fR.
+ .Sp
+ The reason is the non-preemptive scheduling. Number-crunching
+ applications usually require preemptive scheduling to achieve
+ concurrency because of their long \s-1CPU\s0 bursts. For them, non-preemptive
+ scheduling (even together with explicit yielding) provides only the old
+ concept of `coroutines\*(R'. On the other hand, event driven applications
+ benefit greatly from non-preemptive scheduling. They have only short
+ \s-1CPU\s0 bursts and lots of events to wait on, and this way run faster under
+ non-preemptive scheduling because no unnecessary context switching
+ occurs, as it is the case for preemptive scheduling. That's why \fBPth\fR
+ is mainly intended for server type applications, although there is no
+ technical restriction.
+ .Ip "\fBo\fR" 2
+ \fBPth requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR.
+ .Sp
+ This nice fact exists again because of the nature of non-preemptive
+ scheduling, where a function isn't interrupted and this way cannot be
+ reentered before it returned. This is a great portability benefit,
+ because thread-safety can be achieved more easily than reentrance
+ possibility. Especially this means that under \fBPth\fR more existing
+ third-party libraries can be used without side-effects than its the case
+ for other threading systems.
+ .Ip "\fBo\fR" 2
+ \fBPth doesn't require any kernel support, but can \s-1NOT\s0
+ benefit from multiprocessor machines\fR.
+ .Sp
+ This means that \fBPth\fR runs on almost all Unix kernels, because the
+ kernel does not need to be aware of the \fBPth\fR threads (because they
+ are implemented entirely in user-space). On the other hand, it cannot
+ benefit from the existence of multiprocessors, because for this, kernel
+ support would be needed. In practice, this is no problem, because
+ multiprocessor systems are rare, and portability is almost more
+ important than highest concurrency.
+ .Sh "The life cycle of a thread"
+ To understand the \fBPth\fR Application Programming Interface (\s-1API\s0), it
+ helps to first understand the life cycle of a thread in the \fBPth\fR
+ threading system. It can be illustrated with the following directed
+ graph:
+ .PP
+ .Vb 10
+ \&             NEW
+ \&              |
+ \&              V
+ \&      +---> READY ---+
+ \&      |       ^      |
+ \&      |       |      V
+ \&   WAITING <--+-- RUNNING
+ \&                     |
+ \&      :              V
+ \&   SUSPENDED       DEAD
+ .Ve
+ When a new thread is created, it is moved into the \fB\s-1NEW\s0\fR queue of the
+ scheduler. On the next dispatching for this thread, the scheduler picks
+ it up from there and moves it to the \fB\s-1READY\s0\fR queue. This is a queue
+ containing all threads which want to perform a \s-1CPU\s0 burst. There they are
+ queued in priority order. On each dispatching step, the scheduler always
+ removes the thread with the highest priority only. It then increases the
+ priority of all remaining threads by 1, to prevent them from `starving\*(R'.
+ .PP
+ The thread which was removed from the \fB\s-1READY\s0\fR queue is the new
+ \fB\s-1RUNNING\s0\fR thread (there is always just one \fB\s-1RUNNING\s0\fR thread, of
+ course). The \fB\s-1RUNNING\s0\fR thread is assigned execution control. After
+ this thread yields execution (either explicitly by yielding excution
+ or implicitly by calling a function which would block) there are three
+ possibilities: Either it has terminated, then it is moved to the \fB\s-1DEAD\s0\fR
+ queue, or it has events on which it wants to wait, then it is moved into
+ the \fB\s-1WAITING\s0\fR queue. Else it is assumed it wants to perform more \s-1CPU\s0
+ bursts and immediately enters the \fB\s-1READY\s0\fR queue again.
+ .PP
+ Before the next thread is taken out of the \fB\s-1READY\s0\fR queue, the
+ \fB\s-1WAITING\s0\fR queue is checked for pending events. If one or more events
+ occurred, the threads that are waiting on them are immediately moved to
+ the \fB\s-1READY\s0\fR queue.
+ .PP
+ The purpose of the \fB\s-1NEW\s0\fR queue has to do with the fact that in \fBPth\fR
+ a thread never directly switches to another thread. A thread always
+ yields execution to the scheduler and the scheduler dispatches to the
+ next thread. So a freshly spawned thread has to be kept somewhere until
+ the scheduler gets a chance to pick it up for scheduling. That is for
+ what the \fB\s-1NEW\s0\fR queue is for. 
+ .PP
+ The purpose of the \fB\s-1DEAD\s0\fR queue is to support thread joining. When a
+ thread is marked to be unjoinable, it is directly kicked out of the
+ system after it terminated. But when it is joinable, it enters the
+ \fB\s-1DEAD\s0\fR queue. There it remains until another thread joins it.
+ .PP
+ Finally, there is a special separated queue named \fB\s-1SUSPENDED\s0\fR, to where
+ threads can be manually moved from the \fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR
+ queues by the application. The purpose of this special queue is to
+ temporarily absorb suspended threads until they are again resumed by
+ the application. Suspended threads do not cost scheduling or event
+ handling resources, because they are temporarily completely out of the
+ scheduler's scope. If a thread is resumed, it is moved back to the queue
+ from where it originally came and this way again enters the schedulers
+ scope.
+ .SH "APPLICATION PROGRAMMING INTERFACE (API)"
+ In the following the \fBPth\fR \fIApplication Programming Interface\fR (API)
+ is discussed in detail. With the knowledge given above, it should be
+ now easy to understand how to program threads with this API. In good
+ Unix tradition, \fBPth\fR functions use special return values (\f(CWNULL\fR
+ in pointer context, \f(CWFALSE\fR in boolean context and \f(CW-1\fR in integer
+ context) to indicate an error condition and set (or pass through) the
+ \f(CWerrno\fR system variable to pass more details about the error to the
+ caller.
+ .Sh "Global Library Management"
+ The following functions act on the library as a whole.  They are used to
+ initialize and shutdown the scheduler and fetch information from it.
+ .Ip "int \fBpth_init\fR(void);" 4
+ This initializes the \fBPth\fR library. It has to be the first \fBPth\fR \s-1API\s0
+ function call in an application, and is mandatory. It's usually done at
+ the begin of the \fImain()\fR function of the application. This implicitly
+ spawns the internal scheduler thread and transforms the single execution
+ unit of the current process into a thread (the `main\*(R' thread). It
+ returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on error.
+ .Ip "int \fBpth_kill\fR(void);" 4
+ This kills the \fBPth\fR library. It should be the last \fBPth\fR \s-1API\s0 function call
+ in an application, but is not really required. It's usually done at the end of
+ the main function of the application. At least, it has to be called from within
+ the main thread. It implicitly kills all threads and transforms back the
+ calling thread into the single execution unit of the underlying process.  The
+ usual way to terminate a \fBPth\fR application is either a simple
+ `\f(CWpth_exit(0);\fR\*(R' in the main thread (which waits for all other threads to
+ terminate, kills the threading system and then terminates the process) or a
+ `\f(CWpth_kill(); exit(0)\fR\*(R' (which immediately kills the threading system and
+ terminates the process). The \fIpth_kill()\fR return immediately with a return
+ code of \f(CWFALSE\fR if it is called not from within the main thread. Else
+ kills the threading system and returns \f(CWTRUE\fR.
+ .Ip "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);" 4
+ This is a generalized query/control function for the \fBPth\fR library.  The
+ argument \fIquery\fR is a bitmask formed out of one or more \f(CWPTH_CTRL_\fR\fI\s-1XXXX\s0\fR
+ queries. Currently the following queries are supported:
+ .Ip "\f(CWPTH_CTRL_GETTHREADS\fR" 8
+ This returns the total number of threads currently in existence.  This query
+ actually is formed out of the combination of queries for threads in a
+ particular state, i.e., the \f(CWPTH_CTRL_GETTHREADS\fR query is equal to the
+ \s-1OR\s0\-combination of all the following specialized queries:
+ .Sp
+ \f(CWPTH_CTRL_GETTHREADS_NEW\fR for the number of threads in the
+ new queue (threads created via \fIpth_spawn\fR\|(3) but still not
+ scheduled once), \f(CWPTH_CTRL_GETTHREADS_READY\fR for the number of
+ threads in the ready queue (threads who want to do \s-1CPU\s0 bursts),
+ \f(CWPTH_CTRL_GETTHREADS_RUNNING\fR for the number of running threads
+ (always just one thread!), \f(CWPTH_CTRL_GETTHREADS_WAITING\fR for
+ the number of threads in the waiting queue (threads waiting for
+ events), \f(CWPTH_CTRL_GETTHREADS_SUSPENDED\fR for the number of
+ threads in the suspended queue (threads waiting to be resumed) and
+ \f(CWPTH_CTRL_GETTHREADS_DEAD\fR for the number of threads in the new queue
+ (terminated threads waiting for a join).
+ .Ip "\f(CWPTH_CTRL_GETAVLOAD\fR" 8
+ This requires a second argument of type `\f(CWfloat *\fR\*(R' (pointer to a floating
+ point variable).  It stores a floating point value describing the exponential
+ averaged load of the scheduler in this variable. The load is a function from
+ the number of threads in the ready queue of the schedulers dispatching unit.
+ So a load around 1.0 means there is only one ready thread (the standard
+ situation when the application has no high load). A higher load value means
+ there a more threads ready who want to do \s-1CPU\s0 bursts. The average load value
+ updates once per second only. The return value for this query is always 0.
+ .Ip "\f(CWPTH_CTRL_GETPRIO\fR" 8
+ This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a
+ thread.  It returns the priority (ranging from \f(CWPTH_PRIO_MIN\fR to
+ \f(CWPTH_PRIO_MAX\fR) of the given thread.
+ .Ip "\f(CWPTH_CTRL_GETNAME\fR" 8
+ This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a
+ thread. It returns the name of the given thread, i.e., the return value of
+ \fIpth_ctrl\fR\|(3) should be casted to a `\f(CWchar *\fR\*(R'.
+ .Ip "\f(CWPTH_CTRL_DUMPSTATE\fR" 8
+ This requires a second argument of type `\f(CWFILE *\fR\*(R' to which a summary
+ of the internal \fBPth\fR library state is written to. The main information
+ which is currently written out is the current state of the thread pool.
+ .Sp
+ The function returns \f(CW-1\fR on error.
+ .Ip "long \fBpth_version\fR(void);" 4
+ This function returns a hex-value `0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR\*(R' which describes the
+ current \fBPth\fR library version. \fIV\fR is the version, \fI\s-1RR\s0\fR the revisions,
+ \fI\s-1LL\s0\fR the level and \fIT\fR the type of the level (alphalevel=0, betalevel=1,
+ patchlevel=2, etc). For instance \fBPth\fR version 1.0b1 is encoded as 0x100101.
+ The reason for this unusual mapping is that this way the version number is
+ steadily \fIincreasing\fR. The same value is also available under compile time as
+ \f(CWPTH_VERSION\fR.
+ .Sh "Thread Attribute Handling"
+ Attribute objects are used in \fBPth\fR for two things: First stand-alone/unbound
+ attribute objects are used to store attributes for to be spawned threads.
+ Bounded attribute objects are used to modify attributes of already existing
+ threads. The following attribute fields exists in attribute objects:
+ .Ip "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]" 4
+ Thread Priority between \f(CWPTH_PRIO_MIN\fR and \f(CWPTH_PRIO_MAX\fR.
+ The default is \f(CWPTH_PRIO_STD\fR.
+ .Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" 4
+ Name of thread (up to 40 characters are stored only), mainly for debugging
+ purposes.
+ .Ip "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]" 4
+ The thread detachment type, \f(CWTRUE\fR indicates a joinable thread, \f(CWFALSE\fR
+ indicates a detached thread.  When a the is detached after termination it is
+ immediately kicked out of the system instead of inserted into the dead queue.
+ .Ip "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]" 4
+ The thread cancellation state, i.e., a combination of \f(CWPTH_CANCEL_ENABLE\fR or
+ \f(CWPTH_CANCEL_DISABLE\fR and \f(CWPTH_CANCEL_DEFERRED\fR or
+ \f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
+ .Ip "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]" 4
+ The thread stack size in bytes. Use lower values than 64 \s-1KB\s0 with great care!
+ .Ip "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]" 4
+ A pointer to the lower address of a chunk of \fImalloc\fR\|(3)'ed memory for the
+ stack.
+ .Ip "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]" 4
+ The time when the thread was spawned.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]" 4
+ The time when the thread was last dispatched.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]" 4
+ The total time the thread was running.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]" 4
+ The thread start function.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]" 4
+ The thread start argument.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]" 4
+ The scheduling state of the thread, i.e., either \f(CWPTH_STATE_NEW\fR,
+ \f(CWPTH_STATE_READY\fR, \f(CWPTH_STATE_WAITING\fR, or \f(CWPTH_STATE_DEAD\fR
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]" 4
+ The event ring the thread is waiting for.
+ This can be queried only when the attribute object is bound to a thread.
+ .Ip "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]" 4
+ Whether the attribute object is bound (\f(CWTRUE\fR) to a thread or not (\f(CWFALSE\fR).
+ .PP
+ The following \s-1API\s0 functions exists to handle the attribute objects:
+ .Ip "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);" 4
+ This returns a new attribute object \fIbound\fR to thread \fItid\fR.  Any queries on
+ this object directly fetch attributes from \fItid\fR. And attribute modifications
+ directly change \fItid\fR. Use such attribute objects to modify existing threads.
+ .Ip "pth_attr_t \fBpth_attr_new\fR(void);" 4
+ This returns a new \fIunbound\fR attribute object. An implicit \fIpth_attr_init()\fR is
+ done on it. Any queries on this object just fetch stored attributes from it.
+ And attribute modifications just change the stored attributes.  Use such
+ attribute objects to pre-configure attributes for to be spawned threads.
+ .Ip "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);" 4
+ This initializes an attribute object \fIattr\fR to the default values:
+ \f(CWPTH_ATTR_PRIO\fR := \f(CWPTH_PRIO_STD\fR, \f(CWPTH_ATTR_NAME\fR := `\f(CWunknown\fR\*(R',
+ \f(CWPTH_ATTR_JOINABLE\fR := \f(CWTRUE\fR, \f(CWPTH_ATTR_CANCELSTATE\fR :=
+ \f(CWPTH_CANCEL_DEFAULT\fR, \f(CWPTH_ATTR_STACK_SIZE\fR := 64*1024 and
+ \f(CWPTH_ATTR_STACK_ADDR\fR := \f(CWNULL\fR. All other \f(CWPTH_ATTR_*\fR attributes are
+ read-only attributes and don't receive default values in \fIattr\fR, because they
+ exists only for bounded attribute objects.
+ .Ip "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" 4
+ This sets the attribute field \fIfield\fR in \fIattr\fR to a value
+ specified as an additional argument on the variable argument
+ list. The following attribute \fIfields\fR and argument pairs can
+ be used: 
+ .Sp
+ .Vb 6
+ \& PTH_ATTR_PRIO           int
+ \& PTH_ATTR_NAME           char *
+ \& PTH_ATTR_JOINABLE       int
+ \& PTH_ATTR_CANCEL_STATE   unsigned int
+ \& PTH_ATTR_STACK_SIZE     unsigned int 
+ \& PTH_ATTR_STACK_ADDR     char *
+ .Ve
+ .Ip "int \fBpth_attr_get\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" 4
+ This retrieves the attribute field \fIfield\fR in \fIattr\fR and stores its
+ value in the variable specified through a pointer in an additional
+ argument on the variable argument list. The following \fIfields\fR and
+ argument pairs can be used:
+ .Sp
+ .Vb 14
+ \& PTH_ATTR_PRIO           int *
+ \& PTH_ATTR_NAME           char **
+ \& PTH_ATTR_JOINABLE       int *
+ \& PTH_ATTR_CANCEL_STATE   unsigned int *
+ \& PTH_ATTR_STACK_SIZE     unsigned int *
+ \& PTH_ATTR_STACK_ADDR     char **
+ \& PTH_ATTR_TIME_SPAWN     pth_time_t *
+ \& PTH_ATTR_TIME_LAST      pth_time_t *
+ \& PTH_ATTR_TIME_RAN       pth_time_t *
+ \& PTH_ATTR_START_FUNC     void *(**)(void *)
+ \& PTH_ATTR_START_ARG      void **
+ \& PTH_ATTR_STATE          pth_state_t *
+ \& PTH_ATTR_EVENTS         pth_event_t *
+ \& PTH_ATTR_BOUND          int *
+ .Ve
+ .Ip "int \fBpth_attr_destroy\fR(pth_attr_t \fIattr\fR);" 4
+ This destroys a attribute object \fIattr\fR. After this \fIattr\fR is no
+ longer a valid attribute object.
+ .Sh "Thread Control"
+ The following functions control the threading itself and form the main \s-1API\s0 of
+ the \fBPth\fR library.
+ .Ip "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);" 4
+ This spawns a new thread with the attributes given in \fIattr\fR (or
+ \f(CWPTH_ATTR_DEFAULT\fR for default attributes \- which means that thread priority,
+ joinability and cancel state are inherited from the current thread) with the
+ starting point at routine \fIentry\fR. This entry routine is called as
+ `\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))\*(R' inside the new thread unit, i.e., \fIentry\fR's
+ return value is fed to an implicit \fIpth_exit\fR\|(3). So the thread usually can exit
+ by just returning. Nevertheless the thread can also exit explicitly at any
+ time by calling \fIpth_exit\fR\|(3). But keep in mind that calling the \s-1POSIX\s0 function
+ \fIexit\fR\|(3) still terminates the complete process and not just the current thread.
+ .Sp
+ There is no \fBPth\fR\-internal limit on the number of threads one can spawn,
+ except the limit implied by the available virtual memory. \fBPth\fR internally
+ keeps track of thread in dynamic data structures. The function returns
+ \f(CWNULL\fR on error.
+ .Ip "int \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);" 4
+ This is a convenience function which uses a control variable of type
+ \f(CWpth_once_t\fR to make sure a constructor function \fIfunc\fR is called only once
+ as `\fIfunc\fR(\fIarg\fR)\*(R' in the system. In other words: Only the first call to
+ \fIpth_once\fR\|(3) by any thread in the system succeeds. The variable referenced via
+ \fIctrlvar\fR should be declared as `\f(CWpth_once_t\fR \fIvariable-name\fR =
+ \f(CWPTH_ONCE_INIT\fR;\*(R' before calling this function.
+ .Ip "pth_t \fBpth_self\fR(void);" 4
+ This just returns the unique thread handle of the currently running thread.
+ This handle itself has to be treated as an opaque entity by the application.
+ It's usually used as an argument to other functions who require an argument of
+ type \f(CWpth_t\fR.
+ .Ip "int \fBpth_suspend\fR(pth_t \fItid\fR);" 4
+ This suspends a thread \fItid\fR until it is manually resumed again via
+ \fIpth_resume\fR\|(3). For this, the thread is moved to the \fB\s-1SUSPENDED\s0\fR queue
+ and this way is completely out of the scheduler's event handling and
+ thread dispatching scope. Suspending the current thread is not allowed.
+ The function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors.
+ .Ip "int \fBpth_resume\fR(pth_t \fItid\fR);" 4
+ This function resumes a previously suspended thread \fItid\fR, i.e. \fItid\fR
+ has to stay on the \fB\s-1SUSPENDED\s0\fR queue. The thread is moved to the
+ \fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR queue (dependent on what its state was
+ when the \fIpth_suspend\fR\|(3) call were made) and this way again enters the
+ event handling and thread dispatching scope of the scheduler. The
+ function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors.
+ .Ip "int \fBpth_raise\fR(pth_t \fItid\fR, int \fIsig\fR)" 4
+ This function raises a signal for delivery to thread \fItid\fR only.  When one
+ just raises a signal via \fIraise\fR\|(3) or \fIkill\fR\|(2), its delivered to an arbitrary
+ thread which has this signal not blocked.  With \fIpth_raise\fR\|(3) one can send a
+ signal to a thread and its guarantees that only this thread gets the signal
+ delivered. But keep in mind that nevertheless the signals \fIaction\fR is still
+ configured \fIprocess\fR\-wide.  When \fIsig\fR is 0 plain thread checking is
+ performed, i.e., `\f(CWpth_raise(tid, 0)\fR\*(R' returns \f(CWTRUE\fR when thread \fItid\fR
+ still exists in the \fB\s-1PTH\s0\fR system but doesn't send any signal to it.
+ .Ip "int \fBpth_yield\fR(pth_t \fItid\fR);" 4
+ This explicitly yields back the execution control to the scheduler thread.
+ Usually the execution is implicitly transferred back to the scheduler when a
+ thread waits for an event. But when a thread has to do larger \s-1CPU\s0 bursts, it
+ can be reasonable to interrupt it explicitly by doing a few \fIpth_yield\fR\|(3) calls
+ to give other threads a chance to execute, too.  This obviously is the
+ cooperating part of \fBPth\fR.  A thread \fIhas not\fR to yield execution, of
+ course. But when you want to program a server application with good response
+ times the threads should be cooperative, i.e., when they should split their \s-1CPU\s0
+ bursts into smaller units with this call.
+ .Sp
+ Usually one specifies \fItid\fR as \f(CWNULL\fR to indicate to the scheduler that it
+ can freely decide which thread to dispatch next.  But if one wants to indicate
+ to the scheduler that a particular thread should be favored on the next
+ dispatching step, one can specify this thread explicitly. This allows the
+ usage of the old concept of \fIcoroutines\fR where a thread/routine switches to a
+ particular cooperating thread. If \fItid\fR is not \f(CWNULL\fR and points to a \fInew\fR
+ or \fIready\fR thread, it is guaranteed that this thread receives execution
+ control on the next dispatching step. If \fItid\fR is in a different state (that
+ is, not in \f(CWPTH_STATE_NEW\fR or \f(CWPTH_STATE_READY\fR) an error is reported.
+ .Sp
+ The function usually returns \f(CWTRUE\fR for success and only \f(CWFALSE\fR (with
+ \f(CWerrno\fR set to \f(CWEINVAL\fR) if \fItid\fR specified and invalid or still not
+ new or ready thread.
+ .Ip "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);" 4
+ This functions suspends the execution of the current thread until \fInaptime\fR
+ is elapsed. \fInaptime\fR is of type \f(CWpth_time_t\fR and this way has theoretically
+ a resolution of one microsecond. In practice you should neither rely on this
+ nor that the thread is awakened exactly after \fInaptime\fR has elapsed. It's
+ only guarantees that the thread will sleep at least \fInaptime\fR. But because
+ of the non-preemptive nature of \fBPth\fR it can last longer (when another thread
+ kept the \s-1CPU\s0 for a long time). Additionally the resolution is dependent of the
+ implementation of timers by the operating system and these usually have only a
+ resolution of 10 microseconds or larger. But usually this isn't important for
+ an application unless it tries to use this facility for real time tasks.
+ .Ip "int \fBpth_wait\fR(pth_event_t \fIev\fR);" 4
+ This is the link between the scheduler and the event facility (see below for
+ the various \fIpth_event_xxx()\fR functions). It's modeled like \fIselect\fR\|(2), i.e., one
+ gives this function one or more events (in the event ring specified by \fIev\fR)
+ on which the current thread wants to wait.  The scheduler awakes the thread
+ when one ore more of them occurred after tagging them as occurred. The \fIev\fR
+ argument is a \fIpointer\fR to an event ring which isn't changed except for the
+ tagging. \fIpth_wait\fR\|(3) returns the number of occurred events and the application
+ can use \fIpth_event_occurred\fR\|(3) to test which events occurred.
+ .Ip "int \fBpth_cancel\fR(pth_t \fItid\fR);" 4
+ This cancels a thread \fItid\fR. How the cancellation is done depends on the
+ cancellation state of \fItid\fR which the thread can configure itself. When its
+ state is \f(CWPTH_CANCEL_DISABLE\fR a cancellation request is just made pending.
+ When it is \f(CWPTH_CANCEL_ENABLE\fR it depends on the cancellation type what is
+ performed. When its \f(CWPTH_CANCEL_DEFERRED\fR again the cancellation request is
+ just made pending. But when its \f(CWPTH_CANCEL_ASYNCHRONOUS\fR the thread is
+ immediately canceled before \fIpth_cancel\fR\|(3) returns. The effect of a thread
+ cancellation is equal to implicitly forcing the thread to call
+ `\f(CWpth_exit(PTH_CANCELED)\fR\*(R' at one of his cancellation points.  In \fBPth\fR
+ thread enter a cancellation point either explicitly via \fIpth_cancel_point\fR\|(3) or
+ implicitly by waiting for an event.
+ .Ip "int \fBpth_abort\fR(pth_t \fItid\fR);" 4
+ This is the cruel way to cancel a thread \fItid\fR. When it's already dead and
+ waits to be joined it just joins it (via `\f(CWpth_join(\fR\fItid\fR\f(CW, NULL)\fR') and
+ this way kicks it out of the system.  Else it forces the thread to be not
+ joinable and to allow asynchronous cancellation and then cancels it via
+ `\f(CWpth_cancel(\fR\fItid\fR\f(CW)\fR\*(R'.
+ .Ip "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);" 4
+ This joins the current thread with the thread specified via \fItid\fR.  It first
+ suspends the current thread until the \fItid\fR thread has terminated. Then it is
+ awakened and stores the value of \fItid\fR's \fIpth_exit\fR\|(3) call into *\fIvalue\fR (if
+ \fIvalue\fR and not \f(CWNULL\fR) and returns to the caller.  A thread can be joined
+ only when it was \fInot\fR spawned with \f(CWPTH_FLAG_NOJOIN\fR. A thread can only be
+ joined once, i.e., after the \fIpth_join\fR\|(3) call the thread \fItid\fR is removed
+ from the system.
+ .Ip "void \fBpth_exit\fR(void *\fIvalue\fR);" 4
+ This terminates the current thread. Whether it's immediately removed from the
+ system or inserted into the dead queue of the scheduler depends on its join
+ type which was specified at spawning time. When it was spawned with
+ \f(CWPTH_FLAG_NOJOIN\fR it's immediately removed and \fIvalue\fR is ignored.
+ Else the thread is inserted into the dead queue and \fIvalue\fR remembered
+ for a \fIpth_join\fR\|(3) call by another thread.
+ .Sh "Utilities"
+ The following functions are utility functions.
+ .Ip "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);" 4
+ This switches the non-blocking mode flag on file descriptor \fIfd\fR.  The
+ argument \fImode\fR can be \f(CWPTH_FDMODE_BLOCK\fR for switching \fIfd\fR into blocking
+ I/O mode, \f(CWPTH_FDMODE_NONBLOCK\fR for switching \fIfd\fR into non-blocking I/O
+ mode or \f(CWPTH_FDMODE_POLL\fR for just polling the current mode. The current mode
+ is returned (either \f(CWPTH_FDMODE_BLOCK\fR or \f(CWPTH_FDMODE_NONBLOCK\fR) or
+ \f(CWPTH_FDMODE_ERROR\fR on error. Keep in mind that since \fBPth\fR 1.1 there is no
+ longer a requirement to manually switch a file descriptor into non-blocking
+ mode in order to use it. This is automatically done temporarily inside \fBPth\fR.
+ Instead when you now switch a file descriptor explicitly into non-blocking
+ mode, \fIpth_read\fR\|(3) or \fIpth_write\fR\|(3) will never block the current thread.
+ .Ip "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);" 4
+ This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient
+ function to avoid temporary structure values. It returns a \fIpth_time_t\fR
+ structure which holds the absolute time value specified by \fIsec\fR and \fIusec\fR.
+ .Ip "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);" 4
+ This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient
+ function to avoid temporary structure values.  It returns a \fIpth_time_t\fR
+ structure which holds the absolute time value calculated by adding \fIsec\fR and
+ \fIusec\fR to the current time.
+ .Ip "Sfdisc_t *\fBpth_sfiodisc\fR(void);" 4
+ This functions is always available, but only reasonably usable when \fBPth\fR
+ was built with \fBSfio\fR support (\f(CW--with-sfio\fR option) and \f(CWPTH_EXT_SFIO\fR is
+ then defined by \f(CWpth.h\fR. It is useful for applications which want to use the
+ comprehensive \fBSfio\fR I/O library with the \fBPth\fR threading library. Then this
+ function can be used to get an \fBSfio\fR discipline structure (\f(CWSfdisc_t\fR)
+ which can be pushed onto \fBSfio\fR streams (\f(CWSfio_t\fR) in order to let this
+ stream use \fIpth_read\fR\|(3)/\fIpth_write\fR\|(2) instead of \fIread\fR\|(2)/\fIwrite\fR\|(2). The benefit
+ is that this way I/O on the \fBSfio\fR stream does only block the current thread
+ instead of the whole process. The application has to \fIfree\fR\|(3) the \f(CWSfdisc_t\fR
+ structure when it is no longer needed. The Sfio package can be found at
+ http://www.research.att.com/sw/tools/sfio/.
+ .Sh "Cancellation Management"
+ \fBPth\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the
+ following two related functions:
+ .Ip "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);" 4
+ This manages the cancellation state of the current thread.  When \fIoldstate\fR
+ is not \f(CWNULL\fR the function stores the old cancellation state under the
+ variable pointed to by \fIoldstate\fR. When \fInewstate\fR is not \f(CW0\fR it sets the
+ new cancellation state. \fIoldstate\fR is created before \fInewstate\fR is set.  A
+ state is a combination of \f(CWPTH_CANCEL_ENABLE\fR or \f(CWPTH_CANCEL_DISABLE\fR and
+ \f(CWPTH_CANCEL_DEFERRED\fR or \f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
+ \f(CWPTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED\fR (or \f(CWPTH_CANCEL_DEFAULT\fR) is the
+ default state where cancellation is possible but only at cancellation points.
+ Use \f(CWPTH_CANCEL_DISABLE\fR to complete disable cancellation for a thread and
+ \f(CWPTH_CANCEL_ASYNCHRONOUS\fR for allowing asynchronous cancellations, i.e.,
+ cancellations which can happen at any time.
+ .Ip "void \fBpth_cancel_point\fR(void);" 4
+ This explicitly enter a cancellation point. When the current cancellation
+ state is \f(CWPTH_CANCEL_DISABLE\fR or no cancellation request is pending, this has
+ no side-effect and returns immediately. Else it calls
+ `\f(CWpth_exit(PTH_CANCELED)\fR\*(R'.
+ .Sh "Event Handling"
+ \fBPth\fR has a very flexible event facility which is linked into the scheduler
+ through the \fIpth_wait\fR\|(3) function. The following functions provide the handling
+ of event rings.
+ .Ip "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);" 4
+ This creates a new event ring consisting of a single initial event.  The type
+ of the generated event is specified by \fIspec\fR. The following types are
+ available:
+ .Ip "\f(CWPTH_EVENT_FD\fR" 8
+ This is a file descriptor event. One or more of \f(CWPTH_UNTIL_FD_READABLE\fR,
+ \f(CWPTH_UNTIL_FD_WRITEABLE\fR or \f(CWPTH_UNTIL_FD_EXECPTION\fR have to be \s-1OR\s0\-ed into
+ \fIspec\fR to specify on which state of the file descriptor you want to wait.  The
+ file descriptor itself has to be given as an additional argument.  Example:
+ `\f(CWpth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\fR\*(R'.
+ .Ip "\f(CWPTH_EVENT_SELECT\fR" 8
+ This is a multiple file descriptor event modeled directly after the \fIselect\fR\|(2)
+ call (actually it is also used to implement \fIpth_select\fR\|(3) internally).  It's a
+ convenient way to wait for a large set of file descriptors at once and at each
+ file descriptor for a different type of state. Additionally as a nice
+ side-effect one receives the number of file descriptors which causes the event
+ to be occurred (using \s-1BSD\s0 semantics, i.e., when a file descriptor occurred in
+ two sets it's counted twice). The arguments correspond directly to the
+ \fIselect\fR\|(2) function arguments except that there is no timeout argument (because
+ timeouts already can be handled via \f(CWPTH_EVENT_TIME\fR events).
+ .Sp
+ Example: `\f(CWpth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\fR\*(R' where
+ \f(CWrc\fR has to be of type `\f(CWint *\fR\*(R', \f(CWnfd\fR has to be of type `\f(CWint\fR\*(R' and
+ \f(CWrfds\fR, \f(CWwfds\fR and \f(CWefds\fR have to be of type `\f(CWfd_set *\fR\*(R' (see
+ \fIselect\fR\|(2)). The number of occurred file descriptors are stored in \f(CWrc\fR.
+ .Ip "\f(CWPTH_EVENT_SIGS\fR" 8
+ This is a signal set event. The two additional arguments have to be a pointer
+ to a signal set (type `\f(CWsigset_t *\fR') and a pointer to a signal number
+ variable (type `\f(CWint *\fR').  This event waits until one of the signals in
+ the signal set occurred.  As a result the occurred signal number is stored in
+ the second additional argument. Keep in mind that the \fBPth\fR scheduler doesn't
+ block signals automatically.  So when you want to wait for a signal with this
+ event you've to block it via \fIsigprocmask\fR\|(2) or it will be delivered without
+ your notice. Example: `\f(CWsigemptyset(&set); sigaddset(&set, SIGINT);
+ pth_event(PTH_EVENT_SIG, &set, &sig);\fR\*(R'.
+ .Ip "\f(CWPTH_EVENT_TIME\fR" 8
+ This is a time point event. The additional argument has to be of type
+ \f(CWpth_time_t\fR (usually on-the-fly generated via \fIpth_time\fR\|(3)). This events
+ waits until the specified time point has elapsed. Keep in mind that the value
+ is an absolute time point and not an offset. When you want to wait for a
+ specified amount of time, you've to add the current time to the offset
+ (usually on-the-fly achieved via \fIpth_timeout\fR\|(3)).  Example:
+ `\f(CWpth_event(PTH_EVENT_TIME, pth_timeout(2,0))\fR\*(R'.
+ .Ip "\f(CWPTH_EVENT_MSG\fR" 8
+ This is a message port event. The additional argument has to be of type
+ \f(CWpth_msgport_t\fR. This events waits until one or more messages were received
+ on the specified message port.  Example: `\f(CWpth_event(PTH_EVENT_MSG, mp)\fR\*(R'.
+ .Ip "\f(CWPTH_EVENT_TID\fR" 8
+ This is a thread event. The additional argument has to be of type \f(CWpth_t\fR.
+ One of \f(CWPTH_UNTIL_TID_NEW\fR, \f(CWPTH_UNTIL_TID_READY\fR, \f(CWPTH_UNTIL_TID_WAITING\fR
+ or \f(CWPTH_UNTIL_TID_DEAD\fR has to be \s-1OR\s0\-ed into \fIspec\fR to specify on which
+ state of the thread you want to wait.  Example:
+ `\f(CWpth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\fR\*(R'.
+ .Ip "\f(CWPTH_EVENT_FUNC\fR" 8
+ This is a custom callback function event. Three additional arguments
+ have to be given with the following types: `\f(CWint (*)(void *)\fR\*(R',
+ `\f(CWvoid *\fR\*(R' and `\f(CWpth_time_t\fR\*(R'. The first is a function pointer to
+ a check function and the second argument is a user-supplied context
+ value which is passed to this function. The scheduler calls this
+ function on a regular basis (on his own scheduler stack, so be very
+ careful!) and the thread is kept sleeping while the function returns
+ \f(CWFALSE\fR. Once it returned \f(CWTRUE\fR the thread will be awakend. The
+ check interval is defined by the third argument, i.e., the check
+ function is polled again not until this amount of time elapsed. Example:
+ `\f(CWpth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\fR\*(R'.
+ .Ip "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);" 4
+ This returns the type of event \fIev\fR. It's a combination of the describing
+ \f(CWPTH_EVENT_XX\fR and \f(CWPTH_UNTIL_XX\fR value. This is especially useful to know
+ which arguments have to be supplied to the \fIpth_event_extract\fR\|(3) function.
+ .Ip "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);" 4
+ When \fIpth_event\fR\|(3) is treated like \fIsprintf\fR\|(3), then this function is
+ \fIsscanf\fR\|(3), i.e., it is the inverse operation of \fIpth_event\fR\|(3). This means that
+ it can be used to extract the ingredients of an event.  The ingredients are
+ stored into variables which are given as pointers on the variable argument
+ list.  Which pointers have to be present depends on the event type and has to
+ be determined by the caller before via \fIpth_event_typeof\fR\|(3).
+ .Sp
+ To make it clear, when you constructed \fIev\fR via `\f(CWev =
+ pth_event(PTH_EVENT_FD, fd);\fR\*(R' you have to extract it via
+ `\f(CWpth_event_extract(ev, &fd)\fR\*(R', etc. For multiple arguments of an event the
+ order of the pointer arguments is the same as for \fIpth_event\fR\|(3). But always
+ keep in mind that you have to always supply \fIpointers\fR to \fIvariables\fR and
+ these variables have to be of the same type as the argument of \fIpth_event\fR\|(3)
+ required.
+ .Ip "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);" 4
+ This concatenates one or more additional event rings to the event ring \fIev\fR
+ and returns \fIev\fR. The end of the argument list has to be marked with a
+ \f(CWNULL\fR argument. Use this function to create real events rings out of the
+ single-event rings created by \fIpth_event\fR\|(3).
+ .Ip "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);" 4
+ This isolates the event \fIev\fR from possibly appended events in the event ring.
+ When in \fIev\fR only one event exists, this returns \f(CWNULL\fR. When remaining
+ events exists, they form a new event ring which is returned.
+ .Ip "pth_event_t \fBpth_event_walk\fR(pth_event_t \fIev\fR, int \fIdirection\fR);" 4
+ This walks to the next (when \fIdirection\fR is \f(CWPTH_WALK_NEXT\fR) or previews
+ (when \fIdirection\fR is \f(CWPTH_WALK_PREV\fR) event in the event ring \fIev\fR and
+ returns this new reached event. Additionally \f(CWPTH_UNTIL_OCCURRED\fR can be
+ \s-1OR\s0\-ed into \fIdirection\fR to walk to the next/previous occurred event in the
+ ring \fIev\fR.
+ .Ip "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);" 4
+ This checks whether the event \fIev\fR occurred. This is a fast operation because
+ only a tag on \fIev\fR is checked which was either set or still not set by the
+ scheduler. In other words: This doesn't check the event itself, it just checks
+ the last knowledge of the scheduler.
+ .Ip "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" 4
+ This deallocates the event \fIev\fR (when \fImode\fR is \f(CWPTH_FREE_THIS\fR) or all
+ events appended to the event ring under \fIev\fR (when \fImode\fR is
+ \f(CWPTH_FREE_ALL\fR).
+ .Sh "Key-Based Storage"
+ The following functions provide thread-local storage through unique keys
+ similar to the \s-1POSIX\s0 \fBPthread\fR \s-1API\s0. Use this for thread specific global data.
+ .Ip "int \fBpth_key_create\fR(pth_key_t *\fIkey\fR, void (*\fIfunc\fR)(void *));" 4
+ This created a new unique key and stores it in \fIkey\fR.  Additionally \fIfunc\fR
+ can specify a destructor function which is called on the current threads
+ termination with the \fIkey\fR.
+ .Ip "int \fBpth_key_delete\fR(pth_key_t \fIkey\fR);" 4
+ This explicitly destroys a key \fIkey\fR.
+ .Ip "int \fBpth_key_setdata\fR(pth_key_t \fIkey\fR, const void *\fIvalue\fR);" 4
+ This stores \fIvalue\fR under \fIkey\fR.
+ .Ip "void *\fBpth_key_getdata\fR(pth_key_t \fIkey\fR);" 4
+ This retrieves the value under \fIkey\fR.
+ .Sh "Message Port Communication"
+ The following functions provide message ports which can be used for efficient
+ and flexible inter-thread communication.
+ .Ip "pth_msgport_t \fBpth_msgport_create\fR(const char *\fIname\fR);" 4
+ This returns a pointer to a new message port with name \fIname\fR. The \fIname\fR
+ can be used by other threads via \fIpth_msgport_find\fR\|(3) to find the message port
+ in case they do not know directly the pointer to the message port.
+ .Ip "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);" 4
+ This destroys a message port \fImp\fR. Before all pending messages on it are
+ replied to their origin message port.
+ .Ip "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);" 4
+ This finds a message port in the system by \fIname\fR and returns the pointer to
+ it.
+ .Ip "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);" 4
+ This returns the number of pending messages on message port \fImp\fR.
+ .Ip "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);" 4
+ This puts (or sends) a message \fIm\fR to message port \fImp\fR.
+ .Ip "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);" 4
+ This gets (or receives) the top message from message port \fImp\fR.  Incoming
+ messages are always kept in a queue, so there can be more pending messages, of
+ course.
+ .Ip "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);" 4
+ This replies a message \fIm\fR to the message port of the sender.
+ .Sh "Thread Cleanups"
+ The following functions provide per-thread cleanup functions.
+ .Ip "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);" 4
+ This pushes the routine \fIhandler\fR onto the stack of cleanup routines for the
+ current thread.  These routines are called in \s-1LIFO\s0 order when the thread
+ terminates.
+ .Ip "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);" 4
+ This pops the top-most routine from the stack of cleanup routines for the
+ current thread. When \fIexecute\fR is \f(CWTRUE\fR the routine is additionally called.
+ .Sh "Process Forking"
+ The following functions provide some special support for process forking
+ situations inside the threading environment.
+ .Ip "int \fBpth_atfork_push\fR(void (*\fIprepare\fR)(void *), void (*)(void *\fIparent\fR), void (*)(void *\fIchild\fR), void *\fIarg\fR);" 4
+ This function declares forking handlers to be called before and after
+ \fIpth_fork\fR\|(3), in the context of the thread that called \fIpth_fork\fR\|(3). The
+ \fIprepare\fR handler is called before \fIfork\fR\|(2) processing commences. The
+ \fIparent\fR handler is called   after \fIfork\fR\|(2) processing completes in the parent
+ process.  The \fIchild\fR handler is called after \fIfork\fR\|(2) processing completed in
+ the child process. If no handling is desired at one or more of these three
+ points, the corresponding handler can be given as \f(CWNULL\fR.  Each handler is
+ called with \fIarg\fR as the argument.
+ .Sp
+ The order of calls to \fIpth_atfork_push\fR\|(3) is significant. The \fIparent\fR and
+ \fIchild\fR handlers are called in the order in which they were established by
+ calls to \fIpth_atfork_push\fR\|(3), i.e., \s-1FIFO\s0. The \fIprepare\fR fork handlers are
+ called in the opposite order, i.e., \s-1LIFO\s0.
+ .Ip "int \fBpth_atfork_pop\fR(void);" 4
+ This removes the top-most handlers on the forking handler stack which were
+ established with the last \fIpth_atfork_push\fR\|(3) call. It returns \f(CWFALSE\fR when no
+ more handlers couldn't be removed from the stack.
+ .Ip "pid_t \fBpth_fork\fR(void);" 4
+ This is a variant of \fIfork\fR\|(2) with the difference that the current thread only
+ is forked into a separate process, i.e., in the parent process nothing changes
+ while in the child process all threads are gone except for the scheduler and
+ the calling thread. When you really want to duplicate all threads in the
+ current process you should use \fIfork\fR\|(2) directly. But this is usually not
+ reasonable. Additionally this function takes care of forking handlers as
+ established by \fIpth_fork_push\fR\|(3).
+ .Sh "Synchronization"
+ The following functions provide synchronization support via mutual exclusion
+ locks (\fBmutex\fR), read-write locks (\fBrwlock\fR), condition variables (\fBcond\fR)
+ and barriers (\fBbarrier\fR). Keep in mind that in a non-preemptive threading
+ system like \fBPth\fR this might sound unnecessary at the first look, because a
+ thread isn't interrupted by the system. Actually when you have a critical code
+ section which doesn't contain any \fIpth_xxx()\fR functions, you don't need any
+ mutex to protect it, of course.
+ .PP
+ But when your critical code section contains any \fIpth_xxx()\fR function the chance
+ is high that these temporarily switch to the scheduler. And this way other
+ threads can make progress and enter your critical code section, too.  This is
+ especially true for critical code sections which implicitly or explicitly use
+ the event mechanism.
+ .Ip "int \fBpth_mutex_init\fR(pth_mutex_t *\fImutex\fR);" 4
+ This dynamically initializes a mutex variable of type `\f(CWpth_mutex_t\fR\*(R'.
+ Alternatively one can also use static initialization via `\f(CWpth_mutex_t
+ mutex = PTH_MUTEX_INIT\fR\*(R'.
+ .Ip "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fItry\fR, pth_event_t \fIev\fR);" 4
+ This acquires a mutex \fImutex\fR.  If the mutex is already locked by another
+ thread, the current threads execution is suspended until the mutex is unlocked
+ again or additionally the extra events in \fIev\fR occurred (when \fIev\fR is not
+ \f(CWNULL\fR).  Recursive locking is explicitly supported, i.e., a thread is allowed
+ to acquire a mutex more than once before its released. But it then also has be
+ released the same number of times until the mutex is again lockable by others.
+ When \fItry\fR is \f(CWTRUE\fR this function never suspends execution. Instead it
+ returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
+ .Ip "int \fBpth_mutex_release\fR(pth_mutex_t *\fImutex\fR);" 4
+ This decrements the recursion locking count on \fImutex\fR and when it is zero it
+ releases the mutex \fImutex\fR.
+ .Ip "int \fBpth_rwlock_init\fR(pth_rwlock_t *\fIrwlock\fR);" 4
+ This dynamically initializes a read-write lock variable of type
+ `\f(CWpth_rwlock_t\fR\*(R'.  Alternatively one can also use static initialization
+ via `\f(CWpth_rwlock_t rwlock = PTH_RWLOCK_INIT\fR\*(R'.
+ .Ip "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, int \fItry\fR, pth_event_t \fIev\fR);" 4
+ This acquires a read-only (when \fIop\fR is \f(CWPTH_RWLOCK_RD\fR) or a read-write
+ (when \fIop\fR is \f(CWPTH_RWLOCK_RW\fR) lock \fIrwlock\fR. When the lock is only locked
+ by other threads in read-only mode, the lock succeeds.  But when one thread
+ holds a read-write lock, all locking attempts suspend the current thread until
+ this lock is released again. Additionally in \fIev\fR events can be given to let
+ the locking timeout, etc. When \fItry\fR is \f(CWTRUE\fR this function never suspends
+ execution. Instead it returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
+ .Ip "int \fBpth_rwlock_release\fR(pth_rwlock_t *\fIrwlock\fR);" 4
+ This releases a previously acquired (read-only or read-write) lock.
+ .Ip "int \fBpth_cond_init\fR(pth_cond_t *\fIcond\fR);" 4
+ This dynamically initializes a condition variable variable of type
+ `\f(CWpth_cond_t\fR\*(R'.  Alternatively one can also use static initialization via
+ `\f(CWpth_cond_t cond = PTH_COND_INIT\fR\*(R'.
+ .Ip "int \fBpth_cond_await\fR(pth_cond_t *\fIcond\fR, pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);" 4
+ This awaits a condition situation. The caller has to follow the semantics of
+ the \s-1POSIX\s0 condition variables: \fImutex\fR has to be acquired before this
+ function is called. The execution of the current thread is then suspended
+ either until the events in \fIev\fR occurred (when \fIev\fR is not \f(CWNULL\fR) or
+ \fIcond\fR was notified by another thread via \fIpth_cond_notify\fR\|(3).  While the
+ thread is waiting, \fImutex\fR is released. Before it returns \fImutex\fR is
+ reacquired.
+ .Ip "int \fBpth_cond_notify\fR(pth_cond_t *\fIcond\fR, int \fIbroadcast\fR);" 4
+ This notified one or all threads which are waiting on \fIcond\fR.  When
+ \fIbroadcast\fR is \f(CWTRUE\fR all thread are notified, else only a single
+ (unspecified) one.
+ .Ip "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I<threshold);" 4
+ This dynamically initializes a barrier variable of type `\f(CWpth_barrier_t\fR\*(R'.
+ Alternatively one can also use static initialization via `\f(CWpth_barrier_t
+ barrier = PTH_BARRIER_INIT(\fR\fIthreadhold\fR\f(CW)\fR\*(R'.
+ .Ip "int \fBpth_barrier_reach\fR(pth_barrier_t *\fIbarrier\fR);" 4
+ This function reaches a barrier \fIbarrier\fR. If this is the last thread (as
+ specified by \fIthreshold\fR on init of \fIbarrier\fR) all threads are awakened.
+ Else the current thread is suspended until the last thread reached the barrier
+ and this way awakes all threads. The function returns (beside \f(CWFALSE\fR on
+ error) the value \f(CWTRUE\fR for any thread which neither reached the barrier as
+ the first nor the last thread; \f(CWPTH_BARRIER_HEADLIGHT\fR for the thread which
+ reached the barrier as the first thread and \f(CWPTH_BARRIER_TAILLIGHT\fR for the
+ thread which reached the barrier as the last thread.
+ .Sh "Generalized \s-1POSIX\s0 Replacement \s-1API\s0"
+ The following functions are generalized replacements functions for the \s-1POSIX\s0
+ \s-1API\s0, i.e., they are similar to the functions under `\fBStandard \s-1POSIX\s0
+ Replacement \s-1API\s0\fR\*(R' but all have an additional event argument which can be used
+ for timeouts, etc.
+ .Ip "int \fBpth_sigwait_ev\fR(const sigset_t *\fIset\fR, int *\fIsig\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_sigwait\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_sigwait\fR\|(3) suspends the current threads execution it
+ usually only uses the signal event on \fIset\fR to awake. With this function any
+ number of extra events can be used to awake the current thread (remember that
+ \fIev\fR actually is an event \fIring\fR).
+ .Ip "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_connect\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_connect\fR\|(3) suspends the current threads execution it
+ usually only uses the I/O event on \fIfd\fR to awake. With this function any
+ number of extra events can be used to awake the current thread (remember that
+ \fIev\fR actually is an event \fIring\fR).
+ .Ip "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_accept\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_accept\fR\|(3) suspends the current threads execution it
+ usually only uses the I/O event on \fIfd\fR to awake. With this function any
+ number of extra events can be used to awake the current thread (remember that
+ \fIev\fR actually is an event \fIring\fR).
+ .Ip "int \fBpth_select_ev\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_select\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_select\fR\|(3) suspends the current threads execution it
+ usually only uses the I/O event on \fIrfds\fR, \fIwfds\fR and \fIefds\fR to awake. With
+ this function any number of extra events can be used to awake the current
+ thread (remember that \fIev\fR actually is an event \fIring\fR).
+ .Ip "int \fBpth_poll_ev\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_poll\fR\|(3) (see below), but has an additional event argument
+ \fIev\fR. When \fIpth_poll\fR\|(3) suspends the current threads execution it usually only
+ uses the I/O event on \fIfds\fR to awake. With this function any number of extra
+ events can be used to awake the current thread (remember that \fIev\fR actually
+ is an event \fIring\fR).
+ .Ip "ssize_t \fBpth_read_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_read\fR\|(3) (see below), but has an additional event argument
+ \fIev\fR. When \fIpth_read\fR\|(3) suspends the current threads execution it usually only
+ uses the I/O event on \fIfd\fR to awake. With this function any number of extra
+ events can be used to awake the current thread (remember that \fIev\fR actually
+ is an event \fIring\fR).
+ .Ip "ssize_t \fBpth_readv_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_readv\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_readv\fR\|(3) suspends the current threads execution it
+ usually only uses the I/O event on \fIfd\fR to awake. With this function any
+ number of extra events can be used to awake the current thread (remember that
+ \fIev\fR actually is an event \fIring\fR).
+ .Ip "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_write\fR\|(3) (see below), but has an additional event argument
+ \fIev\fR. When \fIpth_write\fR\|(3) suspends the current threads execution it usually
+ only uses the I/O event on \fIfd\fR to awake. With this function any number of
+ extra events can be used to awake the current thread (remember that \fIev\fR
+ actually is an event \fIring\fR).
+ .Ip "ssize_t \fBpth_writev_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);" 4
+ This is equal to \fIpth_writev\fR\|(3) (see below), but has an additional event
+ argument \fIev\fR. When \fIpth_writev\fR\|(3) suspends the current threads execution it
+ usually only uses the I/O event on \fIfd\fR to awake. With this function any
+ number of extra events can be used to awake the current thread (remember that
+ \fIev\fR actually is an event \fIring\fR).
+ .Sh "Standard \s-1POSIX\s0 Replacement \s-1API\s0"
+ The following functions are standard replacements functions for the \s-1POSIX\s0 \s-1API\s0.
+ The difference is mainly that they suspend the current thread only instead of
+ the whole process in case the file descriptors will block.
+ .Ip "int \fBpth_usleep\fR(unsigned int \fIusec\fR);" 4
+ This is a variant of the 4.3BSD \fIusleep\fR\|(3) function. It suspends the current
+ threads execution until \fIusec\fR microsecond (= \fIusec\fR * 1/1000000 sec)
+ elapsed.  The thread is guaranteed to not awakened before this time, but
+ because of the non-preemptive scheduling nature of \fBPth\fR, it can be awakened
+ later, of course.  The difference between \fIusleep\fR\|(3) and \fIpth_usleep\fR\|(3) is that
+ that \fIpth_usleep\fR\|(3) suspends only the execution of the current thread and not
+ the whole process.
+ .Ip "unsigned int \fBpth_sleep\fR(unsigned int \fIsec\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIsleep\fR\|(3) function. It
+ suspends the current threads execution until \fIsec\fR seconds elapsed.  The
+ thread is guaranteed to not awakened before this time, but because of the
+ non-preemptive scheduling nature of \fBPth\fR, it can be awakened later, of
+ course.  The difference between \fIsleep\fR\|(3) and \fIpth_sleep\fR\|(3) is that that
+ \fIpth_sleep\fR\|(3) suspends only the execution of the current thread and not the
+ whole process.
+ .Ip "pid_t \fBpth_waitpid\fR(pid_t \fIpid\fR, int *\fIstatus\fR, int \fIoptions\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIwaitpid\fR\|(2) function. It suspends the
+ current threads execution until \fIstatus\fR information is available for a
+ terminated child process \fIpid\fR.  The difference between \fIwaitpid\fR\|(2) and
+ \fIpth_waitpid\fR\|(3) is that that \fIpth_waitpid\fR\|(3) suspends only the execution of the
+ current thread and not the whole process.  For more details about the
+ arguments and return code semantics see \fIwaitpid\fR\|(2).
+ .Ip "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)" 4
+ This is the \fBPth\fR thread-related equivalent of \s-1POSIX\s0 \fIsigprocmask\fR\|(2) respectively
+ \fIpthread_sigmask\fR\|(3). The arguments \fIhow\fR, \fIset\fR and \fIoset\fR directly relate
+ to \fIsigprocmask\fR\|(2), because \fBPth\fR internally just uses \fIsigprocmask\fR\|(2) here. So
+ alternatively you can also directly call \fIsigprocmask\fR\|(2), but for consistency
+ reasons you should use this function \fIpth_sigmask\fR\|(3).
+ .Ip "int \fBpth_sigwait\fR(const sigset_t *\fIset\fR, int *\fIsig\fR);" 4
+ This is a variant of the \s-1POSIX\s0.1c \fIsigwait\fR\|(3) function. It suspends the current
+ threads execution until a signal in \fIset\fR occurred and stores the signal
+ number in \fIsig\fR. The important point is that the signal is not delivered to a
+ signal handler. Instead it's caught by the scheduler only in order to awake
+ the \fIpth_sigwait()\fR call. The trick and noticeable point here is that this way
+ you get an asynchronous aware application that is written completely
+ synchronously. When you think about the problem of \fIasynchronous safe\fR
+ functions you should recognize that this is a great benefit.
+ .Ip "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR);" 4
+ This is a variant of the 4.2BSD \fIconnect\fR\|(2) function. It establishes a
+ connection on a socket \fIs\fR to target specified in \fIaddr\fR and \fIaddrlen\fR.
+ The difference between \fIconnect\fR\|(2) and \fIpth_connect\fR\|(3) is that that
+ \fIpth_connect\fR\|(3) suspends only the execution of the current thread and not the
+ whole process.  For more details about the arguments and return code semantics
+ see \fIconnect\fR\|(2).
+ .Ip "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR);" 4
+ This is a variant of the 4.2BSD \fIaccept\fR\|(2) function. It accepts a connection on
+ a socket by extracting the first connection request on the queue of pending
+ connections, creating a new socket with the same properties of \fIs\fR and
+ allocates a new file descriptor for the socket (which is returned).  The
+ difference between \fIaccept\fR\|(2) and \fIpth_accept\fR\|(3) is that that \fIpth_accept\fR\|(3)
+ suspends only the execution of the current thread and not the whole process.
+ For more details about the arguments and return code semantics see \fIaccept\fR\|(2).
+ .Ip "int \fBpth_select\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR);" 4
+ This is a variant of the 4.2BSD \fIselect\fR\|(2) function.  It examines the I/O
+ descriptor sets whose addresses are passed in \fIrfds\fR, \fIwfds\fR, and \fIefds\fR to
+ see if some of their descriptors are ready for reading, are ready for writing,
+ or have an exceptional condition pending, respectively.  For more details
+ about the arguments and return code semantics see \fIselect\fR\|(2).
+ .Ip "int \fBpth_poll\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR);" 4
+ This is a variant of the SysV \fIpoll\fR\|(2) function. It examines the I/O
+ descriptors which are passed in the array \fIfds\fR to see if some of them are
+ ready for reading, are ready for writing, or have an exceptional condition
+ pending, respectively. For more details about the arguments and return code
+ semantics see \fIpoll\fR\|(2).
+ .Ip "ssize_t \fBpth_read\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIread\fR\|(2) function. It reads up to \fInbytes\fR
+ bytes into \fIbuf\fR from file descriptor \fIfd\fR.  The difference between \fIread\fR\|(2)
+ and \fIpth_read\fR\|(2) is that that \fIpth_read\fR\|(2) suspends execution of the current
+ thread until the file descriptor is ready for reading. For more details about
+ the arguments and return code semantics see \fIread\fR\|(2).
+ .Ip "ssize_t \fBpth_readv\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIreadv\fR\|(2) function. It reads data from
+ file descriptor \fIfd\fR into the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
+ difference between \fIreadv\fR\|(2) and \fIpth_readv\fR\|(2) is that that \fIpth_readv\fR\|(2)
+ suspends execution of the current thread until the file descriptor is ready for
+ reading. For more details about the arguments and return code semantics see
+ \fIreadv\fR\|(2).
+ .Ip "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIwrite\fR\|(2) function. It writes \fInbytes\fR bytes
+ from \fIbuf\fR to file descriptor \fIfd\fR.  The difference between \fIwrite\fR\|(2) and
+ \fIpth_write\fR\|(2) is that that \fIpth_write\fR\|(2) suspends execution of the current
+ thread until the file descriptor is ready for writing.  For more details about
+ the arguments and return code semantics see \fIwrite\fR\|(2).
+ .Ip "ssize_t \fBpth_writev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIwritev\fR\|(2) function. It writes data to
+ file descriptor \fIfd\fR from the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
+ difference between \fIwritev\fR\|(2) and \fIpth_writev\fR\|(2) is that that \fIpth_writev\fR\|(2)
+ suspends execution of the current thread until the file descriptor is ready for
+ reading. For more details about the arguments and return code semantics see
+ \fIwritev\fR\|(2).
+ .Ip "ssize_t \fBpth_pread\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIpread\fR\|(3) function.  It performs the same action
+ as a regular \fIread\fR\|(2), except that it reads from a given position in the file
+ without changing the file pointer.  The first three arguments are the same as
+ for \fIpth_read\fR\|(3) with the addition of a fourth argument \fIoffset\fR for the
+ desired position inside the file.
+ .Ip "ssize_t \fBpth_pwrite\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);" 4
+ This is a variant of the \s-1POSIX\s0 \fIpwrite\fR\|(3) function.  It performs the same
+ action as a regular \fIwrite\fR\|(2), except that it writes to a given position in the
+ file without changing the file pointer. The first three arguments are the same
+ as for \fIpth_write\fR\|(3) with the addition of a fourth argument \fIoffset\fR for the
+ desired position inside the file.
+ .SH "EXAMPLE"
+ The following example is a useless server which does nothing more than
+ listening on TCP port 12345 and displaying the current time to the
+ socket when a connection was established. For each incoming connection a
+ thread is spawned. Additionally, to see more multithreading, a useless
+ ticker thread runs simultaneously which outputs the current time to
+ \f(CWstderr\fR every 5 seconds. The example contains \fIno\fR error checking and
+ is \fIonly\fR intended to show you the look and feel of \fBPth\fR.
+ .PP
+ .Vb 11
+ \& #include <stdio.h>
+ \& #include <stdlib.h>
+ \& #include <errno.h>
+ \& #include <sys/types.h>
+ \& #include <sys/socket.h>
+ \& #include <netinet/in.h>
+ \& #include <arpa/inet.h>
+ \& #include <signal.h>
+ \& #include <netdb.h>
+ \& #include <unistd.h>
+ \& #include "pth.h"
+ .Ve
+ .Vb 1
+ \& #define PORT 12345
+ .Ve
+ .Vb 6
+ \& /* the socket connection handler thread */
+ \& static void *handler(void *_arg)
+ \& {
+ \&     int fd = (int)_arg;
+ \&     time_t now;
+ \&     char *ct;
+ .Ve
+ .Vb 6
+ \&     now = time(NULL);
+ \&     ct = ctime(&now);
+ \&     pth_write(fd, ct, strlen(ct));
+ \&     close(fd);
+ \&     return NULL;
+ \& }
+ .Ve
+ .Vb 6
+ \& /* the stderr time ticker thread */
+ \& static void *ticker(void *_arg)
+ \& {
+ \&     time_t now;
+ \&     char *ct;
+ \&     float load;
+ .Ve
+ .Vb 9
+ \&     for (;;) {
+ \&         pth_sleep(5);
+ \&         now = time(NULL);
+ \&         ct = ctime(&now);
+ \&         ct[strlen(ct)-1] = '\e0';
+ \&         pth_ctrl(PTH_CTRL_GETAVLOAD, &load);
+ \&         printf("ticker: time: %s, average load: %.2f\en", ct, load);
+ \&     }
+ \& }
+ .Ve
+ .Vb 10
+ \& /* the main thread/procedure */
+ \& int main(int argc, char *argv[])
+ \& {
+ \&     pth_attr_t attr;
+ \&     struct sockaddr_in sar;
+ \&     struct protoent *pe;
+ \&     struct sockaddr_in peer_addr;
+ \&     int peer_len;
+ \&     int sa, sw;
+ \&     int port;
+ .Ve
+ .Vb 2
+ \&     pth_init();
+ \&     signal(SIGPIPE, SIG_IGN);
+ .Ve
+ .Vb 5
+ \&     attr = pth_attr_new();
+ \&     pth_attr_set(attr, PTH_ATTR_NAME, "ticker");
+ \&     pth_attr_set(attr, PTH_ATTR_STACK_SIZE, 64*1024);
+ \&     pth_attr_set(attr, PTH_ATTR_JOINABLE, FALSE);
+ \&     pth_spawn(attr, ticker, NULL);
+ .Ve
+ .Vb 7
+ \&     pe = getprotobyname("tcp");
+ \&     sa = socket(AF_INET, SOCK_STREAM, pe->p_proto);
+ \&     sar.sin_family = AF_INET;
+ \&     sar.sin_addr.s_addr = INADDR_ANY;
+ \&     sar.sin_port = htons(PORT);
+ \&     bind(sa, (struct sockaddr *)&sar, sizeof(struct sockaddr_in));
+ \&     listen(sa, 10);
+ .Ve
+ .Vb 7
+ \&     pth_attr_set(attr, PTH_ATTR_NAME, "handler");
+ \&     for (;;) {
+ \&         peer_len = sizeof(peer_addr);
+ \&         sw = pth_accept(sa, (struct sockaddr *)&peer_addr, &peer_len);
+ \&         pth_spawn(attr, handler, (void *)sw);
+ \&     }
+ \& }
+ .Ve
+ .SH "BUILD ENVIRONMENTS"
+ In this section we will discuss the canonical ways to establish the build
+ environment for a \fBPth\fR based program. The possibilities supported by \fBPth\fR
+ range from very simple environments to rather complex ones.
+ .Sh "Manual Build Environment (Novice)"
+ As a first example, assume we have the above test program staying in the
+ source file \f(CWfoo.c\fR. Then we can create a very simple build environment by
+ just adding the following \f(CWMakefile\fR:
+ .PP
+ .Vb 13
+ \& $ vi Makefile
+ \& | CC      = cc
+ \& | CFLAGS  = `pth-config --cflags`
+ \& | LDFLAGS = `pth-config --ldflags`
+ \& | LIBS    = `pth-config --libs`
+ \& |
+ \& | all: foo
+ \& | foo: foo.o
+ \& |     $(CC) $(LDFLAGS) -o foo foo.o $(LIBS)
+ \& | foo.o: foo.c
+ \& |     $(CC) $(CFLAGS) -c foo.c
+ \& | clean:
+ \& |     rm -f foo foo.o
+ .Ve
+ This imports the necessary compiler and linker flags on-the-fly from the
+ \fBPth\fR installation via its \f(CWpth-config\fR program. This approach is
+ straight-foreward and works fine for small projects.
+ .Sh "Autoconf Build Environment (Advanced)"
+ The previous approach is simple but unflexible. First, to speed up
+ building, it would be nice to not expand the compiler and linker flags
+ every time the compiler is started. Second, it would be useful to
+ also be able to build against an uninstalled \fBPth\fR, that is, against
+ a \fBPth\fR source tree which was just configured and built, but not
+ installed. Third, it would be also useful to allow checking of the
+ \fBPth\fR version to make sure it is at least a minimum required version.
+ And finally, it would be also great to make sure \fBPth\fR works correctly
+ by first performing some sanity compile and run-time checks. All this
+ can be done if we use \s-1GNU\s0 \fBautoconf\fR and the \f(CWAC_CHECK_PTH\fR macro
+ provided by \fBPth\fR. For this, we establish the following three files:
+ .PP
+ First we again need the \f(CWMakefile\fR, but this time it contains \fBautoconf\fR
+ placeholders and additional cleanup targets. And we create it under the name
+ \f(CWMakefile.in\fR, because it is now an input file for \fBautoconf\fR:
+ .PP
+ .Vb 17
+ \& $ vi Makefile.in
+ \& | CC      = @CC@
+ \& | CFLAGS  = @CFLAGS@
+ \& | LDFLAGS = @LDFLAGS@
+ \& | LIBS    = @LIBS@
+ \& |
+ \& | all: foo
+ \& | foo: foo.o
+ \& |     $(CC) $(LDFLAGS) -o foo foo.o $(LIBS)
+ \& | foo.o: foo.c
+ \& |     $(CC) $(CFLAGS) -c foo.c
+ \& | clean:
+ \& |     rm -f foo foo.o
+ \& | distclean:
+ \& |     rm -f foo foo.o
+ \& |     rm -f config.log config.status config.cache
+ \& |     rm -f Makefile
+ .Ve
+ Because \fBautoconf\fR generates additional files, we added a canonical
+ \f(CWdistclean\fR target which cleanups this, too. Second, we write
+ a (minimalistic) \fBautoconf\fR script specification in a file
+ \f(CWconfigure.in\fR:
+ .PP
+ .Vb 4
+ \& $ vi configure.in
+ \& | AC_INIT(Makefile.in)
+ \& | AC_CHECK_PTH(1.3.0)
+ \& | AC_OUTPUT(Makefile)
+ .Ve
+ Then we let \fBautoconf\fR's \f(CWaclocal\fR program generate for us an \f(CWaclocal.m4\fR
+ file containing \fBPth\fR's \f(CWAC_CHECK_PTH\fR macro. Then we generate the final
+ \f(CWconfigure\fR script out of this \f(CWaclocal.m4\fR file and the \f(CWconfigure.in\fR
+ file:
+ .PP
+ .Vb 2
+ \& $ aclocal --acdir=`pth-config --acdir`
+ \& $ autoconf
+ .Ve
+ After these steps, the working directory should look similar to this:
+ .PP
+ .Vb 6
+ \& $ ls -l
+ \& -rw-r--r--  1 rse  users    176 Nov  3 11:11 Makefile.in
+ \& -rw-r--r--  1 rse  users  15314 Nov  3 11:16 aclocal.m4
+ \& -rwxr-xr-x  1 rse  users  52045 Nov  3 11:16 configure
+ \& -rw-r--r--  1 rse  users     63 Nov  3 11:11 configure.in
+ \& -rw-r--r--  1 rse  users   4227 Nov  3 11:11 foo.c
+ .Ve
+ If we now run \f(CWconfigure\fR we get a correct \f(CWMakefile\fR which
+ immediately can be used to build \f(CWfoo\fR (assuming that \fBPth\fR is already
+ installed somewhere, so that \f(CWpth-config\fR is in \f(CW$PATH\fR):
+ .PP
+ .Vb 16
+ \& $ ./configure
+ \& creating cache ./config.cache
+ \& checking for gcc... gcc
+ \& checking whether the C compiler (gcc   ) works... yes
+ \& checking whether the C compiler (gcc   ) is a cross-compiler... no
+ \& checking whether we are using GNU C... yes
+ \& checking whether gcc accepts -g... yes
+ \& checking how to run the C preprocessor... gcc -E
+ \& checking for GNU Pth... version 1.3.0, installed under /usr/local
+ \& updating cache ./config.cache
+ \& creating ./config.status
+ \& creating Makefile
+ \& rse@en1:/e/gnu/pth/ac
+ \& $ make
+ \& gcc -g -O2 -I/usr/local/include -c foo.c
+ \& gcc -L/usr/local/lib -o foo foo.o -lpth
+ .Ve
+ If \fBPth\fR is installed in non-standard locations or \f(CWpth-config\fR
+ is not in \f(CW$PATH\fR, one just has to drop the \f(CWconfigure\fR script
+ a note about the location by running \f(CWconfigure\fR with the option
+ \f(CW--with-pth=\fR\fIdir\fR (where \fIdir\fR is the argument which was used with
+ the \f(CW--prefix\fR option when \fBPth\fR was installed).
+ .Sh "Autoconf Build Environment with Local Copy of Pth (Expert)"
+ Finally let us assume the \f(CWfoo\fR program stays under either a \fI\s-1GPL\s0\fR or
+ \fI\s-1LGPL\s0\fR distribution license and we want to make it a stand-alone package for
+ easier distribution and installation.  That is, we don't want that the
+ end-user first has to install \fBPth\fR just to allow our \f(CWfoo\fR package to
+ compile. For this, it is a convinient practice to include the required
+ libraries (here \fBPth\fR) into the source tree of the package (here \f(CWfoo\fR).
+ \fBPth\fR ships with all necessary support to allow us to easily achieve this
+ approach. Say, we want \fBPth\fR in a subdirectory named \f(CWpth/\fR and this
+ directory should be seamlessly integrated into the configuration and build
+ process of \f(CWfoo\fR.
+ .PP
+ First we again start with the \f(CWMakefile.in\fR, but this time it is a more
+ advanced version which supports subdirectory movement:
+ .PP
+ .Vb 34
+ \& $ vi Makefile.in
+ \& | CC      = @CC@
+ \& | CFLAGS  = @CFLAGS@
+ \& | LDFLAGS = @LDFLAGS@
+ \& | LIBS    = @LIBS@
+ \& |
+ \& | SUBDIRS = pth
+ \& |
+ \& | all: subdirs_all foo
+ \& |
+ \& | subdirs_all:
+ \& |     @$(MAKE) $(MFLAGS) subdirs TARGET=all
+ \& | subdirs_clean:
+ \& |     @$(MAKE) $(MFLAGS) subdirs TARGET=clean
+ \& | subdirs_distclean:
+ \& |     @$(MAKE) $(MFLAGS) subdirs TARGET=distclean
+ \& | subdirs:
+ \& |     @for subdir in $(SUBDIRS); do \e
+ \& |         echo "===> $$subdir ($(TARGET))"; \e
+ \& |         (cd $$subdir; $(MAKE) $(MFLAGS) $(TARGET) || exit 1) || exit 1; \e
+ \& |         echo "<=== $$subdir"; \e
+ \& |     done
+ \& |
+ \& | foo: foo.o
+ \& |     $(CC) $(LDFLAGS) -o foo foo.o $(LIBS)
+ \& | foo.o: foo.c
+ \& |     $(CC) $(CFLAGS) -c foo.c
+ \& |
+ \& | clean: subdirs_clean
+ \& |     rm -f foo foo.o
+ \& | distclean: subdirs_distclean
+ \& |     rm -f foo foo.o
+ \& |     rm -f config.log config.status config.cache
+ \& |     rm -f Makefile
+ .Ve
+ Then we create a slightly different \fBautoconf\fR script \f(CWconfigure.in\fR:
+ .PP
+ .Vb 6
+ \& $ vi configure.in
+ \& | AC_INIT(Makefile.in)
+ \& | AC_CONFIG_AUX_DIR(pth)
+ \& | AC_CHECK_PTH(1.3.0, subdir:pth --disable-tests)
+ \& | AC_CONFIG_SUBDIRS(pth)
+ \& | AC_OUTPUT(Makefile)
+ .Ve
+ Here we provided a default value for \f(CWfoo\fR's \f(CW--with-pth\fR option as the
+ second argument to \f(CWAC_CHECK_PTH\fR which indicates that \fBPth\fR can be found in
+ the subdirectory named \f(CWpth/\fR. Additionally we specified that the
+ \f(CW--disable-tests\fR option of \fBPth\fR should be passed to the \f(CWpth/\fR
+ subdirectory, because we need only to build the \fBPth\fR library itself. And we
+ added a \f(CWAC_CONFIG_SUBDIR\fR call which indicates to \fBautoconf\fR that it should
+ configure the \f(CWpth/\fR subdirectory, too. The \f(CWAC_CONFIG_AUX_DIR\fR directive
+ was added just to make \fBautoconf\fR happy, because it wants to find a
+ \f(CWinstall.sh\fR or \f(CWshtool\fR script if \f(CWAC_CONFIG_SUBDIRS\fR is used.
+ .PP
+ Now we let \fBautoconf\fR's \f(CWaclocal\fR program again generate for us an
+ \f(CWaclocal.m4\fR file with the contents of \fBPth\fR's \f(CWAC_CHECK_PTH\fR macro.
+ Finally we generate the \f(CWconfigure\fR script out of this \f(CWaclocal.m4\fR
+ file and the \f(CWconfigure.in\fR file.
+ .PP
+ .Vb 2
+ \& $ aclocal --acdir=`pth-config --acdir`
+ \& $ autoconf
+ .Ve
+ Now we have to create the \f(CWpth/\fR subdirectory itself. For this, we extract the
+ \fBPth\fR distribution to the \f(CWfoo\fR source tree and just rename it to \f(CWpth/\fR:
+ .PP
+ .Vb 2
+ \& $ gunzip <pth-X.Y.Z.tar.gz | tar xvf -
+ \& $ mv pth-X.Y.Z pth
+ .Ve
+ Optionally to reduce the size of the \f(CWpth/\fR subdirectory, we can strip down
+ the \fBPth\fR sources to a minimum with the \fIstriptease\fR feature:
+ .PP
+ .Vb 4
+ \& $ cd pth
+ \& $ ./configure
+ \& $ make striptease
+ \& $ cd ..
+ .Ve
+ After this the source tree of \f(CWfoo\fR should look similar to this:
+ .PP
+ .Vb 24
+ \& $ ls -l
+ \& -rw-r--r--  1 rse  users    709 Nov  3 11:51 Makefile.in
+ \& -rw-r--r--  1 rse  users  16431 Nov  3 12:20 aclocal.m4
+ \& -rwxr-xr-x  1 rse  users  57403 Nov  3 12:21 configure
+ \& -rw-r--r--  1 rse  users    129 Nov  3 12:21 configure.in
+ \& -rw-r--r--  1 rse  users   4227 Nov  3 11:11 foo.c
+ \& drwxr-xr-x  2 rse  users   3584 Nov  3 12:36 pth
+ \& $ ls -l pth/
+ \& -rw-rw-r--  1 rse  users   26344 Nov  1 20:12 COPYING
+ \& -rw-rw-r--  1 rse  users    2042 Nov  3 12:36 Makefile.in
+ \& -rw-rw-r--  1 rse  users    3967 Nov  1 19:48 README
+ \& -rw-rw-r--  1 rse  users     340 Nov  3 12:36 README.1st
+ \& -rw-rw-r--  1 rse  users   28719 Oct 31 17:06 config.guess
+ \& -rw-rw-r--  1 rse  users   24274 Aug 18 13:31 config.sub
+ \& -rwxrwxr-x  1 rse  users  155141 Nov  3 12:36 configure
+ \& -rw-rw-r--  1 rse  users  162021 Nov  3 12:36 pth.c
+ \& -rw-rw-r--  1 rse  users   18687 Nov  2 15:19 pth.h.in
+ \& -rw-rw-r--  1 rse  users    5251 Oct 31 12:46 pth_acdef.h.in
+ \& -rw-rw-r--  1 rse  users    2120 Nov  1 11:27 pth_acmac.h.in
+ \& -rw-rw-r--  1 rse  users    2323 Nov  1 11:27 pth_p.h.in
+ \& -rw-rw-r--  1 rse  users     946 Nov  1 11:27 pth_vers.c
+ \& -rw-rw-r--  1 rse  users   26848 Nov  1 11:27 pthread.c
+ \& -rw-rw-r--  1 rse  users   18772 Nov  1 11:27 pthread.h.in
+ \& -rwxrwxr-x  1 rse  users   26188 Nov  3 12:36 shtool
+ .Ve
+ Now when we configure and build the \f(CWfoo\fR package it looks similar to this:
+ .PP
+ .Vb 31
+ \& $ ./configure
+ \& creating cache ./config.cache
+ \& checking for gcc... gcc
+ \& checking whether the C compiler (gcc   ) works... yes
+ \& checking whether the C compiler (gcc   ) is a cross-compiler... no
+ \& checking whether we are using GNU C... yes
+ \& checking whether gcc accepts -g... yes
+ \& checking how to run the C preprocessor... gcc -E
+ \& checking for GNU Pth... version 1.3.0, local under pth
+ \& updating cache ./config.cache
+ \& creating ./config.status
+ \& creating Makefile
+ \& configuring in pth
+ \& running /bin/sh ./configure  --enable-subdir --enable-batch
+ \& --disable-tests --cache-file=.././config.cache --srcdir=.
+ \& loading cache .././config.cache
+ \& checking for gcc... (cached) gcc
+ \& checking whether the C compiler (gcc   ) works... yes
+ \& checking whether the C compiler (gcc   ) is a cross-compiler... no
+ \& [...]
+ \& $ make
+ \& ===> pth (all)
+ \& ./shtool scpp -o pth_p.h -t pth_p.h.in -Dcpp -Cintern -M '==#==' pth.c
+ \& pth_vers.c
+ \& gcc -c -I. -O2 -pipe pth.c
+ \& gcc -c -I. -O2 -pipe pth_vers.c
+ \& ar rc libpth.a pth.o pth_vers.o
+ \& ranlib libpth.a
+ \& <=== pth
+ \& gcc -g -O2 -Ipth -c foo.c
+ \& gcc -Lpth -o foo foo.o -lpth
+ .Ve
+ As you can see, \fBautoconf\fR now automatically configures the local
+ (stripped down) copy of \fBPth\fR in the subdirectory \f(CWpth/\fR and the
+ \f(CWMakefile\fR automatically builds the subdirectory, too.
+ .SH "SYSTEM CALL WRAPPER FACILITY"
+ \fBPth\fR per default uses an explicit API, including the system calls. For
+ instance you've to explicitly use \fIpth_read\fR\|(3) when you need a thread-aware
+ \fIread\fR\|(3) and cannot expect that by just calling \fIread\fR\|(3) only the current thread
+ is blocked. Instead with the standard \fIread\fR\|(3) call the whole process will be
+ blocked. But because for some applications (mainly those consisting of lots of
+ third-party stuff) this can be inconvenient.  Here it's required that a call
+ to \fIread\fR\|(3) `magically\*(R' means \fIpth_read\fR\|(3). The problem here is that such
+ magic \fBPth\fR cannot provide per default because it's not really portable.
+ Nevertheless \fBPth\fR provides a two step approach to solve this problem:
+ .Sh "Soft System Call Mapping"
+ This variant is available on all platforms and can \fIalways\fR be enabled by
+ building \fBPth\fR with \f(CW--enable-syscall-soft\fR. This then triggers some
+ \f(CW#define\fR's in the \f(CWpth.h\fR header which map for instance \fIread\fR\|(3) to
+ \fIpth_read\fR\|(3), etc.  Currently the following functions are mapped: \fIfork\fR\|(2),
+ \fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
+ \fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
+ .PP
+ The drawback of this approach is just that really all source files
+ of the application where these function calls occur have to include
+ \f(CWpth.h\fR, of course. And this also means that existing libraries,
+ including the vendor's \fBstdio\fR, usually will still block the whole
+ process if one of its I/O functions block.
+ .Sh "Hard System Call Mapping"
+ This variant is available only on those platforms where the \fIsyscall\fR\|(2)
+ function exists and there it can be enabled by building \fBPth\fR with
+ \f(CW--enable-syscall-hard\fR. This then builds wrapper functions (for instances
+ \fIread\fR\|(3)) into the \fBPth\fR library which internally call the real \fBPth\fR
+ replacement functions (\fIpth_read\fR\|(3)).  Currently the following functions are
+ mapped: \fIfork\fR\|(2), \fIsleep\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
+ \fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
+ .PP
+ The drawback of this approach is that it depends on \fIsyscall\fR\|(2) interface
+ and prototype conflicts can occur while building the wrapper functions
+ due to different function signatures in the vendor C header files.
+ But the advantage of this mapping variant is that the source files of
+ the application where these function calls occur have not to include
+ \f(CWpth.h\fR and that existing libraries, including the vendor's \fBstdio\fR,
+ magically become thread-aware (and then block only the current thread).
+ .SH "IMPLEMENTATION NOTES"
+ \fBPth\fR is very portable because it has only one part which perhaps has
+ to be ported to new platforms (the machine context initialization). But
+ it is written in a way which works on mostly all Unix platforms which
+ support \fImakecontext\fR\|(2) or at least \fIsigstack\fR\|(2) or \fIsigaltstack\fR\|(2) [see
+ \f(CWpth_mctx.c\fR for details]. Any other \fBPth\fR code is POSIX and ANSI C
+ based only.
+ .PP
+ The context switching is done via either SUSv2 \fImakecontext\fR\|(2) or POSIX
+ make[sig]\fIsetjmp\fR\|(3) and [sig]\fIlongjmp\fR\|(3). Here all CPU registers, the
+ program counter and the stack pointer are switched. Additionally the
+ \fBPth\fR dispatcher switches also the global Unix \f(CWerrno\fR variable [see
+ \f(CWpth_mctx.c\fR for details] and the signal mask (either implicitly via
+ \fIsigsetjmp\fR\|(3) or in an emulated way via explicit \fIsetprocmask\fR\|(2) calls).
+ .PP
+ The \fBPth\fR event manager is mainly \fIselect\fR\|(2) and \fIgettimeofday\fR\|(2) based,
+ i.e., the current time is fetched via \fIgettimeofday\fR\|(2) once per context
+ switch for time calculations and all I/O events are implemented via a
+ single central \fIselect\fR\|(2) call [see \f(CWpth_sched.c\fR for details].
+ .PP
+ The thread control block management is done via virtual priority
+ queues without any additional data structure overhead. For this, the
+ queue linkage attributes are part of the thread control blocks and the
+ queues are actually implemented as rings with a selected element as the
+ entry point [see \f(CWpth_tcb.h\fR and \f(CWpth_pqueue.c\fR for details].
+ .PP
+ Most time critical code sections (especially the dispatcher and event
+ manager) are speeded up by inlined functions (implemented as ANSI C
+ pre-processor macros). Additionally any debugging code is \fIcompletely\fR
+ removed from the source when not built with \f(CW-DPTH_DEBUG\fR (see Autoconf
+ \f(CW--enable-debug\fR option), i.e., not only stub functions remain [see
+ \f(CWpth_debug.h\fR for details].
+ .SH "RESTRICTIONS"
+ \fBPth\fR (intentionally) provides no replacements for non-thread-safe
+ functions (like \fIstrtok\fR\|(3) which uses a static internal buffer) or
+ synchronous system functions (like \fIgethostbyname\fR\|(3) which doesn't
+ provide an asynchronous mode where it doesn't block). When you want to
+ use those functions in your server application together with threads,
+ you've to either link the application against special third-party
+ libraries (or for thread-safe/reentrant functions possibly against an
+ existing \f(CWlibc_r\fR of the platform vendor). For an asynchronous DNS
+ resolver library use the GNU \fBadns\fR package from Ian Jackson ( see
+ http://www.gnu.org/software/adns/adns.html ).
+ .SH "HISTORY"
+ The \fBPth\fR library was designed and implemented between February and
+ July 1999 by \fIRalf S. Engelschall\fR after evaluating numerous (mostly
+ preemptive) thread libraries and after intensive discussions with
+ \fIPeter Simons\fR, \fIMartin Kraemer\fR, \fILars Eilebrecht\fR and \fIRalph
+ Babel\fR related to an experimental (matrix based) non-preemptive \*(C+
+ scheduler class written by \fIPeter Simons\fR.
+ .PP
+ \fBPth\fR was then implemented in order to combine the \fInon-preemptive\fR
+ approach of multithreading (which provides better portability and
+ performance) with an API similar to the popular one found in \fBPthread\fR
+ libraries (which provides easy programming).
+ .PP
+ So the essential idea of the non-preemptive approach was taken over from
+ \fIPeter Simons\fR scheduler. The priority based scheduling algorithm was
+ suggested by \fIMartin Kraemer\fR. Some code inspiration also came from
+ an experimental threading library (\fBrsthreads\fR) written by \fIRobert
+ S. Thau\fR for an ancient internal test version of the Apache webserver.
+ The concept and API of message ports was borrowed from AmigaOS\*(R' \fBExec\fR
+ subsystem. The concept and idea for the flexible event mechanism came
+ from \fIPaul Vixie\fR's \fBeventlib\fR (which can be found as a part of
+ \fBBIND\fR v8).
+ .SH "BUG REPORTS AND SUPPORT"
+ If you think you have found a bug in \fBPth\fR, you should send a report as
+ complete as possible to \fIbug-pth@gnu.org\fR. If you can, please try to
+ fix the problem and include a patch, made with \*(L'\f(CWdiff -u3\fR\*(R', in your
+ report. Always, at least, include a reasonable amount of description in
+ your report to allow the author to deterministically reproduce the bug.
+ .PP
+ For further support you additionally can subscribe to the
+ \fIpth-users@gnu.org\fR mailing list by sending an Email to
+ \fIpth-users-request@gnu.org\fR with `\f(CWsubscribe pth-users\fR\*(R' (or
+ `\f(CWsubscribe pth-users\fR \fIaddress\fR\*(R' if you want to subscribe
+ from a particular Email \fIaddress\fR) in the body. Then you can
+ discuss your issues with other \fBPth\fR users by sending messages to
+ \fIpth-users@gnu.org\fR. Currently (as of January 2000) you can reach about
+ 50 Pth users on this mailing list.
+ .SH "SEE ALSO"
+ .Sh "Related Web Locations"
+ `comp.programming.threads Newsgroup Archive\*(R',
+ http://www.deja.com/topics_if.xp?
+ search=topic&group=comp.programming.threads
+ .PP
+ `comp.programming.threads Frequently Asked Questions (F.A.Q.)\*(R',
+ http://www.lambdacs.com/newsgroup/\s-1FAQ\s0.html
+ .PP
+ `\fIMultithreading \- Definitions and Guidelines\fR\*(R',
+ Numeric Quest Inc 1998;
+ http://www.numeric-quest.com/lang/multi-frame.html
+ .PP
+ `\fIThe Single \s-1UNIX\s0 Specification, Version 2 \- Threads\fR\*(R',
+ The Open Group 1997;
+ http://www.opengroup.org/onlinepubs /007908799/xsh/threads.html
+ .PP
+ \s-1SMI\s0 Thread Resources,
+ Sun Microsystems Inc;
+ http://www.sun.com/workshop/threads/
+ .PP
+ Bibliography on threads and multithreading,
+ Torsten Amundsen;
+ http://liinwww.ira.uka.de/bibliography/Os/threads.html
+ .Sh "Related Books"
+ B. Nichols, D. Buttlar, J.P. Farrel:
+ `\fIPthreads Programming \- A \s-1POSIX\s0 Standard for Better Multiprocessing\fR\*(R',
+ O'Reilly 1996;
+ \s-1ISBN\s0 1-56592-115-1
+ .PP
+ B. Lewis, D. J. Berg:
+ `\fIMultithreaded Programming with Pthreads\fR\*(R',
+ Sun Microsystems Press, Prentice Hall 1998;
+ \s-1ISBN\s0 0-13-680729-1
+ .PP
+ B. Lewis, D. J. Berg:
+ `\fIThreads Primer \- A Guide To Multithreaded Programming\fR\*(R',
+ Prentice Hall 1996;
+ \s-1ISBN\s0 0-13-443698-9
+ .PP
+ S. J. Norton, M. D. Dipasquale:
+ `\fIThread Time \- The Multithreaded Programming Guide\fR\*(R',
+ Prentice Hall 1997;
+ \s-1ISBN\s0 0-13-190067-6
+ .PP
+ D. R. Butenhof:
+ `\fIProgramming with \s-1POSIX\s0 Threads\fR\*(R',
+ Addison Wesley 1997;
+ \s-1ISBN\s0 0-201-63392-2
+ .Sh "Related Manpages"
+ pth-\fIconfig\fR\|(1), \fIpthread\fR\|(3).
+ .PP
+ \fIgetcontext\fR\|(2), \fIsetcontext\fR\|(2), \fImakecontext\fR\|(2), \fIswapcontext\fR\|(2),
+ \fIsigstack\fR\|(2), \fIsigaltstack\fR\|(2), \fIsigaction\fR\|(2), \fIsigemptyset\fR\|(2), \fIsigaddset\fR\|(2),
+ \fIsigprocmask\fR\|(2), \fIsigsuspend\fR\|(2), \fIsigsetjmp\fR\|(3), \fIsiglongjmp\fR\|(3), \fIsetjmp\fR\|(3),
+ \fIlongjmp\fR\|(3), \fIselect\fR\|(2), \fIgettimeofday\fR\|(2).
+ .SH "AUTHOR"
+ .PP
+ .Vb 3
+ \& Ralf S. Engelschall
+ \& rse@engelschall.com
+ \& www.engelschall.com
+ .Ve
+ 
+ .rn }` ''
+ .IX Title "pth 3"
+ .IX Name "B<pth> - GNU Portable Threads"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "VERSION"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Item "\fBGlobal Library Management\fR"
+ 
+ .IX Item "\fBThread Attribute Handling\fR"
+ 
+ .IX Item "\fBThread Control\fR"
+ 
+ .IX Item "\fBUtilities\fR"
+ 
+ .IX Item "\fBCancellation Management\fR"
+ 
+ .IX Item "\fBEvent Handling\fR"
+ 
+ .IX Item "\fBKey-Based Storage\fR"
+ 
+ .IX Item "\fBMessage Port Communication\fR"
+ 
+ .IX Item "\fBThread Cleanups\fR"
+ 
+ .IX Item "\fBProcess Forking\fR"
+ 
+ .IX Item "\fBSynchronization\fR"
+ 
+ .IX Item "\fBGeneralized \s-1POSIX\s0 Replacement \s-1API\s0\fR"
+ 
+ .IX Item "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Subsection "Threading Background"
+ 
+ .IX Subsection "The World of Threading"
+ 
+ .IX Item "\fBo\fR \fBprocess\fR vs. \fBthread\fR"
+ 
+ .IX Item "\fBo\fR \fBkernel-space\fR vs. \fBuser-space\fR threading"
+ 
+ .IX Item "\fBo\fR \fBpreemtive\fR vs. \fBnon-preemtive\fR thread scheduling"
+ 
+ .IX Item "\fBo\fR \fBconcurrency\fR vs. \fBparallelism\fR"
+ 
+ .IX Item "\fBo\fR \fBresponsiveness\fR"
+ 
+ .IX Item "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasynchronous-safe\fR functions"
+ 
+ .IX Subsection "User-Space Threads"
+ 
+ .IX Item "\fB1.\fR"
+ 
+ .IX Item "\fB2.\fR"
+ 
+ .IX Subsection "The Compromise of Pth"
+ 
+ .IX Item "\fBo\fR"
+ 
+ .IX Item "\fBo\fR"
+ 
+ .IX Item "\fBo\fR"
+ 
+ .IX Item "\fBo\fR"
+ 
+ .IX Subsection "The life cycle of a thread"
+ 
+ .IX Header "APPLICATION PROGRAMMING INTERFACE (API)"
+ 
+ .IX Subsection "Global Library Management"
+ 
+ .IX Item "int \fBpth_init\fR(void);"
+ 
+ .IX Item "int \fBpth_kill\fR(void);"
+ 
+ .IX Item "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);"
+ 
+ .IX Item "\f(CWPTH_CTRL_GETTHREADS\fR"
+ 
+ .IX Item "\f(CWPTH_CTRL_GETAVLOAD\fR"
+ 
+ .IX Item "\f(CWPTH_CTRL_GETPRIO\fR"
+ 
+ .IX Item "\f(CWPTH_CTRL_GETNAME\fR"
+ 
+ .IX Item "\f(CWPTH_CTRL_DUMPSTATE\fR"
+ 
+ .IX Item "long \fBpth_version\fR(void);"
+ 
+ .IX Subsection "Thread Attribute Handling"
+ 
+ .IX Item "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]"
+ 
+ .IX Item "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]"
+ 
+ .IX Item "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "pth_attr_t \fBpth_attr_new\fR(void);"
+ 
+ .IX Item "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);"
+ 
+ .IX Item "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);"
+ 
+ .IX Item "int \fBpth_attr_get\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);"
+ 
+ .IX Item "int \fBpth_attr_destroy\fR(pth_attr_t \fIattr\fR);"
+ 
+ .IX Subsection "Thread Control"
+ 
+ .IX Item "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);"
+ 
+ .IX Item "int \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);"
+ 
+ .IX Item "pth_t \fBpth_self\fR(void);"
+ 
+ .IX Item "int \fBpth_suspend\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "int \fBpth_resume\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "int \fBpth_raise\fR(pth_t \fItid\fR, int \fIsig\fR)"
+ 
+ .IX Item "int \fBpth_yield\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);"
+ 
+ .IX Item "int \fBpth_wait\fR(pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_cancel\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "int \fBpth_abort\fR(pth_t \fItid\fR);"
+ 
+ .IX Item "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);"
+ 
+ .IX Item "void \fBpth_exit\fR(void *\fIvalue\fR);"
+ 
+ .IX Subsection "Utilities"
+ 
+ .IX Item "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);"
+ 
+ .IX Item "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);"
+ 
+ .IX Item "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);"
+ 
+ .IX Item "Sfdisc_t *\fBpth_sfiodisc\fR(void);"
+ 
+ .IX Subsection "Cancellation Management"
+ 
+ .IX Item "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);"
+ 
+ .IX Item "void \fBpth_cancel_point\fR(void);"
+ 
+ .IX Subsection "Event Handling"
+ 
+ .IX Item "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);"
+ 
+ .IX Item "\f(CWPTH_EVENT_FD\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_SELECT\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_SIGS\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_TIME\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_MSG\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_TID\fR"
+ 
+ .IX Item "\f(CWPTH_EVENT_FUNC\fR"
+ 
+ .IX Item "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);"
+ 
+ .IX Item "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);"
+ 
+ .IX Item "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);"
+ 
+ .IX Item "pth_event_t \fBpth_event_walk\fR(pth_event_t \fIev\fR, int \fIdirection\fR);"
+ 
+ .IX Item "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);"
+ 
+ .IX Subsection "Key-Based Storage"
+ 
+ .IX Item "int \fBpth_key_create\fR(pth_key_t *\fIkey\fR, void (*\fIfunc\fR)(void *));"
+ 
+ .IX Item "int \fBpth_key_delete\fR(pth_key_t \fIkey\fR);"
+ 
+ .IX Item "int \fBpth_key_setdata\fR(pth_key_t \fIkey\fR, const void *\fIvalue\fR);"
+ 
+ .IX Item "void *\fBpth_key_getdata\fR(pth_key_t \fIkey\fR);"
+ 
+ .IX Subsection "Message Port Communication"
+ 
+ .IX Item "pth_msgport_t \fBpth_msgport_create\fR(const char *\fIname\fR);"
+ 
+ .IX Item "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);"
+ 
+ .IX Item "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);"
+ 
+ .IX Item "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);"
+ 
+ .IX Item "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);"
+ 
+ .IX Item "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);"
+ 
+ .IX Item "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);"
+ 
+ .IX Subsection "Thread Cleanups"
+ 
+ .IX Item "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);"
+ 
+ .IX Item "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);"
+ 
+ .IX Subsection "Process Forking"
+ 
+ .IX Item "int \fBpth_atfork_push\fR(void (*\fIprepare\fR)(void *), void (*)(void *\fIparent\fR), void (*)(void *\fIchild\fR), void *\fIarg\fR);"
+ 
+ .IX Item "int \fBpth_atfork_pop\fR(void);"
+ 
+ .IX Item "pid_t \fBpth_fork\fR(void);"
+ 
+ .IX Subsection "Synchronization"
+ 
+ .IX Item "int \fBpth_mutex_init\fR(pth_mutex_t *\fImutex\fR);"
+ 
+ .IX Item "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fItry\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_mutex_release\fR(pth_mutex_t *\fImutex\fR);"
+ 
+ .IX Item "int \fBpth_rwlock_init\fR(pth_rwlock_t *\fIrwlock\fR);"
+ 
+ .IX Item "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, int \fItry\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_rwlock_release\fR(pth_rwlock_t *\fIrwlock\fR);"
+ 
+ .IX Item "int \fBpth_cond_init\fR(pth_cond_t *\fIcond\fR);"
+ 
+ .IX Item "int \fBpth_cond_await\fR(pth_cond_t *\fIcond\fR, pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_cond_notify\fR(pth_cond_t *\fIcond\fR, int \fIbroadcast\fR);"
+ 
+ .IX Item "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I<threshold);"
+ 
+ .IX Item "int \fBpth_barrier_reach\fR(pth_barrier_t *\fIbarrier\fR);"
+ 
+ .IX Subsection "Generalized \s-1POSIX\s0 Replacement \s-1API\s0"
+ 
+ .IX Item "int \fBpth_sigwait_ev\fR(const sigset_t *\fIset\fR, int *\fIsig\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_select_ev\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "int \fBpth_poll_ev\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "ssize_t \fBpth_read_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "ssize_t \fBpth_readv_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Item "ssize_t \fBpth_writev_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);"
+ 
+ .IX Subsection "Standard \s-1POSIX\s0 Replacement \s-1API\s0"
+ 
+ .IX Item "int \fBpth_usleep\fR(unsigned int \fIusec\fR);"
+ 
+ .IX Item "unsigned int \fBpth_sleep\fR(unsigned int \fIsec\fR);"
+ 
+ .IX Item "pid_t \fBpth_waitpid\fR(pid_t \fIpid\fR, int *\fIstatus\fR, int \fIoptions\fR);"
+ 
+ .IX Item "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)"
+ 
+ .IX Item "int \fBpth_sigwait\fR(const sigset_t *\fIset\fR, int *\fIsig\fR);"
+ 
+ .IX Item "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR);"
+ 
+ .IX Item "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR);"
+ 
+ .IX Item "int \fBpth_select\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR);"
+ 
+ .IX Item "int \fBpth_poll\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR);"
+ 
+ .IX Item "ssize_t \fBpth_read\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR);"
+ 
+ .IX Item "ssize_t \fBpth_readv\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);"
+ 
+ .IX Item "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);"
+ 
+ .IX Item "ssize_t \fBpth_writev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);"
+ 
+ .IX Item "ssize_t \fBpth_pread\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);"
+ 
+ .IX Item "ssize_t \fBpth_pwrite\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);"
+ 
+ .IX Header "EXAMPLE"
+ 
+ .IX Header "BUILD ENVIRONMENTS"
+ 
+ .IX Subsection "Manual Build Environment (Novice)"
+ 
+ .IX Subsection "Autoconf Build Environment (Advanced)"
+ 
+ .IX Subsection "Autoconf Build Environment with Local Copy of Pth (Expert)"
+ 
+ .IX Header "SYSTEM CALL WRAPPER FACILITY"
+ 
+ .IX Subsection "Soft System Call Mapping"
+ 
+ .IX Subsection "Hard System Call Mapping"
+ 
+ .IX Header "IMPLEMENTATION NOTES"
+ 
+ .IX Header "RESTRICTIONS"
+ 
+ .IX Header "HISTORY"
+ 
+ .IX Header "BUG REPORTS AND SUPPORT"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Subsection "Related Web Locations"
+ 
+ .IX Subsection "Related Books"
+ 
+ .IX Subsection "Related Manpages"
+ 
+ .IX Header "AUTHOR"
+

ossp-pkg/pth/pth_p.h.in -> 1.24.2.1 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,96 ----
+ /*
+ **  GNU Pth - The GNU Portable Threads
+ **  Copyright (c) 1999-2000 Ralf S. Engelschall <rse@engelschall.com>
+ **
+ **  This file is part of GNU Pth, a non-preemptive thread scheduling
+ **  library which can be found at http://www.gnu.org/software/pth/.
+ **
+ **  This library is free software; you can redistribute it and/or
+ **  modify it under the terms of the GNU Lesser General Public
+ **  License as published by the Free Software Foundation; either
+ **  version 2.1 of the License, or (at your option) any later version.
+ **
+ **  This library is distributed in the hope that it will be useful,
+ **  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ **  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ **  Lesser General Public License for more details.
+ **
+ **  You should have received a copy of the GNU Lesser General Public
+ **  License along with this library; if not, write to the Free Software
+ **  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+ **  USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
+ **
+ **  pth_p.h: Pth private API definitions
+ */
+ 
+ #ifndef _PTH_P_H_
+ #define _PTH_P_H_
+ 
+ /* mandatory system headers */
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <stdarg.h>
+ #include <string.h>
+ #include <setjmp.h>
+ #include <signal.h>
+ #include <unistd.h>
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/wait.h>
+ #include <sys/socket.h>
+ 
+ /* library version */
+ #define _PTH_VERS_C_AS_HEADER_
+ #include "pth_vers.c"
+ #undef  _PTH_VERS_C_AS_HEADER_
+ 
+ /* public API headers */
+ #define _PTH_PRIVATE
+ #include "pth.h"
+ #undef _PTH_PRIVATE
+ 
+ /* autoconf defines and macros */
+ #include "pth_acdef.h"
+ #include "pth_acmac.h"
+ 
+ /* optional system headers */
+ #ifdef HAVE_SYS_RESOURCE_H
+ #include <sys/resource.h>
+ #endif
+ #ifdef HAVE_NET_ERRNO_H
+ #include <net/errno.h>
+ #endif
+ 
+ /* dmalloc support */
+ #ifdef PTH_DMALLOC
+ #include <dmalloc.h>
+ #endif
+ 
+ /* non-blocking flags */
+ #ifdef  O_NONBLOCK
+ #define O_NONBLOCKING O_NONBLOCK
+ #else
+ #ifdef  O_NDELAY
+ #define O_NONBLOCKING O_NDELAY
+ #else
+ #ifdef  FNDELAY
+ #define O_NONBLOCKING FNDELAY
+ #else
+ #error "No O_NONBLOCK, O_NDELAY or FNDELAY flag available!"
+ #endif
+ #endif
+ #endif
+ 
+ /* compiler happyness: avoid ``empty compilation unit'' problem */
+ #define COMPILER_HAPPYNESS(name) \
+     int __##name##_unit = 0;
+ 
+ /* generated contents */
+ BEGIN_DECLARATION
+ ==#==
+ END_DECLARATION
+ 
+ #endif /* _PTH_P_H_ */
+

ossp-pkg/pth/pthread-config.1 -> 1.81.2.5 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,315 ----
+ .rn '' }`
+ ''' $RCSfile$$Revision$$Date$
+ '''
+ ''' $Log$
+ '''
+ .de Sh
+ .br
+ .if t .Sp
+ .ne 5
+ .PP
+ \fB\\$1\fR
+ .PP
+ ..
+ .de Sp
+ .if t .sp .5v
+ .if n .sp
+ ..
+ .de Ip
+ .br
+ .ie \\n(.$>=3 .ne \\$3
+ .el .ne 3
+ .IP "\\$1" \\$2
+ ..
+ .de Vb
+ .ft CW
+ .nf
+ .ne \\$1
+ ..
+ .de Ve
+ .ft R
+ 
+ .fi
+ ..
+ '''
+ '''
+ '''     Set up \*(-- to give an unbreakable dash;
+ '''     string Tr holds user defined translation string.
+ '''     Bell System Logo is used as a dummy character.
+ '''
+ .tr \(*W-|\(bv\*(Tr
+ .ie n \{\
+ .ds -- \(*W-
+ .ds PI pi
+ .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+ .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+ .ds L" ""
+ .ds R" ""
+ '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+ '''   \*(L" and \*(R", except that they are used on ".xx" lines,
+ '''   such as .IP and .SH, which do another additional levels of
+ '''   double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
+ .ds L' '
+ .ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
+ 'br\}
+ .el\{\
+ .ds -- \(em\|
+ .tr \*(Tr
+ .ds L" ``
+ .ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
+ .ds L' `
+ .ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
+ .ds PI \(*p
+ 'br\}
+ .\"    If the F register is turned on, we'll generate
+ .\"    index entries out stderr for the following things:
+ .\"            TH      Title 
+ .\"            SH      Header
+ .\"            Sh      Subsection 
+ .\"            Ip      Item
+ .\"            X<>     Xref  (embedded
+ .\"    Of course, you have to process the output yourself
+ .\"    in some meaninful fashion.
+ .if \nF \{
+ .de IX
+ .tm Index:\\$1\t\\n%\t"\\$2"
+ ..
+ .nr % 0
+ .rr F
+ .\}
+ .TH PTHREAD-CONFIG 1 "01-Jul-2000" "GNU Pth 1.3.5" "POSIX Threading API of GNU Pth"
+ .UC
+ .if n .hy 0
+ .if n .na
+ .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+ .de CQ          \" put $1 in typewriter font
+ .ft CW
+ 'if n "\c
+ 'if t \\&\\$1\c
+ 'if n \\&\\$1\c
+ 'if n \&"
+ \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+ '.ft R
+ ..
+ .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+ .      \" AM - accent mark definitions
+ .bd B 3
+ .      \" fudge factors for nroff and troff
+ .if n \{\
+ .      ds #H 0
+ .      ds #V .8m
+ .      ds #F .3m
+ .      ds #[ \f1
+ .      ds #] \fP
+ .\}
+ .if t \{\
+ .      ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+ .      ds #V .6m
+ .      ds #F 0
+ .      ds #[ \&
+ .      ds #] \&
+ .\}
+ .      \" simple accents for nroff and troff
+ .if n \{\
+ .      ds ' \&
+ .      ds ` \&
+ .      ds ^ \&
+ .      ds , \&
+ .      ds ~ ~
+ .      ds ? ?
+ .      ds ! !
+ .      ds /
+ .      ds q
+ .\}
+ .if t \{\
+ .      ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+ .      ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+ .      ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+ .      ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+ .      ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+ .      ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+ .      ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+ .      ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+ .      ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+ .\}
+ .      \" troff and (daisy-wheel) nroff accents
+ .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+ .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+ .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+ .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+ .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+ .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+ .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+ .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+ .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+ .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+ .ds ae a\h'-(\w'a'u*4/10)'e
+ .ds Ae A\h'-(\w'A'u*4/10)'E
+ .ds oe o\h'-(\w'o'u*4/10)'e
+ .ds Oe O\h'-(\w'O'u*4/10)'E
+ .      \" corrections for vroff
+ .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+ .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+ .      \" for low resolution devices (crt and lpr)
+ .if \n(.H>23 .if \n(.V>19 \
+ \{\
+ .      ds : e
+ .      ds 8 ss
+ .      ds v \h'-1'\o'\(aa\(ga'
+ .      ds _ \h'-1'^
+ .      ds . \h'-1'.
+ .      ds 3 3
+ .      ds o a
+ .      ds d- d\h'-1'\(ga
+ .      ds D- D\h'-1'\(hy
+ .      ds th \o'bp'
+ .      ds Th \o'LP'
+ .      ds ae ae
+ .      ds Ae AE
+ .      ds oe oe
+ .      ds Oe OE
+ .\}
+ .rm #[ #] #H #V #F C
+ .SH "NAME"
+ \fBpthread-config\fR \- Pth pthread library build utility
+ .SH "VERSION"
+ GNU Pth 1.3.5 (01-Jul-2000)
+ .SH "SYNOPSIS"
+ \fBpthread-config\fR
+ [\fB--help\fR]
+ [\fB--version\fR]
+ [\fB--all\fR]
+ [\fB--prefix\fR]
+ [\fB--exec-prefix\fR]
+ [\fB--bindir\fR]
+ [\fB--libdir\fR]
+ [\fB--includedir\fR]
+ [\fB--mandir\fR]
+ [\fB--cflags\fR]
+ [\fB--ldflags\fR]
+ [\fB--libs\fR]
+ .SH "DESCRIPTION"
+ The \fBpthread-config\fR program is a little helper utility for easy configuring
+ and building applications based on the pthread emulation API of the GNU
+ Portable Threads (pth) library.  It can be used to query the C compiler and
+ linker flags which are required to correctly compile and link the application
+ against the \fIpth\fR\|(3) library.
+ .SH "OPTIONS"
+ \fBpthread-config\fR accepts the following options:
+ .Ip "\fB--help\fR" 4
+ Prints the short usage information.
+ .Ip "\fB--version\fR" 4
+ Prints the version number and date of the installed \fIpth\fR\|(3) library.
+ .Ip "\fB--all\fR" 4
+ Forces the output of all flags, that is, including extra flags which are not
+ \fBPth\fR specific.
+ .Ip "\fB--prefix\fR" 4
+ Prints the installation prefix of architecture independent files
+ .Ip "\fB--exec-prefix\fR" 4
+ Prints the installation prefix of architecture dependent files.
+ .Ip "\fB--bindir\fR" 4
+ Prints the installation directory of binaries.
+ .Ip "\fB--libdir\fR" 4
+ Prints the installation directory of libraries.
+ .Ip "\fB--includedir\fR" 4
+ Prints the installation directory of include headers.
+ .Ip "\fB--mandir\fR" 4
+ Prints the installation directory of manual pages.
+ .Ip "\fB--cflags\fR" 4
+ Prints the C compiler flags which are needed to compile the \fIpth\fR\|(3)\-based
+ application. The output is usually added to the \f(CWCFLAGS\fR variable of the
+ applications \f(CWMakefile\fR.
+ .Ip "\fB--ldflags\fR" 4
+ Prints the linker flags (\f(CW-L\fR) which are needed to link the application with
+ the \fIpth\fR\|(3) library. The output is usually added to the \f(CWLDFLAGS\fR variable of
+ the applications \f(CWMakefile\fR.
+ .Ip "\fB--libs\fR" 4
+ Prints the library flags (\f(CW-l\fR) which are needed to link the application with
+ the \fIpth\fR\|(3) library. The output is usually added to the \f(CWLIBS\fR variable of the
+ applications \f(CWMakefile\fR.
+ .SH "EXAMPLE"
+ .PP
+ .Vb 4
+ \& CC      = cc
+ \& CFLAGS  = -O `pthread-config --cflags`
+ \& LDFLAGS = `pthread-config --ldflags`
+ \& LIBS    = -lm `pthread-config --libs`
+ .Ve
+ .Vb 5
+ \& all: foo
+ \& foo: foo.o
+ \&     $(CC) $(LDFLAGS) -o foo foo.o $(LIBS)
+ \& foo.o: foo.c
+ \&     $(CC) $(CFLAGS) -c foo.c
+ .Ve
+ .SH "SEE ALSO"
+ \fIpthread\fR\|(3), \fIcc\fR\|(1).
+ .SH "AUTHOR"
+ .PP
+ .Vb 3
+ \& Ralf S. Engelschall
+ \& rse@engelschall.com
+ \& www.engelschall.com
+ .Ve
+ 
+ .rn }` ''
+ .IX Title "PTHREAD-CONFIG 1"
+ .IX Name "B<pthread-config> - Pth pthread library build utility"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "VERSION"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "OPTIONS"
+ 
+ .IX Item "\fB--help\fR"
+ 
+ .IX Item "\fB--version\fR"
+ 
+ .IX Item "\fB--all\fR"
+ 
+ .IX Item "\fB--prefix\fR"
+ 
+ .IX Item "\fB--exec-prefix\fR"
+ 
+ .IX Item "\fB--bindir\fR"
+ 
+ .IX Item "\fB--libdir\fR"
+ 
+ .IX Item "\fB--includedir\fR"
+ 
+ .IX Item "\fB--mandir\fR"
+ 
+ .IX Item "\fB--cflags\fR"
+ 
+ .IX Item "\fB--ldflags\fR"
+ 
+ .IX Item "\fB--libs\fR"
+ 
+ .IX Header "EXAMPLE"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "AUTHOR"
+

ossp-pkg/pth/pthread.3 -> 1.85.2.5 

*** /dev/null    Wed May  1 15:55:00 2024
--- -    Wed May  1 15:57:32 2024
***************
*** 0 ****
--- 1,9502 ----
+ .rn '' }`
+ ''' $RCSfile$$Revision$$Date$
+ '''
+ ''' $Log$
+ '''
+ .de Sh
+ .br
+ .if t .Sp
+ .ne 5
+ .PP
+ \fB\\$1\fR
+ .PP
+ ..
+ .de Sp
+ .if t .sp .5v
+ .if n .sp
+ ..
+ .de Ip
+ .br
+ .ie \\n(.$>=3 .ne \\$3
+ .el .ne 3
+ .IP "\\$1" \\$2
+ ..
+ .de Vb
+ .ft CW
+ .nf
+ .ne \\$1
+ ..
+ .de Ve
+ .ft R
+ 
+ .fi
+ ..
+ '''
+ '''
+ '''     Set up \*(-- to give an unbreakable dash;
+ '''     string Tr holds user defined translation string.
+ '''     Bell System Logo is used as a dummy character.
+ '''
+ .tr \(*W-|\(bv\*(Tr
+ .ie n \{\
+ .ds -- \(*W-
+ .ds PI pi
+ .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+ .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+ .ds L" ""
+ .ds R" ""
+ '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+ '''   \*(L" and \*(R", except that they are used on ".xx" lines,
+ '''   such as .IP and .SH, which do another additional levels of
+ '''   double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
+ .ds L' '
+ .ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
+ 'br\}
+ .el\{\
+ .ds -- \(em\|
+ .tr \*(Tr
+ .ds L" ``
+ .ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
+ .ds L' `
+ .ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
+ .ds PI \(*p
+ 'br\}
+ .\"    If the F register is turned on, we'll generate
+ .\"    index entries out stderr for the following things:
+ .\"            TH      Title 
+ .\"            SH      Header
+ .\"            Sh      Subsection 
+ .\"            Ip      Item
+ .\"            X<>     Xref  (embedded
+ .\"    Of course, you have to process the output yourself
+ .\"    in some meaninful fashion.
+ .if \nF \{
+ .de IX
+ .tm Index:\\$1\t\\n%\t"\\$2"
+ ..
+ .nr % 0
+ .rr F
+ .\}
+ .TH pthread 3 "01-Jul-2000" "GNU Pth 1.3.5" "POSIX Threading API of GNU Pth"
+ .UC
+ .if n .hy 0
+ .if n .na
+ .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+ .de CQ          \" put $1 in typewriter font
+ .ft CW
+ 'if n "\c
+ 'if t \\&\\$1\c
+ 'if n \\&\\$1\c
+ 'if n \&"
+ \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+ '.ft R
+ ..
+ .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+ .      \" AM - accent mark definitions
+ .bd B 3
+ .      \" fudge factors for nroff and troff
+ .if n \{\
+ .      ds #H 0
+ .      ds #V .8m
+ .      ds #F .3m
+ .      ds #[ \f1
+ .      ds #] \fP
+ .\}
+ .if t \{\
+ .      ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+ .      ds #V .6m
+ .      ds #F 0
+ .      ds #[ \&
+ .      ds #] \&
+ .\}
+ .      \" simple accents for nroff and troff
+ .if n \{\
+ .      ds ' \&
+ .      ds ` \&
+ .      ds ^ \&
+ .      ds , \&
+ .      ds ~ ~
+ .      ds ? ?
+ .      ds ! !
+ .      ds /
+ .      ds q
+ .\}
+ .if t \{\
+ .      ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+ .      ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+ .      ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+ .      ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+ .      ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+ .      ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+ .      ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+ .      ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+ .      ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+ .\}
+ .      \" troff and (daisy-wheel) nroff accents
+ .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+ .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+ .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+ .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+ .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+ .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+ .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+ .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+ .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+ .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+ .ds ae a\h'-(\w'a'u*4/10)'e
+ .ds Ae A\h'-(\w'A'u*4/10)'E
+ .ds oe o\h'-(\w'o'u*4/10)'e
+ .ds Oe O\h'-(\w'O'u*4/10)'E
+ .      \" corrections for vroff
+ .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+ .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+ .      \" for low resolution devices (crt and lpr)
+ .if \n(.H>23 .if \n(.V>19 \
+ \{\
+ .      ds : e
+ .      ds 8 ss
+ .      ds v \h'-1'\o'\(aa\(ga'
+ .      ds _ \h'-1'^
+ .      ds . \h'-1'.
+ .      ds 3 3
+ .      ds o a
+ .      ds d- d\h'-1'\(ga
+ .      ds D- D\h'-1'\(hy
+ .      ds th \o'bp'
+ .      ds Th \o'LP'
+ .      ds ae ae
+ .      ds Ae AE
+ .      ds oe oe
+ .      ds Oe OE
+ .\}
+ .rm #[ #] #H #V #F C
+ .SH "NAME"
+ \fBpthread\fR \- POSIX.1c Threading API of GNU Pth
+ .SH "VERSION"
+ GNU Pth 1.3.5 (01-Jul-2000)
+ .SH "SYNOPSIS"
+ \fBApplication Makefiles:\fR
+ .PP
+ .Vb 4
+ \& #   manually
+ \& CFLAGS=-I/path/to/pth/include
+ \& LDFLAGS=-L/path/to/pth/lib
+ \& LIBS=-lpthread
+ .Ve
+ .Vb 4
+ \& #   automatically
+ \& CFLAGS=`pthread-config --cflags`
+ \& LDFLAGS=`pthread-config --ldflags`
+ \& LIBS=`pthread-config --libs`
+ .Ve
+ \fBApplication source files:\fR
+ .PP
+ .Vb 1
+ \& #include <pthread.h>
+ .Ve
+ .SH "DESCRIPTION"
+ .Sh "Overview"
+ This is the \s-1IEEE\s0 Std. 1003.1c ("\s-1POSIX\s0.1c") conforming threading \s-1API\s0 of
+ \s-1GNU\s0 Portable Threads (\fBPth\fR). This \s-1API\s0 is commonly known as ``\fI\s-1POSIX\s0
+ threads\fR'\*(R' or in short ``\fIPthreads\fR'\*(R'. It is provided by \fBPth\fR with
+ the intention of backward compatibility to existing multithreaded
+ applications. It is implemented by mapping the various Pthread \s-1API\s0
+ functions to the corresponding native \fBPth\fR \s-1API\s0 functions.
+ .Sh "Supported Features"
+ The following defined feature macros in \f(CWpthread.h\fR indicate supported
+ features:
+ .PP
+ .Vb 3
+ \& #define _POSIX_THREADS
+ \& #define _POSIX_THREAD_ATTR_STACKADDR
+ \& #define _POSIX_THREAD_ATTR_STACKSIZE
+ .Ve
+ The following undefined feature macros in \f(CWpthread.h\fR indicate (still)
+ unsupported features:
+ .PP
+ .Vb 5
+ \& #undef  _POSIX_THREAD_PRIORITY_SCHEDULING
+ \& #undef  _POSIX_THREAD_PRIO_INHERIT
+ \& #undef  _POSIX_THREAD_PRIO_PROTECT
+ \& #undef  _POSIX_THREAD_PROCESS_SHARED
+ \& #undef  _POSIX_THREAD_SAFE_FUNCTIONS
+ .Ve
+ .Sh "Notes"
+ A few notes which you should keep in mind when working with the \fBPth\fR Pthread
+ \s-1API\s0.
+ .Ip "\fBNon-Preemptive Scheduling\fR" 4
+ First you have to always remember when working with this Pthread library that
+ it uses non-preemptive scheduling, because it is directly based on \fBPth\fR
+ (\fBPth\fR for portability reasons is a pure non-preemptive thread scheduling
+ system). So there is no implicit yielding of execution control unless you can
+ \f(CWpthread_*\fR functions which could block and you cannot expect granular
+ concurrency in your application, of course.  Nevertheless the responsiveness
+ and concurrency of an event driven application is increased greatly because of
+ overlapping I/O.
+ .Ip "\fBConflicts with Vendor Implementation\fR" 4
+ There can be a conflict between the \fBPth\fR \f(CWpthread.h\fR header and a possibly
+ existing vendor \f(CW/usr/include/pthread.h\fR header which was implicitly included
+ by some standard vendor headers (like \f(CW/usr/include/unistd.h\fR). When this
+ occurs try to ``\f(CW#define\fR'\*(R' header-dependent values which prevent the
+ inclusion of the vendor header.
+ .Sh "Further Reading"
+ There is ``\fIThe Single \s-1UNIX\s0 Specification, Version
+ 2 \- Threads\fR'\*(R', from \fIThe Open Group\fR of 1997 under
+ http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html. This is
+ a very complete publically available description of the Pthread \s-1API\s0. For
+ convinience reasons, a translated copy of these freely available \s-1HTML\s0
+ pages are appended to this manpage below. These are \fICopyright (C) 1997
+ The Open Group\fR.
+ .PP
+ Second, you can also buy the official standard from \s-1IEEE\s0. It is the \s-1IEEE\s0
+ \s-1POSIX\s0 1003.1c-1995 standard (also known as \s-1ISO/IEC\s0 9945-1:1996), which
+ is available as part of the \s-1ANSI/IEEE\s0 1003.1, 1996 edition, standard.
+ .PP
+ Finally you can look at the files \f(CWpthread.c\fR and \f(CWpthread.h\fR in the \fBPth\fR
+ source tree for details of the implementation, of course.
+ .SH "SEE ALSO"
+ pthread-\fIconfig\fR\|(1), \fIpth\fR\|(3).
+ .SH "AUTHOR"
+ .PP
+ .Vb 3
+ \& Ralf S. Engelschall
+ \& rse@engelschall.com
+ \& www.engelschall.com
+ .Ve
+ ##
+ ##  The Single UNIX Specification, Version 2 \- Threads
+ ##  http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html
+ ##  Copyright (C) 1997 The Open Group, All Rights Reserved.
+ ##
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread.h\fR \- threads
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .SH "DESCRIPTION"
+ The
+ \fI<pthread.h\fR>
+ header defines the following symbols:
+ .PP
+ .Vb 24
+ \& PTHREAD_CANCEL_ASYNCHRONOUS
+ \& PTHREAD_CANCEL_ENABLE
+ \& PTHREAD_CANCEL_DEFERRED
+ \& PTHREAD_CANCEL_DISABLE
+ \& PTHREAD_CANCELED
+ \& PTHREAD_COND_INITIALIZER
+ \& PTHREAD_CREATE_DETACHED
+ \& PTHREAD_CREATE_JOINABLE
+ \& PTHREAD_EXPLICIT_SCHED
+ \& PTHREAD_INHERIT_SCHED
+ \& PTHREAD_MUTEX_DEFAULT
+ \& PTHREAD_MUTEX_ERRORCHECK
+ \& PTHREAD_MUTEX_NORMAL
+ \& PTHREAD_MUTEX_INITIALIZER
+ \& PTHREAD_MUTEX_RECURSIVE
+ \& PTHREAD_ONCE_INIT
+ \& PTHREAD_PRIO_INHERIT
+ \& PTHREAD_PRIO_NONE
+ \& PTHREAD_PRIO_PROTECT
+ \& PTHREAD_PROCESS_SHARED
+ \& PTHREAD_PROCESS_PRIVATE
+ \& PTHREAD_RWLOCK_INITIALIZER
+ \& PTHREAD_SCOPE_PROCESS
+ \& PTHREAD_SCOPE_SYSTEM
+ .Ve
+ The \fBpthread_attr_t\fR, \fBpthread_cond_t\fR, \fBpthread_condattr_t\fR,
+ \fBpthread_key_t\fR, \fBpthread_mutex_t\fR, \fBpthread_mutexattr_t\fR,
+ \fBpthread_once_t\fR, \fBpthread_rwlock_t\fR, \fBpthread_rwlockattr_t\fR and
+ \fBpthread_t\fR types are defined as described in \fI<sys/types.h\fR>.
+ .PP
+ The following are declared as functions and may also be declared as
+ macros. Function prototypes must be provided for use with an ISO C
+ compiler.
+ .PP
+ .Vb 77
+ \& int   pthread_attr_destroy(pthread_attr_t *);
+ \& int   pthread_attr_getdetachstate(const pthread_attr_t *, int *);
+ \& int   pthread_attr_getguardsize(const pthread_attr_t *, size_t *);
+ \& int   pthread_attr_getinheritsched(const pthread_attr_t *, int *);
+ \& int   pthread_attr_getschedparam(const pthread_attr_t *, struct sched_param *);
+ \& int   pthread_attr_getschedpolicy(const pthread_attr_t *, int *);
+ \& int   pthread_attr_getscope(const pthread_attr_t *, int *);
+ \& int   pthread_attr_getstackaddr(const pthread_attr_t *, void **);
+ \& int   pthread_attr_getstacksize(const pthread_attr_t *, size_t *);
+ \& int   pthread_attr_init(pthread_attr_t *);
+ \& int   pthread_attr_setdetachstate(pthread_attr_t *, int);
+ \& int   pthread_attr_setguardsize(pthread_attr_t *, size_t);
+ \& int   pthread_attr_setinheritsched(pthread_attr_t *, int);
+ \& int   pthread_attr_setschedparam(pthread_attr_t *, const struct sched_param *);
+ \& int   pthread_attr_setschedpolicy(pthread_attr_t *, int);
+ \& int   pthread_attr_setscope(pthread_attr_t *, int);
+ \& int   pthread_attr_setstackaddr(pthread_attr_t *, void *);
+ \& int   pthread_attr_setstacksize(pthread_attr_t *, size_t);
+ \& int   pthread_cancel(pthread_t);
+ \& void  pthread_cleanup_push(void*), void *);
+ \& void  pthread_cleanup_pop(int);
+ \& int   pthread_cond_broadcast(pthread_cond_t *);
+ \& int   pthread_cond_destroy(pthread_cond_t *);
+ \& int   pthread_cond_init(pthread_cond_t *, const pthread_condattr_t *);
+ \& int   pthread_cond_signal(pthread_cond_t *);
+ \& int   pthread_cond_timedwait(pthread_cond_t *, pthread_mutex_t *, const struct timespec *);
+ \& int   pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *);
+ \& int   pthread_condattr_destroy(pthread_condattr_t *);
+ \& int   pthread_condattr_getpshared(const pthread_condattr_t *, int *);
+ \& int   pthread_condattr_init(pthread_condattr_t *);
+ \& int   pthread_condattr_setpshared(pthread_condattr_t *, int);
+ \& int   pthread_create(pthread_t *, const pthread_attr_t *, void *(*)(void *), void *);
+ \& int   pthread_detach(pthread_t);
+ \& int   pthread_equal(pthread_t, pthread_t);
+ \& void  pthread_exit(void *);
+ \& int   pthread_getconcurrency(void);
+ \& int   pthread_getschedparam(pthread_t, int *, struct sched_param *);
+ \& void *pthread_getspecific(pthread_key_t);
+ \& int   pthread_join(pthread_t, void **);
+ \& int   pthread_key_create(pthread_key_t *, void (*)(void *));
+ \& int   pthread_key_delete(pthread_key_t);
+ \& int   pthread_mutex_destroy(pthread_mutex_t *);
+ \& int   pthread_mutex_getprioceiling(const pthread_mutex_t *, int *);
+ \& int   pthread_mutex_init(pthread_mutex_t *, const pthread_mutexattr_t *);
+ \& int   pthread_mutex_lock(pthread_mutex_t *);
+ \& int   pthread_mutex_setprioceiling(pthread_mutex_t *, int, int *);
+ \& int   pthread_mutex_trylock(pthread_mutex_t *);
+ \& int   pthread_mutex_unlock(pthread_mutex_t *);
+ \& int   pthread_mutexattr_destroy(pthread_mutexattr_t *);
+ \& int   pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *, int *);
+ \& int   pthread_mutexattr_getprotocol(const pthread_mutexattr_t *, int *);
+ \& int   pthread_mutexattr_getpshared(const pthread_mutexattr_t *, int *);
+ \& int   pthread_mutexattr_gettype(const pthread_mutexattr_t *, int *);
+ \& int   pthread_mutexattr_init(pthread_mutexattr_t *);
+ \& int   pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int);
+ \& int   pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int);
+ \& int   pthread_mutexattr_setpshared(pthread_mutexattr_t *, int);
+ \& int   pthread_mutexattr_settype(pthread_mutexattr_t *, int);
+ \& int   pthread_once(pthread_once_t *, void (*)(void));
+ \& int   pthread_rwlock_destroy(pthread_rwlock_t *);
+ \& int   pthread_rwlock_init(pthread_rwlock_t *, const pthread_rwlockattr_t *);
+ \& int   pthread_rwlock_rdlock(pthread_rwlock_t *);
+ \& int   pthread_rwlock_tryrdlock(pthread_rwlock_t *);
+ \& int   pthread_rwlock_trywrlock(pthread_rwlock_t *);
+ \& int   pthread_rwlock_unlock(pthread_rwlock_t *);
+ \& int   pthread_rwlock_wrlock(pthread_rwlock_t *);
+ \& int   pthread_rwlockattr_destroy(pthread_rwlockattr_t *);
+ \& int   pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *, int *);
+ \& int   pthread_rwlockattr_init(pthread_rwlockattr_t *);
+ \& int   pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int);
+ \& pthread_t pthread_self(void);
+ \& int   pthread_setcancelstate(int, int *);
+ \& int   pthread_setcanceltype(int, int *);
+ \& int   pthread_setconcurrency(int);
+ \& int   pthread_setschedparam(pthread_t, int, const struct sched_param *);
+ \& int   pthread_setspecific(pthread_key_t, const void *);
+ \& void  pthread_testcancel(void);
+ .Ve
+ Inclusion of the \fI<pthread.h\fR> header will make visible symbols defined
+ in the headers \fI<sched.h\fR> and \fI<time.h\fR>.
+ .SH "APPLICATION USAGE"
+ An interpretation request has been filed with IEEE PASC concerning
+ requirements for visibility of symbols in this header.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_getguardsize()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_cancel()\fR,
+ \fIpthread_cleanup_push()\fR,
+ \fIpthread_cond_init()\fR,
+ \fIpthread_cond_signal()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_condattr_init()\fR,
+ \fIpthread_create()\fR,
+ \fIpthread_detach()\fR,
+ \fIpthread_equal()\fR,
+ \fIpthread_exit()\fR,
+ \fIpthread_getconcurrency()\fR,
+ \fIpthread_getschedparam()\fR,
+ \fIpthread_join()\fR,
+ \fIpthread_key_create()\fR,
+ \fIpthread_key_delete()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_setprioceiling()\fR,
+ \fIpthread_mutexattr_init()\fR,
+ \fIpthread_mutexattr_gettype()\fR,
+ \fIpthread_mutexattr_setprotocol()\fR,
+ \fIpthread_once()\fR,
+ \fIpthread_self()\fR,
+ \fIpthread_setcancelstate()\fR,
+ \fIpthread_setspecific()\fR,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fI<sched.h\fR>,
+ \fI<time.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_atfork\fR \- register fork handlers
+ .SH "SYNOPSIS"
+ #include <sys/types.h>
+ .PP
+ #include <unistd.h>
+ .PP
+ int \fIpthread_atfork\fR\|(void (*\fIprepare\fR)(void), void (*\fIparent\fR)(void),
+ void (*\fIchild\fR)(void));
+ .SH "DESCRIPTION"
+ The \fIpthread_atfork()\fR function declares fork handlers to be called
+ before and after \fIfork()\fR, in the context of the thread that called
+ \fIfork()\fR. The \fIprepare\fR fork handler is called before \fIfork()\fR
+ processing commences. The \fIparent\fR fork handle is called after
+ \fIfork()\fR processing completes in the parent process. The \fIchild\fR fork
+ handler is called after \fIfork()\fR processing completes in the child
+ process. If no handling is desired at one or more of these three points,
+ the corresponding fork handler \fIaddress\fR\|(es) may be set to NULL.
+ .PP
+ The order of calls to \fIpthread_atfork()\fR is significant. The \fIparent\fR
+ and \fIchild\fR fork handlers are called in the order in which they were
+ established by calls to \fIpthread_atfork()\fR. The \fIprepare\fR fork
+ handlers are called in the opposite order.
+ .SH "RETURN VALUE"
+ Upon successful completion, \fIpthread_atfork()\fR returns a value of zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_atfork()\fR function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient table space exists to record the fork handler addresses.
+ .PP
+ The \fIpthread_atfork()\fR function will not return an error code of
+ [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIatexit()\fR,
+ \fIfork()\fR,
+ \fI<sys/types.h\fR>
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_init,\fR \fBpthread_attr_destroy\fR
+ \- initialise and destroy threads attribute object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_init\fR\|(pthread_attr_t *\fIattr\fR);
+ .PP
+ int \fIpthread_attr_destroy\fR\|(pthread_attr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function \fIpthread_attr_init()\fR initialises a thread attributes
+ object \fIattr\fR with the default value for all of the individual
+ attributes used by a given implementation.
+ .PP
+ The resulting attribute object (possibly modified by setting individual
+ attribute values), when used by \fIpthread_create()\fR, defines the
+ attributes of the thread created. A single attributes object can be used
+ in multiple simultaneous calls to \fIpthread_create()\fR.
+ .PP
+ The \fIpthread_attr_destroy()\fR function is used to destroy a thread
+ attributes object. An implementation may cause \fIpthread_attr_destroy()\fR
+ to set \fIattr\fR to an implementation-dependent invalid value. The
+ behaviour of using the attribute after it has been destroyed is
+ undefined.
+ .SH "RETURN VALUE"
+ Upon successful completion, \fIpthread_attr_init()\fR and
+ \fIpthread_attr_destroy()\fR return a value of 0. Otherwise, an error
+ number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_init()\fR function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the thread attributes object.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setdetachstate,\fR \fBpthread_attr_getdetachstate\fR
+ \- set and get detachstate attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setdetachstate\fR\|(pthread_attr_t *\fIattr\fR, int \fIdetachstate\fR);
+ .PP
+ int \fIpthread_attr_getdetachstate\fR\|(const pthread_attr_t *\fIattr\fR, int *\fIdetachstate\fR);
+ .SH "DESCRIPTION"
+ The \fIdetachstate\fR attribute controls whether the thread is created in a
+ detached state. If the thread is created detached, then use of the ID of
+ the newly created thread by the \fIpthread_detach()\fR or \fIpthread_join()\fR
+ function is an error.
+ .PP
+ The \fIpthread_attr_setdetachstate()\fR and
+ \fIpthread_attr_getdetachstate()\fR, respectively, set and get the
+ \fIdetachstate\fR attribute in the \fIattr\fR object.
+ .PP
+ The \fIdetachstate\fR can be set to either PTHREAD_CREATE_DETACHED or
+ PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes
+ all threads created with \fIattr\fR to be in the detached state, whereas
+ using a value of PTHREAD_CREATE_JOINABLE causes all threads created
+ with \fIattr\fR to be in the joinable state. The default value of the
+ \fIdetachstate\fR attribute is PTHREAD_CREATE_JOINABLE .
+ .SH "RETURN VALUE"
+ Upon successful completion, \fIpthread_attr_setdetachstate()\fR and
+ \fIpthread_attr_getdetachstate()\fR return a value of 0. Otherwise, an
+ error number is returned to indicate the error.
+ .PP
+ The \fIpthread_attr_getdetachstate()\fR function stores the value of the
+ \fIdetachstate\fR attribute in \fIdetachstate\fR if successful.
+ .SH "ERRORS"
+ The \fIpthread_attr_setdetachstate()\fR function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of \fIdetachstate\fR was not valid
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_getguardsize,\fR \fBpthread_attr_setguardsize\fR \-
+ get or set the thread guardsize attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_getguardsize\fR\|(const pthread_attr_t \fI*attr\fR, size_t
+ \fI*guardsize\fR); int \fIpthread_attr_setguardsize\fR\|(pthread_attr_t \fI*attr\fR,
+ size_t \fIguardsize\fR);
+ .SH "DESCRIPTION"
+ The \fIguardsize\fR attribute controls the size of the guard area for the
+ created thread's stack. The \fIguardsize\fR attribute provides protection
+ against overflow of the stack pointer. If a thread's stack is created
+ with guard protection, the implementation allocates extra memory at the
+ overflow end of the stack as a buffer against stack overflow of the
+ stack pointer. If an application overflows into this buffer an error
+ results (possibly in a SIGSEGV signal being delivered to the thread).
+ .PP
+ The \fIguardsize\fR attribute is provided to the application
+ for two reasons:
+ .Ip "1." 4
+ Overflow protection can potentially result in wasted system resources.
+ An application that creates a large number of threads, and which knows
+ its threads will never overflow their stack, can save system resources
+ by turning off guard areas.
+ .Ip "2." 4
+ When threads allocate large data structures on the stack,
+ large guard areas may be needed to detect stack overflow.
+ .PP
+ The \fIpthread_attr_getguardsize()\fR function gets the \fIguardsize\fR
+ attribute in the \fIattr\fR object. This attribute is returned in the
+ \fIguardsize\fR parameter.
+ .PP
+ The \fIpthread_attr_setguardsize()\fR function sets the \fIguardsize\fR
+ attribute in the \fIattr\fR object. The new value of this attribute is
+ obtained from the \fIguardsize\fR parameter. If \fIguardsize\fR is zero,
+ a guard area will not be provided for threads created with \fIattr\fR.
+ If \fIguardsize\fR is greater than zero, a guard area of at least size
+ \fIguardsize\fR bytes is provided for each thread created with \fIattr\fR.
+ .PP
+ A conforming implementation is permitted to round up the value
+ contained in \fIguardsize\fR to a multiple of the configurable system
+ variable \s-1PAGESIZE\s0 (see \fI<sys/mman.h\fR>). If an implementation rounds
+ up the value of \fIguardsize\fR to a multiple of \s-1PAGESIZE\s0, a call to
+ \fIpthread_attr_getguardsize()\fR specifying \fIattr\fR will store in the
+ \fIguardsize\fR parameter the guard size specified by the previous
+ \fIpthread_attr_setguardsize()\fR function call.
+ .PP
+ The default value of the \fIguardsize\fR attribute is \s-1PAGESIZE\s0 bytes. The
+ actual value of \s-1PAGESIZE\s0 is implementation-dependent and may not be the
+ same on all implementations.
+ .PP
+ If the \fIstackaddr\fR attribute has been set (that is, the caller is
+ allocating and managing its own thread stacks), the \fIguardsize\fR
+ attribute is ignored and no protection will be provided by the
+ implementation. It is the responsibility of the application to manage
+ stack overflow along with stack allocation and management in this case.
+ .SH "RETURN VALUE"
+ If successful, the \fIpthread_attr_getguardsize()\fR and
+ \fIpthread_attr_setguardsize()\fR functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_getguardsize()\fR and \fIpthread_attr_setguardsize()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The attribute \fIattr\fR is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The parameter \fIguardsize\fR is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The parameter \fIguardsize\fR contains an invalid value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setinheritsched,\fR \fBpthread_attr_getinheritsched\fR
+ \- set and get inheritsched attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setinheritsched\fR\|(pthread_attr_t *\fIattr\fR,
+ int \fIinheritsched\fR);
+ int \fIpthread_attr_getinheritsched\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIinheritsched\fR);
+ .SH "DESCRIPTION"
+ The functions \fIpthread_attr_setinheritsched()\fR and
+ \fIpthread_attr_getinheritsched()\fR, respectively, set and get the
+ \fIinheritsched\fR attribute in the \fIattr\fR argument.
+ .PP
+ When the attribute objects are used by \fIpthread_create()\fR, the
+ \fIinheritsched\fR attribute determines how the other scheduling attributes
+ of the created thread are to be set:
+ .Ip "\s-1PTHREAD_INHERIT_SCHED\s0" 4
+ Specifies that the scheduling policy and associated attributes are to
+ be inherited from the creating thread, and the scheduling attributes in
+ this \fIattr\fR argument are to be ignored.
+ .Ip "\s-1PTHREAD_EXPLICIT_SCHED\s0" 4
+ Specifies that the scheduling policy and associated attributes
+ are to be set to the corresponding values from this attribute object.
+ .PP
+ The symbols \s-1PTHREAD_INHERIT_SCHED\s0 and \s-1PTHREAD_EXPLICIT_SCHED\s0 are defined
+ in the header \fI<pthread.h\fR>.
+ .SH "RETURN VALUE"
+ If successful, the \fIpthread_attr_setinheritsched()\fR and
+ \fIpthread_attr_getinheritsched()\fR functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_setinheritsched()\fR and
+ \fIpthread_attr_getinheritsched()\fR functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_attr_setinheritsched()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with the
+ specified attributes using \fIpthread_create()\fR. Using these routines
+ does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setschedparam,\fR \fBpthread_attr_getschedparam\fR
+ \- set and get schedparam attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setschedparam\fR\|(pthread_attr_t *\fIattr\fR, const struct sched_param *\fIparam\fR);
+ .PP
+ int \fIpthread_attr_getschedparam\fR\|(const pthread_attr_t *\fIattr\fR, struct sched_param *\fIparam\fR);
+ .SH "DESCRIPTION"
+ The functions \fIpthread_attr_setschedparam()\fR and
+ \fIpthread_attr_getschedparam()\fR, respectively, set and get the
+ scheduling parameter attributes in the \fIattr\fR argument. The contents of
+ the \fIparam\fR structure are defined in \fI<sched.h\fR>. For the SCHED_FIFO
+ and SCHED_RR policies, the only required member of \fIparam\fR is
+ \fIsched_priority\fR.
+ .SH "RETURN VALUE"
+ If successful, the \fIpthread_attr_setschedparam()\fR and
+ \fIpthread_attr_getschedparam()\fR functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_setschedparam()\fR function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .PP
+ The
+ \fIpthread_attr_setschedparam()\fR
+ and
+ \fIpthread_attr_getschedparam()\fR
+ functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with the
+ specified attributes using \fIpthread_create()\fR. Using these routines
+ does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setschedpolicy,\fR \fBpthread_attr_getschedpolicy\fR
+ \- set and get schedpolicy attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setschedpolicy\fR\|(pthread_attr_t *\fIattr\fR, int \fIpolicy\fR);
+ int \fIpthread_attr_getschedpolicy\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIpolicy\fR);
+ .SH "DESCRIPTION"
+ The functions \fIpthread_attr_setschedpolicy()\fR and
+ \fIpthread_attr_getschedpolicy()\fR, respectively, set and get the
+ \fIschedpolicy\fR attribute in the \fIattr\fR argument.
+ .PP
+ The supported values of \fIpolicy\fR include SCHED_FIFO, SCHED_RR and
+ SCHED_OTHER, which are defined by the header \fI<sched.h\fR>. When threads
+ executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting
+ on a mutex, they acquire the mutex in priority order when the mutex is
+ unlocked.
+ .SH "RETURN VALUE"
+ If successful, the \fIpthread_attr_setschedpolicy()\fR and
+ \fIpthread_attr_getschedpolicy()\fR functions return zero. Otherwise, an
+ error number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_setschedpolicy()\fR and
+ \fIpthread_attr_getschedpolicy()\fR functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The \fIpthread_attr_setschedpolicy()\fR function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with the
+ specified attributes using \fIpthread_create()\fR. Using these routines
+ does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setscope,\fR \fBpthread_attr_getscope\fR
+ \- set and get contentionscope attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setscope\fR\|(pthread_attr_t *\fIattr\fR, int \fIcontentionscope\fR);
+ int \fIpthread_attr_getscope\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIcontentionscope\fR);
+ .SH "DESCRIPTION"
+ The \fIpthread_attr_setscope()\fR and \fIpthread_attr_getscope()\fR functions
+ are used to set and get the \fIcontentionscope\fR attribute in the \fIattr\fR
+ object.
+ .PP
+ The \fIcontentionscope\fR attribute may have the values
+ PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or
+ PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope.
+ The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined
+ by the header \fI<pthread.h\fR>.
+ .SH "RETURN VALUE"
+ If successful, the \fIpthread_attr_setscope()\fR and
+ \fIpthread_attr_getscope()\fR functions return zero. Otherwise, an error
+ number is returned to indicate the error.
+ .SH "ERRORS"
+ The \fIpthread_attr_setscope()\fR and \fIpthread_attr_getscope()\fR functions
+ will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_attr_setscope()\fR,
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with the
+ specified attributes using \fIpthread_create()\fR. Using these routines
+ does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setstackaddr,\fR \fBpthread_attr_getstackaddr\fR
+ \- set and get stackaddr attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setstackaddr\fR\|(pthread_attr_t *\fIattr\fR, void *\fIstackaddr\fR);
+ .PP
+ int \fIpthread_attr_getstackaddr\fR\|(const pthread_attr_t *\fIattr\fR, void **\fIstackaddr\fR);
+ .SH "DESCRIPTION"
+ The functions \fIpthread_attr_setstackaddr()\fR and
+ \fIpthread_attr_getstackaddr()\fR, respectively, set and get the thread
+ creation \fIstackaddr\fR attribute in the \fIattr\fR object.
+ .PP
+ The \fIstackaddr\fR attribute specifies the location of storage to be used
+ for the created thread's stack. The size of the storage is at least
+ PTHREAD_STACK_MIN.
+ .SH "RETURN VALUE"
+ Upon successful completion, \fIpthread_attr_setstackaddr()\fR and
+ \fIpthread_attr_getstackaddr()\fR return a value of 0. Otherwise, an error
+ number is returned to indicate the error.
+ .PP
+ The \fIpthread_attr_getstackaddr()\fR function stores the \fIstackaddr\fR
+ attribute value in \fIstackaddr\fR if successful.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ These functions will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_create()\fR,
+ \fI<limits.h\fR>,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setstacksize,\fR \fBpthread_attr_getstacksize\fR
+ \- set and get stacksize attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setstacksize\fR\|(pthread_attr_t *\fIattr\fR, size_t \fIstacksize\fR);
+ int \fIpthread_attr_getstacksize\fR\|(const pthread_attr_t *\fIattr\fR,
+ size_t *\fIstacksize\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setstacksize()\fR
+ and
+ \fIpthread_attr_getstacksize()\fR,
+ respectively, set and get the thread creation
+ \fIstacksize\fR
+ attribute in the
+ \fIattr\fR
+ object.
+ .PP
+ The
+ \fIstacksize\fR
+ attribute defines the minimum stack size (in bytes) allocated for
+ the created threads stack.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_attr_setstacksize()\fR
+ and
+ \fIpthread_attr_getstacksize()\fR
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ The
+ \fIpthread_attr_getstacksize()\fR
+ function stores the
+ \fIstacksize\fR
+ attribute value in
+ \fIstacksize\fR
+ if successful.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setstacksize()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of
+ \fIstacksize\fR
+ is less than \s-1PTHREAD_STACK_MIN\s0 or exceeds a system-imposed limit.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_create()\fR,
+ \fI<limits.h\fR>,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_init,\fR \fBpthread_attr_destroy\fR
+ \- initialise and destroy threads attribute object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_init\fR\|(pthread_attr_t *\fIattr\fR);
+ int \fIpthread_attr_destroy\fR\|(pthread_attr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_attr_init()\fR
+ initialises a thread attributes object
+ \fIattr\fR
+ with the default value for all of the individual attributes
+ used by a given implementation.
+ .PP
+ The resulting attribute object
+ (possibly modified by setting individual attribute values),
+ when used by
+ \fIpthread_create()\fR,
+ defines the attributes of the thread created.
+ A single attributes object can be used in multiple simultaneous calls to
+ \fIpthread_create()\fR.
+ .PP
+ The
+ \fIpthread_attr_destroy()\fR
+ function is used to destroy a thread attributes object.
+ An implementation may cause
+ \fIpthread_attr_destroy()\fR
+ to set
+ \fIattr\fR
+ to an implementation-dependent invalid value.
+ The behaviour of using the attribute after it has been destroyed is undefined.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_attr_init()\fR
+ and
+ \fIpthread_attr_destroy()\fR
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_init()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the thread attributes object.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setdetachstate,\fR \fBpthread_attr_getdetachstate\fR
+ \- set and get detachstate attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setdetachstate\fR\|(pthread_attr_t *\fIattr\fR, int \fIdetachstate\fR);
+ int \fIpthread_attr_getdetachstate\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIdetachstate\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIdetachstate\fR
+ attribute controls whether the thread is created in a detached state.
+ If the thread is created detached,
+ then use of the ID of the newly created thread by the
+ \fIpthread_detach()\fR
+ or
+ \fIpthread_join()\fR
+ function is an error.
+ .PP
+ The
+ \fIpthread_attr_setdetachstate()\fR
+ and
+ \fIpthread_attr_getdetachstate()\fR,
+ respectively, set and get the
+ \fIdetachstate\fR
+ attribute in the
+ \fIattr\fR
+ object.
+ .PP
+ The
+ \fIdetachstate\fR
+ can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
+ A value of PTHREAD_CREATE_DETACHED causes all threads created with
+ \fIattr\fR
+ to be in the detached state, whereas using a value of
+ PTHREAD_CREATE_JOINABLE
+ causes all threads created with
+ \fIattr\fR
+ to be in the joinable state.
+ The default value of the
+ \fIdetachstate\fR
+ attribute is
+ PTHREAD_CREATE_JOINABLE .
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_attr_setdetachstate()\fR
+ and
+ \fIpthread_attr_getdetachstate()\fR
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ The
+ \fIpthread_attr_getdetachstate()\fR
+ function stores the value of the
+ \fIdetachstate\fR
+ attribute in
+ \fIdetachstate\fR
+ if successful.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setdetachstate()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of
+ \fIdetachstate\fR
+ was not valid
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_getguardsize,\fR \fBpthread_attr_setguardsize\fR \-
+ get or set the thread guardsize attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_getguardsize\fR\|(const pthread_attr_t \fI*attr\fR,
+ size_t \fI*guardsize\fR);
+ int \fIpthread_attr_setguardsize\fR\|(pthread_attr_t \fI*attr\fR,
+ size_t \fIguardsize\fR);
+ .SH "DESCRIPTION"
+ The \fIguardsize\fR attribute controls the size
+ of the guard area for the created thread's stack. The \fIguardsize\fR
+ attribute provides protection against overflow of the
+ stack pointer. If a thread's stack is created with guard
+ protection, the implementation allocates extra
+ memory at the overflow end of the stack as a buffer against
+ stack overflow of the stack pointer. If an application
+ overflows into this buffer an error results (possibly
+ in a SIGSEGV signal being delivered to the thread).
+ .PP
+ The \fIguardsize\fR attribute is provided to the application
+ for two reasons:
+ .Ip "1." 4
+ Overflow protection can potentially
+ result in wasted system resources. An application that creates a large
+ number of threads, and which knows its threads will never overflow
+ their stack, can save system resources by turning off guard areas.
+ .Ip "2." 4
+ When threads allocate large data structures on the stack,
+ large guard areas may be needed to detect stack overflow.
+ .PP
+ The
+ \fIpthread_attr_getguardsize()\fR
+ function gets the
+ \fIguardsize\fR attribute in the \fIattr\fR object. This attribute is
+ returned in the \fIguardsize\fR parameter.
+ .PP
+ The
+ \fIpthread_attr_setguardsize()\fR
+ function sets the
+ \fIguardsize\fR attribute in the \fIattr\fR object. The new value of
+ this attribute is obtained from the \fIguardsize\fR parameter.
+ If \fIguardsize\fR is zero, a guard area will not be
+ provided for threads created with \fIattr\fR. If \fIguardsize\fR is
+ greater
+ than zero, a guard area of at least size \fIguardsize\fR
+ bytes is provided for each thread created with \fIattr\fR.
+ .PP
+ A conforming implementation is permitted to round up
+ the value contained in \fIguardsize\fR to a multiple
+ of the configurable system variable \s-1PAGESIZE\s0 (see
+ \fI<sys/mman.h\fR>).
+ If an implementation rounds up the
+ value of \fIguardsize\fR to a multiple of \s-1PAGESIZE\s0, a call to
+ \fIpthread_attr_getguardsize()\fR
+ specifying \fIattr\fR will
+ store in the \fIguardsize\fR parameter the guard size specified by the
+ previous
+ \fIpthread_attr_setguardsize()\fR
+ function call.
+ .PP
+ The default value of the \fIguardsize\fR attribute is \s-1PAGESIZE\s0 bytes.
+ The actual value of \s-1PAGESIZE\s0 is
+ implementation-dependent and may not be the same on all implementations.
+ .PP
+ If the \fIstackaddr\fR attribute has been set (that is, the caller
+ is allocating and managing its own thread stacks), the
+ \fIguardsize\fR attribute is ignored and no protection
+ will be provided by the implementation. It is the
+ responsibility of the application to manage stack overflow
+ along with stack allocation and management in this
+ case.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_attr_getguardsize()\fR
+ and
+ \fIpthread_attr_setguardsize()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_getguardsize()\fR
+ and
+ \fIpthread_attr_setguardsize()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The attribute \fIattr\fR is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The parameter \fIguardsize\fR is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The parameter \fIguardsize\fR contains an invalid value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setinheritsched,\fR \fBpthread_attr_getinheritsched\fR
+ \- set and get inheritsched attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setinheritsched\fR\|(pthread_attr_t *\fIattr\fR,
+ int \fIinheritsched\fR);
+ int \fIpthread_attr_getinheritsched\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIinheritsched\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setinheritsched()\fR
+ and
+ \fIpthread_attr_getinheritsched()\fR,
+ respectively, set and get the
+ \fIinheritsched\fR
+ attribute in the
+ \fIattr\fR
+ argument.
+ .PP
+ When the attribute objects are used by
+ \fIpthread_create()\fR,
+ the
+ \fIinheritsched\fR
+ attribute determines how the other scheduling attributes of
+ the created thread are to be set:
+ .Ip "\s-1PTHREAD_INHERIT_SCHED\s0" 4
+ Specifies that the scheduling policy and associated attributes
+ are to be inherited from the creating thread, and the scheduling
+ attributes in this
+ \fIattr\fR
+ argument are to be ignored.
+ .Ip "\s-1PTHREAD_EXPLICIT_SCHED\s0" 4
+ Specifies that the scheduling policy and associated attributes
+ are to be set to the corresponding values from this attribute object.
+ .PP
+ The symbols \s-1PTHREAD_INHERIT_SCHED\s0 and \s-1PTHREAD_EXPLICIT_SCHED\s0
+ are defined in the header
+ \fI<pthread.h\fR>.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_attr_setinheritsched()\fR
+ and
+ \fIpthread_attr_getinheritsched()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setinheritsched()\fR
+ and
+ \fIpthread_attr_getinheritsched()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_attr_setinheritsched()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ \fIpthread_create()\fR.
+ Using these routines does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setschedparam,\fR \fBpthread_attr_getschedparam\fR
+ \- set and get schedparam attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setschedparam\fR\|(pthread_attr_t *\fIattr\fR,
+ const struct sched_param *\fIparam\fR);
+ int \fIpthread_attr_getschedparam\fR\|(const pthread_attr_t *\fIattr\fR,
+ struct sched_param *\fIparam\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setschedparam()\fR
+ and
+ \fIpthread_attr_getschedparam()\fR,
+ respectively, set and get the scheduling parameter
+ attributes in the
+ \fIattr\fR
+ argument.
+ The contents of the
+ \fIparam\fR
+ structure are defined in
+ \fI<sched.h\fR>.
+ For the SCHED_FIFO and SCHED_RR policies,
+ the only required member of
+ \fIparam\fR
+ is
+ \fIsched_priority\fR.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_attr_setschedparam()\fR
+ and
+ \fIpthread_attr_getschedparam()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setschedparam()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .PP
+ The
+ \fIpthread_attr_setschedparam()\fR
+ and
+ \fIpthread_attr_getschedparam()\fR
+ functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ \fIpthread_create()\fR.
+ Using these routines does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setschedpolicy,\fR \fBpthread_attr_getschedpolicy\fR
+ \- set and get schedpolicy attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setschedpolicy\fR\|(pthread_attr_t *\fIattr\fR, int \fIpolicy\fR);
+ int \fIpthread_attr_getschedpolicy\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIpolicy\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setschedpolicy()\fR
+ and
+ \fIpthread_attr_getschedpolicy()\fR,
+ respectively, set and get the
+ \fIschedpolicy\fR
+ attribute in the
+ \fIattr\fR
+ argument.
+ .PP
+ The supported values of
+ \fIpolicy\fR
+ include SCHED_FIFO, SCHED_RR and SCHED_OTHER,
+ which are defined by the header
+ \fI<sched.h\fR>.
+ When threads executing with the scheduling policy
+ SCHED_FIFO or SCHED_RR are waiting on a mutex,
+ they acquire the mutex in priority order when the mutex is unlocked.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_attr_setschedpolicy()\fR
+ and
+ \fIpthread_attr_getschedpolicy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setschedpolicy()\fR
+ and
+ \fIpthread_attr_getschedpolicy()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_attr_setschedpolicy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ \fIpthread_create()\fR.
+ Using these routines does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setscope()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setscope,\fR \fBpthread_attr_getscope\fR
+ \- set and get contentionscope attribute
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setscope\fR\|(pthread_attr_t *\fIattr\fR, int \fIcontentionscope\fR);
+ int \fIpthread_attr_getscope\fR\|(const pthread_attr_t *\fIattr\fR,
+ int *\fIcontentionscope\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_attr_setscope()\fR
+ and
+ \fIpthread_attr_getscope()\fR
+ functions are used to set and get the
+ \fIcontentionscope\fR
+ attribute in the
+ \fIattr\fR
+ object.
+ .PP
+ The
+ \fIcontentionscope\fR
+ attribute may have the values
+ PTHREAD_SCOPE_SYSTEM,
+ signifying system scheduling contention scope,
+ or PTHREAD_SCOPE_PROCESS,
+ signifying process scheduling contention scope.
+ The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS
+ are defined by the header
+ \fI<pthread.h\fR>.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_attr_setscope()\fR
+ and
+ \fIpthread_attr_getscope()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setscope()\fR
+ and
+ \fIpthread_attr_getscope()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_attr_setscope()\fR,
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the attribute being set is not valid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the attribute to an unsupported value.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ After these attributes have been set, a thread can be created with
+ the specified attributes using
+ \fIpthread_create()\fR.
+ Using these routines does not affect the current running thread.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setinheritsched()\fR,
+ \fIpthread_attr_setschedpolicy()\fR,
+ \fIpthread_attr_setschedparam()\fR,
+ \fIpthread_create()\fR,
+ \fI<pthread.h\fR>,
+ \fIpthread_setschedparam()\fR,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setstackaddr,\fR \fBpthread_attr_getstackaddr\fR
+ \- set and get stackaddr attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setstackaddr\fR\|(pthread_attr_t *\fIattr\fR, void *\fIstackaddr\fR);
+ int \fIpthread_attr_getstackaddr\fR\|(const pthread_attr_t *\fIattr\fR,
+ void **\fIstackaddr\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setstackaddr()\fR
+ and
+ \fIpthread_attr_getstackaddr()\fR,
+ respectively, set and get the thread creation
+ \fIstackaddr\fR
+ attribute in the
+ \fIattr\fR
+ object.
+ .PP
+ The
+ \fIstackaddr\fR
+ attribute specifies the location of storage
+ to be used for the created thread's stack.
+ The size of the storage is at least PTHREAD_STACK_MIN.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_attr_setstackaddr()\fR
+ and
+ \fIpthread_attr_getstackaddr()\fR
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ The
+ \fIpthread_attr_getstackaddr()\fR
+ function stores the
+ \fIstackaddr\fR
+ attribute value in
+ \fIstackaddr\fR
+ if successful.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ These functions will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_attr_setstacksize()\fR,
+ \fIpthread_create()\fR,
+ \fI<limits.h\fR>,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_attr_setstacksize,\fR \fBpthread_attr_getstacksize\fR
+ \- set and get stacksize attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_attr_setstacksize\fR\|(pthread_attr_t *\fIattr\fR, size_t \fIstacksize\fR);
+ int \fIpthread_attr_getstacksize\fR\|(const pthread_attr_t *\fIattr\fR,
+ size_t *\fIstacksize\fR);
+ .SH "DESCRIPTION"
+ The functions
+ \fIpthread_attr_setstacksize()\fR
+ and
+ \fIpthread_attr_getstacksize()\fR,
+ respectively, set and get the thread creation
+ \fIstacksize\fR
+ attribute in the
+ \fIattr\fR
+ object.
+ .PP
+ The
+ \fIstacksize\fR
+ attribute defines the minimum stack size (in bytes) allocated for
+ the created threads stack.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_attr_setstacksize()\fR
+ and
+ \fIpthread_attr_getstacksize()\fR
+ return a value of 0.
+ Otherwise, an error number is returned to indicate the error.
+ The
+ \fIpthread_attr_getstacksize()\fR
+ function stores the
+ \fIstacksize\fR
+ attribute value in
+ \fIstacksize\fR
+ if successful.
+ .SH "ERRORS"
+ The
+ \fIpthread_attr_setstacksize()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of
+ \fIstacksize\fR
+ is less than \s-1PTHREAD_STACK_MIN\s0 or exceeds a system-imposed limit.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_attr_init()\fR,
+ \fIpthread_attr_setstackaddr()\fR,
+ \fIpthread_attr_setdetachstate()\fR,
+ \fIpthread_create()\fR,
+ \fI<limits.h\fR>,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cancel\fR \- cancel execution of a thread
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cancel\fR\|(pthread_t \fIthread\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_cancel()\fR
+ function requests that
+ \fIthread\fR
+ be canceled.
+ The target threads cancelability state and type
+ determines when the cancellation takes effect.
+ When the cancellation is acted on, the
+ cancellation cleanup handlers for
+ \fIthread\fR
+ are called.
+ When the last cancellation cleanup handler returns,
+ the thread-specific data destructor functions are called for
+ \fIthread\fR.
+ When the last destructor function returns,
+ \fIthread\fR
+ is terminated.
+ .PP
+ The cancellation processing in the target thread runs asynchronously
+ with respect to the calling thread returning from
+ \fIpthread_cancel()\fR.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_cancel()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_cancel()\fR
+ function may fail if:
+ .Ip "[\s-1ESRCH\s0]" 4
+ No thread could be found corresponding to that specified
+ by the given thread \s-1ID\s0.
+ .PP
+ The
+ \fIpthread_cancel()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_exit()\fR,
+ \fIpthread_join()\fR,
+ \fIpthread_setcancelstate()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cleanup_push,\fR \fBpthread_cleanup_pop\fR \- establish cancellation handlers
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ void \fIpthread_cleanup_push\fR\|(void (*\fIroutine\fR)(void*), void *\fIarg\fR);
+ void \fIpthread_cleanup_pop\fR\|(int \fIexecute\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_cleanup_push()\fR
+ function pushes the specified cancellation cleanup handler
+ \fIroutine\fR
+ onto the calling thread's cancellation cleanup stack.
+ The cancellation cleanup handler is popped from the
+ cancellation cleanup stack and invoked with the argument
+ \fIarg\fR
+ when: (a) the thread exits (that is, calls
+ \fIpthread_exit()\fR),
+ (b) the thread acts upon a cancellation request, or
+ (c) the thread calls
+ \fIpthread_cleanup_pop()\fR
+ with a non-zero
+ \fIexecute\fR
+ argument.
+ .PP
+ The
+ \fIpthread_cleanup_pop()\fR
+ function removes the routine at the top of the calling thread's
+ cancellation cleanup stack and optionally invokes it (if
+ \fIexecute\fR
+ is non-zero).
+ .PP
+ These functions may be implemented as macros and will
+ appear as statements and in pairs within the same lexical scope (that is, the
+ \fIpthread_cleanup_push()\fR
+ macro may be thought to expand to a token list whose first
+ token is
+ \fB`{\*(R'\fR
+ with
+ \fIpthread_cleanup_pop()\fR
+ expanding to a token list whose last token is the corresponding
+ \fB`}\*(R'\fR.
+ .PP
+ The effect of calling
+ \fIlongjmp()\fR
+ or
+ \fIsiglongjmp()\fR
+ is undefined if there have been any calls to
+ \fIpthread_cleanup_push()\fR
+ or
+ \fIpthread_cleanup_pop()\fR
+ made without the matching call
+ since the jump buffer was filled.
+ The effect of calling
+ \fIlongjmp()\fR
+ or
+ \fIsiglongjmp()\fR
+ from inside a cancellation cleanup handler is also
+ undefined unless the jump buffer was also filled in the
+ cancellation cleanup handler.
+ .SH "RETURN VALUE"
+ The
+ \fIpthread_cleanup_push()\fR
+ and
+ \fIpthread_cleanup_pop()\fR
+ functions return no value.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ These functions will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cancel()\fR,
+ \fIpthread_setcancelstate()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cleanup_push,\fR \fBpthread_cleanup_pop\fR \- establish cancellation handlers
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ void \fIpthread_cleanup_push\fR\|(void (*\fIroutine\fR)(void*), void *\fIarg\fR);
+ void \fIpthread_cleanup_pop\fR\|(int \fIexecute\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_cleanup_push()\fR
+ function pushes the specified cancellation cleanup handler
+ \fIroutine\fR
+ onto the calling thread's cancellation cleanup stack.
+ The cancellation cleanup handler is popped from the
+ cancellation cleanup stack and invoked with the argument
+ \fIarg\fR
+ when: (a) the thread exits (that is, calls
+ \fIpthread_exit()\fR),
+ (b) the thread acts upon a cancellation request, or
+ (c) the thread calls
+ \fIpthread_cleanup_pop()\fR
+ with a non-zero
+ \fIexecute\fR
+ argument.
+ .PP
+ The
+ \fIpthread_cleanup_pop()\fR
+ function removes the routine at the top of the calling thread's
+ cancellation cleanup stack and optionally invokes it (if
+ \fIexecute\fR
+ is non-zero).
+ .PP
+ These functions may be implemented as macros and will
+ appear as statements and in pairs within the same lexical scope (that is, the
+ \fIpthread_cleanup_push()\fR
+ macro may be thought to expand to a token list whose first
+ token is
+ \fB`{\*(R'\fR
+ with
+ \fIpthread_cleanup_pop()\fR
+ expanding to a token list whose last token is the corresponding
+ \fB`}\*(R'\fR.
+ .PP
+ The effect of calling
+ \fIlongjmp()\fR
+ or
+ \fIsiglongjmp()\fR
+ is undefined if there have been any calls to
+ \fIpthread_cleanup_push()\fR
+ or
+ \fIpthread_cleanup_pop()\fR
+ made without the matching call
+ since the jump buffer was filled.
+ The effect of calling
+ \fIlongjmp()\fR
+ or
+ \fIsiglongjmp()\fR
+ from inside a cancellation cleanup handler is also
+ undefined unless the jump buffer was also filled in the
+ cancellation cleanup handler.
+ .SH "RETURN VALUE"
+ The
+ \fIpthread_cleanup_push()\fR
+ and
+ \fIpthread_cleanup_pop()\fR
+ functions return no value.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ These functions will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cancel()\fR,
+ \fIpthread_setcancelstate()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_signal,\fR \fBpthread_cond_broadcast\fR \- signal or broadcast a
+ condition
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_signal\fR\|(pthread_cond_t *\fIcond\fR);
+ int \fIpthread_cond_broadcast\fR\|(pthread_cond_t *\fIcond\fR);
+ .SH "DESCRIPTION"
+ These two functions are used to unblock
+ threads blocked on a condition variable.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ call unblocks at least one of the threads that are blocked on the
+ specified condition variable
+ \fIcond\fR
+ (if any threads are blocked on
+ \fIcond\fR).
+ .PP
+ The
+ \fIpthread_cond_broadcast()\fR
+ call unblocks all threads currently blocked on the specified condition variable
+ \fIcond\fR.
+ .PP
+ If more than one thread is blocked on a condition variable,
+ the scheduling policy determines the order in which threads are unblocked.
+ When each thread unblocked as a result of a
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ returns from its call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ the thread owns the mutex with which it called
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR.
+ The \fIthread\fR\|(s) that are unblocked contend for the mutex
+ according to the scheduling policy (if applicable),
+ and as if each had called
+ \fIpthread_mutex_lock()\fR.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ functions may be called by a thread whether or not it
+ currently owns the mutex that threads calling
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ have associated with the condition variable during their waits;
+ however, if predictable scheduling behaviour is required,
+ then that mutex is locked by the thread calling
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ functions have no effect if there are no threads
+ currently blocked on
+ \fIcond\fR.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value
+ \fIcond\fR
+ does not refer to an initialised condition variable.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_init()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_init,\fR \fBpthread_cond_destroy\fR \- initialise and destroy
+ condition variables
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_init\fR\|(pthread_cond_t *\fIcond\fR,
+ const pthread_condattr_t *\fIattr\fR);
+ int \fIpthread_cond_destroy\fR\|(pthread_cond_t *\fIcond\fR);
+ pthread_cond_t \fIcond\fR = PTHREAD_COND_INITIALIZER;
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_cond_init()\fR
+ initialises the condition variable referenced by
+ \fIcond\fR
+ with attributes referenced by
+ \fIattr\fR.
+ If
+ \fIattr\fR
+ is NULL,
+ the default condition variable attributes are used;
+ the effect is the same as passing the address
+ of a default condition variable attributes object.
+ Upon successful initialisation,
+ the state of the condition variable becomes initialised.
+ .PP
+ Attempting to initialise an already initialised
+ condition variable
+ results in undefined behaviour.
+ .PP
+ The function
+ \fIpthread_cond_destroy()\fR
+ destroys the given condition variable specified by
+ \fIcond\fR;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_cond_destroy()\fR
+ to set the object referenced by
+ \fIcond\fR
+ to an invalid value.
+ A destroyed condition variable object
+ can be re-initialised using
+ \fIpthread_cond_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ It is safe to destroy an initialised condition variable
+ upon which no threads are currently blocked.
+ Attempting to destroy a condition variable
+ upon which other threads are currently blocked
+ results in undefined behaviour.
+ .PP
+ In cases where default condition variable attributes are appropriate,
+ the macro PTHREAD_COND_INITIALIZER
+ can be used to initialise condition variables that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_cond_init()\fR
+ with parameter
+ \fIattr\fR
+ specified as NULL, except that no error checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_cond_init()\fR
+ and
+ \fIpthread_cond_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL]
+ error checks, if implemented,
+ act as if they were performed immediately
+ at the beginning of processing for the function
+ and caused an error return
+ prior to modifying the state of the condition variable specified by
+ \fIcond\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other
+ than memory) to initialise another condition variable.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the condition variable.
+ .PP
+ The
+ \fIpthread_cond_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ \fIcond\fR,
+ a previously initialised, but
+ not yet destroyed, condition variable.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_cond_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ \fIcond\fR
+ while it is referenced
+ (for example, while being used in a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR)
+ by another thread.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIcond\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_signal()\fR,
+ \fIpthread_cond_broadcast()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_init,\fR \fBpthread_cond_destroy\fR \- initialise and destroy
+ condition variables
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_init\fR\|(pthread_cond_t *\fIcond\fR,
+ const pthread_condattr_t *\fIattr\fR);
+ int \fIpthread_cond_destroy\fR\|(pthread_cond_t *\fIcond\fR);
+ pthread_cond_t \fIcond\fR = PTHREAD_COND_INITIALIZER;
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_cond_init()\fR
+ initialises the condition variable referenced by
+ \fIcond\fR
+ with attributes referenced by
+ \fIattr\fR.
+ If
+ \fIattr\fR
+ is NULL,
+ the default condition variable attributes are used;
+ the effect is the same as passing the address
+ of a default condition variable attributes object.
+ Upon successful initialisation,
+ the state of the condition variable becomes initialised.
+ .PP
+ Attempting to initialise an already initialised
+ condition variable
+ results in undefined behaviour.
+ .PP
+ The function
+ \fIpthread_cond_destroy()\fR
+ destroys the given condition variable specified by
+ \fIcond\fR;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_cond_destroy()\fR
+ to set the object referenced by
+ \fIcond\fR
+ to an invalid value.
+ A destroyed condition variable object
+ can be re-initialised using
+ \fIpthread_cond_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ It is safe to destroy an initialised condition variable
+ upon which no threads are currently blocked.
+ Attempting to destroy a condition variable
+ upon which other threads are currently blocked
+ results in undefined behaviour.
+ .PP
+ In cases where default condition variable attributes are appropriate,
+ the macro PTHREAD_COND_INITIALIZER
+ can be used to initialise condition variables that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_cond_init()\fR
+ with parameter
+ \fIattr\fR
+ specified as NULL, except that no error checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_cond_init()\fR
+ and
+ \fIpthread_cond_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL]
+ error checks, if implemented,
+ act as if they were performed immediately
+ at the beginning of processing for the function
+ and caused an error return
+ prior to modifying the state of the condition variable specified by
+ \fIcond\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other
+ than memory) to initialise another condition variable.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the condition variable.
+ .PP
+ The
+ \fIpthread_cond_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ \fIcond\fR,
+ a previously initialised, but
+ not yet destroyed, condition variable.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_cond_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ \fIcond\fR
+ while it is referenced
+ (for example, while being used in a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR)
+ by another thread.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIcond\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_signal()\fR,
+ \fIpthread_cond_broadcast()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_signal,\fR \fBpthread_cond_broadcast\fR \- signal or broadcast a
+ condition
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_signal\fR\|(pthread_cond_t *\fIcond\fR);
+ int \fIpthread_cond_broadcast\fR\|(pthread_cond_t *\fIcond\fR);
+ .SH "DESCRIPTION"
+ These two functions are used to unblock
+ threads blocked on a condition variable.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ call unblocks at least one of the threads that are blocked on the
+ specified condition variable
+ \fIcond\fR
+ (if any threads are blocked on
+ \fIcond\fR).
+ .PP
+ The
+ \fIpthread_cond_broadcast()\fR
+ call unblocks all threads currently blocked on the specified condition variable
+ \fIcond\fR.
+ .PP
+ If more than one thread is blocked on a condition variable,
+ the scheduling policy determines the order in which threads are unblocked.
+ When each thread unblocked as a result of a
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ returns from its call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ the thread owns the mutex with which it called
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR.
+ The \fIthread\fR\|(s) that are unblocked contend for the mutex
+ according to the scheduling policy (if applicable),
+ and as if each had called
+ \fIpthread_mutex_lock()\fR.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ functions may be called by a thread whether or not it
+ currently owns the mutex that threads calling
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ have associated with the condition variable during their waits;
+ however, if predictable scheduling behaviour is required,
+ then that mutex is locked by the thread calling
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR.
+ .PP
+ The
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ functions have no effect if there are no threads
+ currently blocked on
+ \fIcond\fR.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_signal()\fR
+ and
+ \fIpthread_cond_broadcast()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value
+ \fIcond\fR
+ does not refer to an initialised condition variable.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_init()\fR,
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_wait,\fR \fBpthread_cond_timedwait\fR \- wait on a condition
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_wait\fR\|(pthread_cond_t *\fIcond\fR, pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_cond_timedwait\fR\|(pthread_cond_t *\fIcond\fR,
+ pthread_mutex_t *\fImutex\fR, const struct timespec *\fIabstime\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_cond_wait()\fR
+ and
+ \fIpthread_cond_timedwait()\fR
+ functions are used to block on a condition variable.
+ They are called with
+ \fImutex\fR
+ locked by the calling thread or undefined behaviour will result.
+ .PP
+ These functions atomically release
+ \fImutex\fR
+ and cause the calling thread to block on the condition variable
+ \fIcond\fR;
+ atomically here means &quot;atomically with respect to access by another
+ thread to the mutex and then the condition variable&quot;.
+ That is, if another thread is able to acquire the mutex
+ after the about-to-block thread has released it,
+ then a subsequent call to
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ in that thread behaves as if it were issued
+ after the about-to-block thread has blocked.
+ .PP
+ Upon successful return, the mutex has been
+ locked and is owned by the calling thread.
+ .PP
+ When using condition variables there is always a boolean predicate involving
+ shared variables associated with each condition wait that is true if the thread
+ should proceed.
+ Spurious wakeups from the
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ functions may occur.
+ Since the return from
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ does not imply anything about the value of this predicate,
+ the predicate should be re-evaluated upon such return.
+ .PP
+ The effect of using more than one mutex for concurrent
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ operations on the same condition variable is
+ undefined; that is, a condition variable becomes bound to a unique mutex
+ when a thread
+ waits on the condition variable,
+ and this (dynamic) binding ends when the wait returns.
+ .PP
+ A condition wait (whether timed or not) is a cancellation point.
+ When the cancelability enable state of a thread is set to
+ PTHREAD_CANCEL_DEFERRED,
+ a side effect of acting upon a cancellation request
+ while in a condition wait is that the mutex is (in effect) re-acquired
+ before calling the first cancellation cleanup handler.
+ The effect is as if the thread were unblocked,
+ allowed to execute up to the point of returning from the
+ call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ but at that point
+ notices the cancellation request and instead of returning to the caller
+ of
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ starts the thread cancellation activities, which includes calling
+ cancellation cleanup handlers.
+ .PP
+ A thread that has been unblocked because it has been
+ canceled while blocked in a call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ does not consume any condition signal that may be
+ directed concurrently at the
+ condition variable if there are other threads blocked on
+ the condition variable.
+ .PP
+ The
+ \fIpthread_cond_timedwait()\fR
+ function is the same as
+ \fIpthread_cond_wait()\fR
+ except that
+ an error is returned
+ if the absolute time specified by
+ \fIabstime\fR
+ passes (that is, system time equals or exceeds
+ \fIabstime\fR)
+ before the condition
+ \fIcond\fR
+ is signaled or broadcasted,
+ or if the absolute time specified by
+ \fIabstime\fR
+ has already been passed at the time of the call.
+ When such time-outs occur,
+ \fIpthread_cond_timedwait()\fR
+ will nonetheless release
+ and reacquire the mutex referenced by
+ \fImutex\fR.
+ The function
+ \fIpthread_cond_timedwait()\fR
+ is also a cancellation point.
+ .PP
+ If a signal is delivered to a thread waiting for a condition variable,
+ upon return from the signal handler
+ the thread resumes waiting for the condition variable
+ as if it was not interrupted,
+ or it returns zero due to spurious wakeup.
+ .SH "RETURN VALUE"
+ Except in the case of [ETIMEDOUT],
+ all these error checks act as if they were performed immediately
+ at the beginning of processing for the function
+ and cause an error return,
+ in effect, prior to modifying the state of the mutex specified by
+ \fImutex\fR
+ or the condition variable specified by
+ \fIcond\fR.
+ .PP
+ Upon successful completion, a value of zero is returned.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_timedwait()\fR
+ function will fail if:
+ .Ip "[\s-1ETIMEDOUT\s0]" 4
+ The time specified by
+ \fIabstime\fR
+ to
+ \fIpthread_cond_timedwait()\fR
+ has passed.
+ .PP
+ The
+ \fIpthread_cond_wait()\fR
+ and
+ \fIpthread_cond_timedwait()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIcond\fR,
+ \fImutex\fR,
+ or
+ \fIabstime\fR
+ is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ Different mutexes were supplied for concurrent
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ operations on the same condition variable.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The mutex was not owned by the current thread at the time of the call.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_signal()\fR,
+ \fIpthread_cond_broadcast()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_cond_wait,\fR \fBpthread_cond_timedwait\fR \- wait on a condition
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_cond_wait\fR\|(pthread_cond_t *\fIcond\fR, pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_cond_timedwait\fR\|(pthread_cond_t *\fIcond\fR,
+ pthread_mutex_t *\fImutex\fR, const struct timespec *\fIabstime\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_cond_wait()\fR
+ and
+ \fIpthread_cond_timedwait()\fR
+ functions are used to block on a condition variable.
+ They are called with
+ \fImutex\fR
+ locked by the calling thread or undefined behaviour will result.
+ .PP
+ These functions atomically release
+ \fImutex\fR
+ and cause the calling thread to block on the condition variable
+ \fIcond\fR;
+ atomically here means &quot;atomically with respect to access by another
+ thread to the mutex and then the condition variable&quot;.
+ That is, if another thread is able to acquire the mutex
+ after the about-to-block thread has released it,
+ then a subsequent call to
+ \fIpthread_cond_signal()\fR
+ or
+ \fIpthread_cond_broadcast()\fR
+ in that thread behaves as if it were issued
+ after the about-to-block thread has blocked.
+ .PP
+ Upon successful return, the mutex has been
+ locked and is owned by the calling thread.
+ .PP
+ When using condition variables there is always a boolean predicate involving
+ shared variables associated with each condition wait that is true if the thread
+ should proceed.
+ Spurious wakeups from the
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ functions may occur.
+ Since the return from
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ does not imply anything about the value of this predicate,
+ the predicate should be re-evaluated upon such return.
+ .PP
+ The effect of using more than one mutex for concurrent
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ operations on the same condition variable is
+ undefined; that is, a condition variable becomes bound to a unique mutex
+ when a thread
+ waits on the condition variable,
+ and this (dynamic) binding ends when the wait returns.
+ .PP
+ A condition wait (whether timed or not) is a cancellation point.
+ When the cancelability enable state of a thread is set to
+ PTHREAD_CANCEL_DEFERRED,
+ a side effect of acting upon a cancellation request
+ while in a condition wait is that the mutex is (in effect) re-acquired
+ before calling the first cancellation cleanup handler.
+ The effect is as if the thread were unblocked,
+ allowed to execute up to the point of returning from the
+ call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ but at that point
+ notices the cancellation request and instead of returning to the caller
+ of
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR,
+ starts the thread cancellation activities, which includes calling
+ cancellation cleanup handlers.
+ .PP
+ A thread that has been unblocked because it has been
+ canceled while blocked in a call to
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ does not consume any condition signal that may be
+ directed concurrently at the
+ condition variable if there are other threads blocked on
+ the condition variable.
+ .PP
+ The
+ \fIpthread_cond_timedwait()\fR
+ function is the same as
+ \fIpthread_cond_wait()\fR
+ except that
+ an error is returned
+ if the absolute time specified by
+ \fIabstime\fR
+ passes (that is, system time equals or exceeds
+ \fIabstime\fR)
+ before the condition
+ \fIcond\fR
+ is signaled or broadcasted,
+ or if the absolute time specified by
+ \fIabstime\fR
+ has already been passed at the time of the call.
+ When such time-outs occur,
+ \fIpthread_cond_timedwait()\fR
+ will nonetheless release
+ and reacquire the mutex referenced by
+ \fImutex\fR.
+ The function
+ \fIpthread_cond_timedwait()\fR
+ is also a cancellation point.
+ .PP
+ If a signal is delivered to a thread waiting for a condition variable,
+ upon return from the signal handler
+ the thread resumes waiting for the condition variable
+ as if it was not interrupted,
+ or it returns zero due to spurious wakeup.
+ .SH "RETURN VALUE"
+ Except in the case of [ETIMEDOUT],
+ all these error checks act as if they were performed immediately
+ at the beginning of processing for the function
+ and cause an error return,
+ in effect, prior to modifying the state of the mutex specified by
+ \fImutex\fR
+ or the condition variable specified by
+ \fIcond\fR.
+ .PP
+ Upon successful completion, a value of zero is returned.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_cond_timedwait()\fR
+ function will fail if:
+ .Ip "[\s-1ETIMEDOUT\s0]" 4
+ The time specified by
+ \fIabstime\fR
+ to
+ \fIpthread_cond_timedwait()\fR
+ has passed.
+ .PP
+ The
+ \fIpthread_cond_wait()\fR
+ and
+ \fIpthread_cond_timedwait()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIcond\fR,
+ \fImutex\fR,
+ or
+ \fIabstime\fR
+ is invalid.
+ .Ip "[\s-1EINVAL\s0]" 4
+ Different mutexes were supplied for concurrent
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ operations on the same condition variable.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The mutex was not owned by the current thread at the time of the call.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_signal()\fR,
+ \fIpthread_cond_broadcast()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_condattr_init,\fR \fBpthread_condattr_destroy\fR
+ \- initialise and destroy condition variable attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_condattr_init\fR\|(pthread_condattr_t *\fIattr\fR);
+ int \fIpthread_condattr_destroy\fR\|(pthread_condattr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_condattr_init()\fR
+ initialises a condition variable attributes object
+ \fIattr\fR
+ with the default value for all of the attributes
+ defined by the implementation.
+ .PP
+ Attempting to initialise an already initialised
+ condition variable attributes object
+ results in undefined behaviour.
+ .PP
+ After a condition variable
+ attributes object has been used to initialise one or more
+ condition variables, any function affecting the attributes object (including
+ destruction) does not affect any previously initialised condition variables.
+ .PP
+ The
+ \fIpthread_condattr_destroy()\fR
+ function destroys a condition variable attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_condattr_destroy()\fR
+ to set the object referenced by
+ \fIattr\fR
+ to an invalid value.
+ A destroyed condition variable attributes object
+ can be re-initialised using
+ \fIpthread_condattr_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ Additional attributes, their default values, and the names
+ of the associated functions to get and set those attribute values are
+ implementation-dependent.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_condattr_init()\fR
+ and
+ \fIpthread_condattr_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_condattr_init()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the condition variable
+ attributes object.
+ .PP
+ The
+ \fIpthread_condattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_condattr_getpshared()\fR,
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_condattr_getpshared,\fR \fBpthread_condattr_setpshared\fR
+ \- get and set the process-shared condition variable attributes
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_condattr_getpshared\fR\|(const pthread_condattr_t *\fIattr\fR,
+ int *\fIpshared\fR);
+ int \fIpthread_condattr_setpshared\fR\|(pthread_condattr_t *\fIattr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_condattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the attributes object referenced by
+ \fIattr\fR.
+ The
+ \fIpthread_condattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by
+ \fIattr\fR.
+ .PP
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED
+ to permit a condition variable
+ to be operated upon by any thread that has access to the memory
+ where the condition variable
+ is allocated, even if the condition variable
+ is allocated in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the condition variable
+ will only be operated upon by threads created
+ within the same process as the
+ thread that initialised the condition variable;
+ if threads of differing processes
+ attempt to operate on such a condition variable, the behaviour is
+ undefined.  The default value of the attribute is
+ PTHREAD_PROCESS_PRIVATE.
+ .PP
+ Additional attributes, their default values, and the names
+ of the associated functions to get and set those attribute values are
+ implementation-dependent.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_condattr_setpshared()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ If successful, the
+ \fIpthread_condattr_getpshared()\fR
+ function returns zero
+ and stores the value of the
+ \fIprocess-shared\fR
+ attribute of
+ \fIattr\fR
+ into the object referenced by the
+ \fIpshared\fR
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_condattr_getpshared()\fR
+ and
+ \fIpthread_condattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_condattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_condattr_init()\fR,
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_condattr_init,\fR \fBpthread_condattr_destroy\fR
+ \- initialise and destroy condition variable attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_condattr_init\fR\|(pthread_condattr_t *\fIattr\fR);
+ int \fIpthread_condattr_destroy\fR\|(pthread_condattr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_condattr_init()\fR
+ initialises a condition variable attributes object
+ \fIattr\fR
+ with the default value for all of the attributes
+ defined by the implementation.
+ .PP
+ Attempting to initialise an already initialised
+ condition variable attributes object
+ results in undefined behaviour.
+ .PP
+ After a condition variable
+ attributes object has been used to initialise one or more
+ condition variables, any function affecting the attributes object (including
+ destruction) does not affect any previously initialised condition variables.
+ .PP
+ The
+ \fIpthread_condattr_destroy()\fR
+ function destroys a condition variable attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_condattr_destroy()\fR
+ to set the object referenced by
+ \fIattr\fR
+ to an invalid value.
+ A destroyed condition variable attributes object
+ can be re-initialised using
+ \fIpthread_condattr_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ Additional attributes, their default values, and the names
+ of the associated functions to get and set those attribute values are
+ implementation-dependent.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_condattr_init()\fR
+ and
+ \fIpthread_condattr_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_condattr_init()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the condition variable
+ attributes object.
+ .PP
+ The
+ \fIpthread_condattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_condattr_getpshared()\fR,
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_condattr_getpshared,\fR \fBpthread_condattr_setpshared\fR
+ \- get and set the process-shared condition variable attributes
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_condattr_getpshared\fR\|(const pthread_condattr_t *\fIattr\fR,
+ int *\fIpshared\fR);
+ int \fIpthread_condattr_setpshared\fR\|(pthread_condattr_t *\fIattr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_condattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the attributes object referenced by
+ \fIattr\fR.
+ The
+ \fIpthread_condattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by
+ \fIattr\fR.
+ .PP
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED
+ to permit a condition variable
+ to be operated upon by any thread that has access to the memory
+ where the condition variable
+ is allocated, even if the condition variable
+ is allocated in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the condition variable
+ will only be operated upon by threads created
+ within the same process as the
+ thread that initialised the condition variable;
+ if threads of differing processes
+ attempt to operate on such a condition variable, the behaviour is
+ undefined.  The default value of the attribute is
+ PTHREAD_PROCESS_PRIVATE.
+ .PP
+ Additional attributes, their default values, and the names
+ of the associated functions to get and set those attribute values are
+ implementation-dependent.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_condattr_setpshared()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ If successful, the
+ \fIpthread_condattr_getpshared()\fR
+ function returns zero
+ and stores the value of the
+ \fIprocess-shared\fR
+ attribute of
+ \fIattr\fR
+ into the object referenced by the
+ \fIpshared\fR
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_condattr_getpshared()\fR
+ and
+ \fIpthread_condattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_condattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_condattr_init()\fR,
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_create\fR \- thread creation
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_create\fR\|(pthread_t *\fIthread\fR, const pthread_attr_t *\fIattr\fR,
+ void *(*\fIstart_routine\fR)(void*), void *\fIarg\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_create()\fR
+ function is used to create a new thread, with attributes specified by
+ \fIattr\fR,
+ within a process.
+ If
+ \fIattr\fR
+ is NULL,
+ the default attributes are used.
+ If the attributes specified by
+ \fIattr\fR
+ are modified later, the thread's attributes are not affected.
+ Upon successful completion,
+ \fIpthread_create()\fR
+ stores the ID of the created thread in the location referenced by
+ \fIthread\fR.
+ .PP
+ The thread is created executing
+ \fIstart_routine\fR
+ with
+ \fIarg\fR
+ as its sole argument.
+ If the
+ \fIstart_routine\fR
+ returns, the effect is as if there was an implicit call to
+ \fIpthread_exit()\fR
+ using the return value of
+ \fIstart_routine\fR
+ as the exit status.
+ Note that the thread in which
+ \fImain()\fR
+ was originally invoked differs from this.
+ When it returns from
+ \fImain()\fR,
+ the effect is as if there was an implicit call to
+ \fIexit()\fR
+ using the return value of
+ \fImain()\fR
+ as the exit status.
+ .PP
+ The signal state of the new thread is initialised as follows:
+ .Ip "o" 4
+ The signal mask is inherited from the creating thread.
+ .Ip "o" 4
+ The set of signals pending for the new thread is empty.
+ .PP
+ If
+ \fIpthread_create()\fR
+ fails, no new thread is created
+ and the contents of the location referenced by
+ \fIthread\fR
+ are undefined.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_create()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_create()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources to create another thread,
+ or the system-imposed limit on the total number of threads
+ in a process \s-1PTHREAD_THREADS_MAX\s0 would be exceeded.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have appropriate permission to set the required
+ scheduling parameters or scheduling policy.
+ .PP
+ The
+ \fIpthread_create()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_exit()\fR,
+ \fIpthread_join()\fR,
+ \fIfork()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_detach\fR \- detach a thread
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_detach\fR\|(pthread_t \fIthread\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_detach()\fR
+ function is used to indicate to the implementation that storage
+ for the thread
+ \fIthread\fR
+ can be reclaimed when that thread terminates.
+ If
+ \fIthread\fR
+ has not terminated,
+ \fIpthread_detach()\fR
+ will not cause it to terminate.
+ The effect of multiple
+ \fIpthread_detach()\fR
+ calls on the same target thread is unspecified.
+ .SH "RETURN VALUE"
+ If the call succeeds,
+ \fIpthread_detach()\fR
+ returns 0.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_detach()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The implementation has detected that the value specified by
+ \fIthread\fR
+ does not refer to a joinable thread.
+ .Ip "[\s-1ESRCH\s0]" 4
+ No thread could be found corresponding to that specified
+ by the given thread \s-1ID\s0.
+ .PP
+ The
+ \fIpthread_detach()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_join()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_equal\fR \- compare thread IDs
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_equal\fR\|(pthread_t \fIt1\fR, pthread_t \fIt2\fR);
+ .SH "DESCRIPTION"
+ This function compares the thread IDs
+ \fIt1\fR
+ and
+ \fIt2\fR.
+ .SH "RETURN VALUE"
+ The
+ \fIpthread_equal()\fR
+ function returns a non-zero value if
+ \fIt1\fR
+ and
+ \fIt2\fR
+ are equal;
+ otherwise, zero is returned.
+ .PP
+ If either
+ \fIt1\fR
+ or
+ \fIt2\fR
+ are not valid thread IDs, the behaviour is undefined.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ The
+ \fIpthread_equal()\fR
+ function will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_self()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_exit\fR \- thread termination
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ void \fIpthread_exit\fR\|(void *\fIvalue_ptr\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_exit()\fR
+ function terminates the calling thread and makes the value
+ \fIvalue_ptr\fR
+ available to any successful join with the terminating thread.
+ Any cancellation cleanup handlers
+ that have been pushed and not yet popped are popped in the reverse order
+ that they were pushed and then executed.
+ After all cancellation cleanup handlers have been executed,
+ if the thread has any thread-specific data,
+ appropriate destructor functions will be called in an unspecified order.
+ Thread termination does not release any application visible process resources,
+ including, but not limited to, mutexes and file descriptors,
+ nor does it perform any process level cleanup actions,
+ including, but not limited to, calling any
+ \fIatexit()\fR
+ routines that may exist.
+ .PP
+ An implicit call to
+ \fIpthread_exit()\fR
+ is made when a thread other than the thread in which
+ \fImain()\fR
+ was first invoked returns from the start routine
+ that was used to create it.
+ The function's return value serves as the thread's exit status.
+ .PP
+ The behaviour of
+ \fIpthread_exit()\fR
+ is undefined if called from a
+ cancellation cleanup handler
+ or destructor function
+ that was invoked as a result of either an implicit or
+ explicit call to
+ \fIpthread_exit()\fR.
+ .PP
+ After a thread has terminated,
+ the result of access to local (auto) variables of the thread is undefined.
+ Thus, references to local variables of the exiting thread
+ should not be used for the
+ \fIpthread_exit()\fR
+ \fIvalue_ptr\fR
+ parameter value.
+ .PP
+ The process exits with an exit status of 0 after the
+ last thread has been terminated.
+ The behaviour is as if the implementation called
+ \fIexit()\fR
+ with a zero argument at thread termination time.
+ .SH "RETURN VALUE"
+ The
+ \fIpthread_exit()\fR
+ function cannot return to its caller.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ The
+ \fIpthread_exit()\fR
+ function will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_join()\fR,
+ \fIexit()\fR,
+ \fI_exit()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_getconcurrency,\fR \fBpthread_setconcurrency\fR \-
+ get or set level of concurrency
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_getconcurrency\fR\|(void);
+ int \fIpthread_setconcurrency\fR\|(int \fInew_level\fR);
+ .SH "DESCRIPTION"
+ Unbound threads in a process may or may not be required to be
+ simultaneously active. By default, the threads
+ implementation ensures that a sufficient number of threads are active
+ so that the process can continue to make
+ progress. While this conserves system resources, it may not produce
+ the most effective level of concurrency.
+ .PP
+ The
+ \fIpthread_setconcurrency()\fR
+ function allows an application to inform
+ the threads implementation of its desired concurrency level,
+ \fInew_level\fR.
+ The actual level of concurrency provided by the implementation as a
+ result of this function call is unspecified.
+ .PP
+ If \fInew_level\fR is zero, it causes the implementation to maintain
+ the concurrency level at its discretion as if
+ \fIpthread_setconcurrency()\fR
+ was never called.
+ .PP
+ The
+ \fIpthread_getconcurrency()\fR
+ function returns the
+ value set by a previous call to the
+ \fIpthread_setconcurrency()\fR
+ function.  If the
+ \fIpthread_setconcurrency()\fR
+ function was not previously called,
+ this function returns zero to indicate that the implementation
+ is maintaining the concurrency level.
+ .PP
+ When an application calls
+ \fIpthread_setconcurrency()\fR
+ it is
+ informing the implementation of its desired
+ concurrency level. The implementation uses this as a hint,
+ not a requirement.
+ .PP
+ If an implementation does not support multiplexing of user threads
+ on top of several kernel scheduled entities,
+ the
+ \fIpthread_setconcurrency()\fR
+ and
+ \fIpthread_getconcurrency()\fR
+ functions
+ will be provided for source code
+ compatibility but they will have no effect when called. To maintain
+ the function semantics, the \fInew_level\fR
+ parameter will be saved when
+ \fIpthread_setconcurrency()\fR
+ is called so
+ that a subsequent call to
+ \fIpthread_getconcurrency()\fR
+ returns the same value.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_setconcurrency()\fR
+ function returns zero.  Otherwise, an error number is returned
+ to indicate the error.
+ .PP
+ The
+ \fIpthread_getconcurrency()\fR
+ function always returns the concurrency level set by a previous call to
+ \fIpthread_setconcurrency()\fR.
+ If the
+ \fIpthread_setconcurrency()\fR
+ function has never been called,
+ \fIpthread_getconcurrency()\fR
+ returns zero.
+ .SH "ERRORS"
+ The
+ \fIpthread_setconcurrency()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fInew_level\fR is negative.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The value specific by \fInew_level\fR would cause a system resource
+ to be exceeded.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Use of these functions changes the state of the underlying
+ concurrency upon which the application depends. Library
+ developers are advised to not use the
+ \fIpthread_getconcurrency()\fR
+ and
+ \fIpthread_setconcurrency()\fR
+ functions since their
+ use may conflict with an applications use of these functions.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_getschedparam,\fR \fBpthread_setschedparam\fR
+ \- dynamic thread scheduling parameters access
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_getschedparam\fR\|(pthread_t \fIthread\fR, int *\fIpolicy\fR,
+ struct sched_param *\fIparam\fR);
+ int \fIpthread_setschedparam\fR\|(pthread_t \fIthread\fR, int \fIpolicy\fR,
+ const struct sched_param *\fIparam\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ allow the scheduling policy and scheduling parameters of individual threads
+ within a multi-threaded process to be retrieved and set.
+ For SCHED_FIFO and SCHED_RR,
+ the only required member of the
+ \fBsched_param\fR
+ structure is the priority
+ \fIsched_priority\fR.
+ For SCHED_OTHER,
+ the affected scheduling parameters are implementation-dependent.
+ .PP
+ The
+ \fIpthread_getschedparam()\fR
+ function retrieves the scheduling policy and scheduling parameters
+ for the thread whose thread ID is given by
+ \fIthread\fR
+ and stores those values in
+ \fIpolicy\fR
+ and
+ \fIparam\fR,
+ respectively.
+ The priority value returned from
+ \fIpthread_getschedparam()\fR
+ is the value specified by the most recent
+ \fIpthread_setschedparam()\fR
+ or
+ \fIpthread_create()\fR
+ call affecting the target thread,
+ and reflects any temporary adjustments to its priority
+ as a result of any priority inheritance or ceiling functions.
+ The
+ \fIpthread_setschedparam()\fR
+ function sets the scheduling policy
+ and associated scheduling parameters for the thread whose
+ thread ID is given by
+ \fIthread\fR
+ to the policy and associated parameters provided in
+ \fIpolicy\fR
+ and
+ \fIparam\fR,
+ respectively.
+ .PP
+ The
+ \fIpolicy\fR
+ parameter may have the value SCHED_OTHER,
+ that has implementation-dependent scheduling parameters,
+ SCHED_FIFO or SCHED_RR,
+ that have the single scheduling parameter,
+ \fIpriority.\fR
+ .PP
+ If the
+ \fIpthread_setschedparam()\fR
+ function fails, no scheduling parameters will be changed
+ for the target thread.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_getschedparam()\fR
+ function may fail if:
+ .Ip "[\s-1ESRCH\s0]" 4
+ The value specified by
+ \fIthread\fR
+ does not refer to a existing thread.
+ .PP
+ The
+ \fIpthread_setschedparam()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIpolicy\fR
+ or one of the scheduling parameters associated with
+ the scheduling policy
+ \fIpolicy\fR
+ is invalid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the policy or scheduling parameters to
+ an unsupported value.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the appropriate permission to set
+ either the scheduling parameters or the scheduling policy of the
+ specified thread.
+ .Ip "[\s-1EPERM\s0]" 4
+ The implementation does not allow the application to modify
+ one of the parameters to the value specified.
+ .Ip "[\s-1ESRCH\s0]" 4
+ The value specified by
+ \fIthread\fR
+ does not refer to a existing thread.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIsched_setparam()\fR,
+ \fIsched_getparam()\fR,
+ \fIsched_setscheduler()\fR,
+ \fIsched_getscheduler()\fR,
+ \fI<pthread.h\fR>,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setspecific,\fR \fBpthread_getspecific\fR \- thread-specific data management
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setspecific\fR\|(pthread_key_t \fIkey\fR, const void *\fIvalue\fR);
+ void *\fIpthread_getspecific\fR\|(pthread_key_t \fIkey\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_setspecific()\fR
+ function associates a thread-specific
+ \fIvalue\fR
+ with a
+ \fIkey\fR
+ obtained via a previous call to
+ \fIpthread_key_create()\fR.
+ Different threads may bind different values to the same key.
+ These values are typically pointers to blocks of dynamically allocated memory
+ that have been reserved for use by the calling thread.
+ .PP
+ The
+ \fIpthread_getspecific()\fR
+ function returns the value currently bound to the specified
+ \fIkey\fR
+ on behalf of the calling thread.
+ .PP
+ The effect of calling
+ \fIpthread_setspecific()\fR
+ or
+ \fIpthread_getspecific()\fR
+ with a
+ \fIkey\fR
+ value not obtained from
+ \fIpthread_key_create()\fR
+ or after
+ \fIkey\fR
+ has been deleted with
+ \fIpthread_key_delete()\fR
+ is undefined.
+ .PP
+ Both
+ \fIpthread_setspecific()\fR
+ and
+ \fIpthread_getspecific()\fR
+ may be called from a thread-specific data destructor function.
+ However, calling
+ \fIpthread_setspecific()\fR
+ from a destructor may result in lost storage or infinite loops.
+ .PP
+ Both functions may be implemented as macros.
+ .SH "RETURN VALUE"
+ The function
+ \fIpthread_getspecific()\fR
+ returns the thread-specific data value
+ associated with the given
+ \fIkey\fR.
+ If no thread-specific data value is associated with
+ \fIkey\fR,
+ then the value NULL is returned.
+ .PP
+ If successful, the
+ \fIpthread_setspecific()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_setspecific()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to associate the value with the key.
+ .PP
+ The
+ \fIpthread_setspecific()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The key value is invalid.
+ .PP
+ No errors are returned from
+ \fIpthread_getspecific()\fR.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_key_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_join\fR \- wait for thread termination
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_join\fR\|(pthread_t \fIthread\fR, void **\fIvalue_ptr\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_join()\fR
+ function suspends execution of the calling thread until the target
+ \fIthread\fR
+ terminates, unless the target
+ \fIthread\fR
+ has already terminated.
+ On return from a successful
+ \fIpthread_join()\fR
+ call with a non-NULL
+ \fIvalue_ptr\fR
+ argument, the value passed to
+ \fIpthread_exit()\fR
+ by the terminating thread is made available in the location referenced by
+ \fIvalue_ptr\fR.
+ When a
+ \fIpthread_join()\fR
+ returns successfully, the target thread has been terminated.
+ The results of multiple simultaneous calls to
+ \fIpthread_join()\fR
+ specifying the same target thread are undefined.
+ If the thread calling
+ \fIpthread_join()\fR
+ is canceled, then the target thread will not be detached.
+ .PP
+ It is unspecified whether a thread that has exited but remains unjoined
+ counts against _POSIX_THREAD_THREADS_MAX.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_join()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_join()\fR
+ function will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The implementation has detected that the value specified by
+ \fIthread\fR
+ does not refer to a joinable thread.
+ .Ip "[\s-1ESRCH\s0]" 4
+ No thread could be found corresponding to that specified
+ by the given thread \s-1ID\s0.
+ .PP
+ The
+ \fIpthread_join()\fR
+ function may fail if:
+ .Ip "[\s-1EDEADLK\s0]" 4
+ A deadlock was detected or
+ the value of
+ \fIthread\fR
+ specifies the calling thread.
+ .PP
+ The
+ \fIpthread_join()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_key_create\fR \- thread-specific data key creation
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_key_create\fR\|(pthread_key_t *\fIkey\fR, void (*\fIdestructor\fR)(void*));
+ .SH "DESCRIPTION"
+ This function creates a thread-specific data
+ key visible to all threads in the process.
+ Key values provided by
+ \fIpthread_key_create()\fR
+ are opaque objects used to locate thread-specific data.
+ Although the same key value may be used by different threads,
+ the values bound to the key by
+ \fIpthread_setspecific()\fR
+ are maintained on a per-thread basis and persist
+ for the life of the calling thread.
+ .PP
+ Upon key creation,
+ the value NULL is associated with the new key in all active threads.
+ Upon thread creation,
+ the value NULL is associated with all defined keys in the new thread.
+ .PP
+ An optional destructor function may be associated with
+ each key value.
+ At thread exit, if a key value has a non-NULL destructor pointer,
+ and the thread has a non-NULL value associated with that key,
+ the function pointed to is called with the current associated value
+ as its sole argument.
+ The order of destructor calls is unspecified
+ if more than one destructor exists for a thread when it exits.
+ .PP
+ If, after all the destructors have been called for all non-NULL values
+ with associated destructors,
+ there are still some non-NULL values with associated destructors,
+ then the process will be repeated.
+ If, after at least PTHREAD_DESTRUCTOR_ITERATIONS
+ iterations of destructor calls for outstanding non-NULL values,
+ there are still some non-NULL values with associated destructors,
+ implementations may stop calling destructors,
+ or they may continue calling destructors
+ until no non-NULL values with associated destructors exist,
+ even though this might result in an infinite loop.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_key_create()\fR
+ function stores the newly created key value at
+ \fI*key\fR
+ and returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_key_create()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources to create another thread-specific
+ data key, or the system-imposed limit on the total number of keys per process
+ \s-1PTHREAD_KEYS_MAX\s0 has been exceeded.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to create the key.
+ .PP
+ The
+ \fIpthread_key_create()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_getspecific()\fR,
+ \fIpthread_setspecific()\fR,
+ \fIpthread_key_delete()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_key_delete\fR \- thread-specific data key deletion
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_key_delete\fR\|(pthread_key_t \fIkey\fR);
+ .SH "DESCRIPTION"
+ This function deletes a thread-specific data
+ key previously returned by
+ \fIpthread_key_create()\fR.
+ The thread-specific data values associated with
+ \fIkey\fR
+ need not be NULL at the time
+ \fIpthread_key_delete()\fR
+ is called.
+ It is the responsibility of the application
+ to free any application storage
+ or perform any cleanup actions for data structures
+ related to the deleted key or associated thread-specific data
+ in any threads;
+ this cleanup can be done either before or after
+ \fIpthread_key_delete()\fR
+ is called.
+ Any attempt to use
+ \fIkey\fR
+ following the call to
+ \fIpthread_key_delete()\fR
+ results in undefined behaviour.
+ .PP
+ The
+ \fIpthread_key_delete()\fR
+ function is callable from within destructor functions.
+ No destructor functions will be invoked by
+ \fIpthread_key_delete()\fR.
+ Any destructor function that may have been associated with
+ \fIkey\fR
+ will no longer be called upon thread exit.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_key_delete()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_key_delete()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The
+ \fIkey\fR
+ value is invalid.
+ .PP
+ The
+ \fIpthread_key_delete()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_key_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_kill\fR \- send a signal to a thread
+ .SH "SYNOPSIS"
+ #include <signal.h>
+ .PP
+ int \fIpthread_kill\fR\|(pthread_t \fIthread\fR, int \fIsig\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_kill()\fR
+ function is used to request that a signal be delivered to the specified thread.
+ .PP
+ As in
+ \fIkill()\fR,
+ if
+ \fIsig\fR
+ is zero, error checking is performed but no signal is actually sent.
+ .SH "RETURN VALUE"
+ Upon successful completion, the function returns a value of zero.
+ Otherwise the function returns an error number.
+ If the
+ \fIpthread_kill()\fR
+ function fails, no signal is sent.
+ .SH "ERRORS"
+ The
+ \fIpthread_kill()\fR
+ function will fail if:
+ .Ip "[\s-1ESRCH\s0]" 4
+ No thread could be found corresponding to that specified
+ by the given thread \s-1ID\s0.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value of the
+ \fIsig\fR
+ argument is an invalid or unsupported signal number.
+ .PP
+ The
+ \fIpthread_kill()\fR
+ function will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIkill()\fR,
+ \fIpthread_self()\fR,
+ \fIraise()\fR,
+ \fI<signal.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_init,\fR \fBpthread_mutex_destroy\fR \- initialise or destroy a mutex
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_init\fR\|(pthread_mutex_t *\fImutex\fR,
+ const pthread_mutexattr_t *\fIattr\fR);
+ int \fIpthread_mutex_destroy\fR\|(pthread_mutex_t *\fImutex\fR);
+ pthread_mutex_t \fImutex\fR = PTHREAD_MUTEX_INITIALIZER;
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutex_init()\fR
+ function initialises the mutex referenced by
+ \fImutex\fR
+ with attributes specified
+ by
+ \fIattr\fR.
+ If
+ \fIattr\fR
+ is NULL,
+ the default mutex attributes are used; the effect is the same as
+ passing the address of a default mutex attributes object.
+ Upon successful initialisation, the state of the mutex becomes
+ initialised and unlocked.
+ .PP
+ Attempting to initialise an already initialised
+ mutex results in
+ undefined behaviour.
+ .PP
+ The
+ \fIpthread_mutex_destroy()\fR
+ function destroys the mutex object referenced by
+ \fImutex\fR;
+ the mutex object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_mutex_destroy()\fR
+ to set the object referenced by
+ \fImutex\fR
+ to an invalid value.
+ A destroyed mutex object
+ can be re-initialised using
+ \fIpthread_mutex_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ It is safe to destroy an initialised mutex that is unlocked.
+ Attempting to destroy a locked mutex results in
+ undefined behaviour.
+ .PP
+ In cases where default mutex attributes are appropriate,
+ the macro PTHREAD_MUTEX_INITIALIZER
+ can be used to initialise mutexes that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_mutex_init()\fR
+ with parameter
+ \fIattr\fR
+ specified as NULL,
+ except that no error checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_init()\fR
+ and
+ \fIpthread_mutex_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL] error checks, if implemented,
+ act as if they were performed immediately
+ at the beginning of processing for the function
+ and cause an error return
+ prior to modifying the state of the mutex specified by
+ \fImutex\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other than memory)
+ to initialise another mutex.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the mutex.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .PP
+ The
+ \fIpthread_mutex_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ \fImutex\fR,
+ a previously initialised, but
+ not yet destroyed, mutex.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_mutex_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ \fImutex\fR
+ while it is locked or referenced
+ (for example, while being used in a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR)
+ by another thread.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_getprioceiling()\fR,
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_unlock()\fR,
+ \fIpthread_mutex_setprioceiling()\fR,
+ \fIpthread_mutex_trylock()\fR,
+ \fIpthread_mutexattr_getpshared()\fR,
+ \fIpthread_mutexattr_setpshared()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_setprioceiling,\fR \fBpthread_mutex_getprioceiling\fR
+ \- change the priority ceiling of a mutex
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_setprioceiling\fR\|(pthread_mutex_t *\fImutex\fR, int \fIprioceiling\fR, int *\fIold_ceiling\fR);
+ .PP
+ int \fIpthread_mutex_getprioceiling\fR\|(const pthread_mutex_t *\fImutex\fR, int *\fIprioceiling\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutex_getprioceiling()\fR
+ function returns the current priority ceiling of the mutex.
+ .PP
+ The
+ \fIpthread_mutex_setprioceiling()\fR
+ function either locks the mutex if it is unlocked, or blocks until it can
+ successfully lock the mutex, then it
+ changes the mutex's priority ceiling and releases the mutex.
+ When the change is successful, the previous value of the
+ priority ceiling is returned in
+ \fIold_ceiling\fR.
+ The process of locking the mutex need not adhere
+ to the priority protect protocol.
+ .PP
+ If the
+ \fIpthread_mutex_setprioceiling()\fR
+ function fails, the mutex priority ceiling is not changed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_setprioceiling()\fR
+ and
+ \fIpthread_mutex_getprioceiling()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_getprioceiling()\fR
+ and
+ \fIpthread_mutex_setprioceiling()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and
+ the implementation does not support the function.
+ .PP
+ The
+ \fIpthread_mutex_setprioceiling()\fR
+ and
+ \fIpthread_mutex_getprioceiling()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The priority requested by
+ \fIprioceiling\fR
+ is out of range.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ does not refer to a currently existing mutex.
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The implementation does not support the priority ceiling protocol for mutexes.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_unlock()\fR,
+ \fIpthread_mutex_trylock()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_init,\fR \fBpthread_mutex_destroy\fR \- initialise or destroy a mutex
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_init\fR\|(pthread_mutex_t *\fImutex\fR,
+ const pthread_mutexattr_t *\fIattr\fR);
+ int \fIpthread_mutex_destroy\fR\|(pthread_mutex_t *\fImutex\fR);
+ pthread_mutex_t \fImutex\fR = PTHREAD_MUTEX_INITIALIZER;
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutex_init()\fR
+ function initialises the mutex referenced by
+ \fImutex\fR
+ with attributes specified
+ by
+ \fIattr\fR.
+ If
+ \fIattr\fR
+ is NULL,
+ the default mutex attributes are used; the effect is the same as
+ passing the address of a default mutex attributes object.
+ Upon successful initialisation, the state of the mutex becomes
+ initialised and unlocked.
+ .PP
+ Attempting to initialise an already initialised
+ mutex results in
+ undefined behaviour.
+ .PP
+ The
+ \fIpthread_mutex_destroy()\fR
+ function destroys the mutex object referenced by
+ \fImutex\fR;
+ the mutex object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_mutex_destroy()\fR
+ to set the object referenced by
+ \fImutex\fR
+ to an invalid value.
+ A destroyed mutex object
+ can be re-initialised using
+ \fIpthread_mutex_init()\fR;
+ the results of otherwise referencing the object after it has been destroyed
+ are undefined.
+ .PP
+ It is safe to destroy an initialised mutex that is unlocked.
+ Attempting to destroy a locked mutex results in
+ undefined behaviour.
+ .PP
+ In cases where default mutex attributes are appropriate,
+ the macro PTHREAD_MUTEX_INITIALIZER
+ can be used to initialise mutexes that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_mutex_init()\fR
+ with parameter
+ \fIattr\fR
+ specified as NULL,
+ except that no error checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_init()\fR
+ and
+ \fIpthread_mutex_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL] error checks, if implemented,
+ act as if they were performed immediately
+ at the beginning of processing for the function
+ and cause an error return
+ prior to modifying the state of the mutex specified by
+ \fImutex\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other than memory)
+ to initialise another mutex.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the mutex.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .PP
+ The
+ \fIpthread_mutex_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt
+ to re-initialise the object referenced by
+ \fImutex\fR,
+ a previously initialised, but
+ not yet destroyed, mutex.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_mutex_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy
+ the object referenced by
+ \fImutex\fR
+ while it is locked or referenced
+ (for example, while being used in a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR)
+ by another thread.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_getprioceiling()\fR,
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_unlock()\fR,
+ \fIpthread_mutex_setprioceiling()\fR,
+ \fIpthread_mutex_trylock()\fR,
+ \fIpthread_mutexattr_getpshared()\fR,
+ \fIpthread_mutexattr_setpshared()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_lock,\fR \fBpthread_mutex_trylock,\fR \fBpthread_mutex_unlock\fR
+ \- lock and unlock a mutex
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_lock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_trylock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_unlock\fR\|(pthread_mutex_t *\fImutex\fR);
+ .SH "DESCRIPTION"
+ The mutex object referenced by
+ \fImutex\fR
+ is locked by calling
+ \fIpthread_mutex_lock()\fR.
+ If the mutex is already locked,
+ the calling thread blocks until the mutex becomes available.
+ This operation returns with the mutex object referenced by
+ \fImutex\fR
+ in the locked state with the calling thread as its owner.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not
+ provided. Attempting to
+ relock the mutex causes deadlock. If a thread attempts to unlock a
+ mutex that it has not locked or a mutex
+ which is unlocked, undefined behaviour results.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then
+ error checking is provided.
+ If a thread attempts to relock a mutex that it has already
+ locked, an error will be returned. If a thread
+ attempts to unlock a mutex that it has not locked or a mutex which
+ is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
+ the concept of a lock count.
+ When a thread successfully acquires a mutex for the
+ first time, the lock count is set
+ to one. Every time a thread relocks this mutex, the lock count is
+ incremented by one. Each time the
+ thread unlocks the mutex, the lock count is decremented by one.
+ When the lock count reaches zero, the
+ mutex becomes available for other threads to acquire. If a thread
+ attempts to unlock a mutex that it has
+ not locked or a mutex which is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
+ lock the mutex results in
+ undefined behaviour. Attempting to unlock the mutex if it was not
+ locked by the calling thread results in
+ undefined behaviour. Attempting to unlock the mutex if it is not
+ locked results in undefined behaviour.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ is identical to
+ \fIpthread_mutex_lock()\fR
+ except that if the mutex object referenced by
+ \fImutex\fR
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function releases the mutex object referenced by
+ \fImutex\fR.
+ The manner in which a mutex is released is dependent upon the mutex's
+ type attribute.
+ If there are threads blocked on the mutex object referenced by
+ \fImutex\fR when
+ \fIpthread_mutex_unlock()\fR
+ is called, resulting in the mutex
+ becoming available, the scheduling policy is used to determine
+ which thread shall acquire the mutex.
+ (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes
+ available when the count reaches zero and the calling thread no
+ longer has any locks on this mutex).
+ .PP
+ If a signal is delivered to a thread waiting for a mutex,
+ upon return from the signal handler the thread resumes waiting
+ for the mutex as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ returns zero if a lock on the mutex object referenced by
+ \fImutex\fR
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_trylock()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The
+ \fImutex\fR
+ was created with the protocol attribute having the value
+ \s-1PTHREAD_PRIO_PROTECT\s0
+ and the calling thread's priority is higher
+ than the mutex's current priority ceiling.
+ .PP
+ The
+ \fIpthread_mutex_trylock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The
+ \fImutex\fR
+ could not be acquired because it was already locked.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_trylock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ does not refer to an initialised mutex object.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The mutex could not be acquired because the maximum
+ number of recursive locks for \fImutex\fR has been exceeded.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR
+ function may fail if:
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the mutex.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function may fail if:
+ .Ip "[\s-1EPERM\s0]" 4
+ The current thread does not own the mutex.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_destroy()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_setprioceiling,\fR \fBpthread_mutex_getprioceiling\fR
+ \- change the priority ceiling of a mutex
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_setprioceiling\fR\|(pthread_mutex_t *\fImutex\fR, int
+ \fIprioceiling\fR, int *\fIold_ceiling\fR);
+ .PP
+ int \fIpthread_mutex_getprioceiling\fR\|(const pthread_mutex_t *\fImutex\fR,
+ int *\fIprioceiling\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutex_getprioceiling()\fR
+ function returns the current priority ceiling of the mutex.
+ .PP
+ The
+ \fIpthread_mutex_setprioceiling()\fR
+ function either locks the mutex if it is unlocked, or blocks until it can
+ successfully lock the mutex, then it
+ changes the mutex's priority ceiling and releases the mutex.
+ When the change is successful, the previous value of the
+ priority ceiling is returned in
+ \fIold_ceiling\fR.
+ The process of locking the mutex need not adhere
+ to the priority protect protocol.
+ .PP
+ If the
+ \fIpthread_mutex_setprioceiling()\fR
+ function fails, the mutex priority ceiling is not changed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_setprioceiling()\fR
+ and
+ \fIpthread_mutex_getprioceiling()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_getprioceiling()\fR
+ and
+ \fIpthread_mutex_setprioceiling()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and
+ the implementation does not support the function.
+ .PP
+ The
+ \fIpthread_mutex_setprioceiling()\fR
+ and
+ \fIpthread_mutex_getprioceiling()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The priority requested by
+ \fIprioceiling\fR
+ is out of range.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ does not refer to a currently existing mutex.
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The implementation does not support the priority ceiling protocol for mutexes.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_unlock()\fR,
+ \fIpthread_mutex_trylock()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_lock,\fR \fBpthread_mutex_trylock,\fR \fBpthread_mutex_unlock\fR
+ \- lock and unlock a mutex
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_lock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_trylock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_unlock\fR\|(pthread_mutex_t *\fImutex\fR);
+ .SH "DESCRIPTION"
+ The mutex object referenced by
+ \fImutex\fR
+ is locked by calling
+ \fIpthread_mutex_lock()\fR.
+ If the mutex is already locked,
+ the calling thread blocks until the mutex becomes available.
+ This operation returns with the mutex object referenced by
+ \fImutex\fR
+ in the locked state with the calling thread as its owner.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not
+ provided. Attempting to
+ relock the mutex causes deadlock. If a thread attempts to unlock a
+ mutex that it has not locked or a mutex
+ which is unlocked, undefined behaviour results.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then
+ error checking is provided.
+ If a thread attempts to relock a mutex that it has already
+ locked, an error will be returned. If a thread
+ attempts to unlock a mutex that it has not locked or a mutex which
+ is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
+ the concept of a lock count.
+ When a thread successfully acquires a mutex for the
+ first time, the lock count is set
+ to one. Every time a thread relocks this mutex, the lock count is
+ incremented by one. Each time the
+ thread unlocks the mutex, the lock count is decremented by one.
+ When the lock count reaches zero, the
+ mutex becomes available for other threads to acquire. If a thread
+ attempts to unlock a mutex that it has
+ not locked or a mutex which is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
+ lock the mutex results in
+ undefined behaviour. Attempting to unlock the mutex if it was not
+ locked by the calling thread results in
+ undefined behaviour. Attempting to unlock the mutex if it is not
+ locked results in undefined behaviour.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ is identical to
+ \fIpthread_mutex_lock()\fR
+ except that if the mutex object referenced by
+ \fImutex\fR
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function releases the mutex object referenced by
+ \fImutex\fR.
+ The manner in which a mutex is released is dependent upon the mutex's
+ type attribute.
+ If there are threads blocked on the mutex object referenced by
+ \fImutex\fR when
+ \fIpthread_mutex_unlock()\fR
+ is called, resulting in the mutex
+ becoming available, the scheduling policy is used to determine
+ which thread shall acquire the mutex.
+ (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes
+ available when the count reaches zero and the calling thread no
+ longer has any locks on this mutex).
+ .PP
+ If a signal is delivered to a thread waiting for a mutex,
+ upon return from the signal handler the thread resumes waiting
+ for the mutex as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ returns zero if a lock on the mutex object referenced by
+ \fImutex\fR
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_trylock()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The
+ \fImutex\fR
+ was created with the protocol attribute having the value
+ \s-1PTHREAD_PRIO_PROTECT\s0
+ and the calling thread's priority is higher
+ than the mutex's current priority ceiling.
+ .PP
+ The
+ \fIpthread_mutex_trylock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The
+ \fImutex\fR
+ could not be acquired because it was already locked.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_trylock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ does not refer to an initialised mutex object.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The mutex could not be acquired because the maximum
+ number of recursive locks for \fImutex\fR has been exceeded.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR
+ function may fail if:
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the mutex.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function may fail if:
+ .Ip "[\s-1EPERM\s0]" 4
+ The current thread does not own the mutex.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_destroy()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutex_lock,\fR \fBpthread_mutex_trylock,\fR \fBpthread_mutex_unlock\fR
+ \- lock and unlock a mutex
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutex_lock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_trylock\fR\|(pthread_mutex_t *\fImutex\fR);
+ int \fIpthread_mutex_unlock\fR\|(pthread_mutex_t *\fImutex\fR);
+ .SH "DESCRIPTION"
+ The mutex object referenced by
+ \fImutex\fR
+ is locked by calling
+ \fIpthread_mutex_lock()\fR.
+ If the mutex is already locked,
+ the calling thread blocks until the mutex becomes available.
+ This operation returns with the mutex object referenced by
+ \fImutex\fR
+ in the locked state with the calling thread as its owner.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not
+ provided. Attempting to
+ relock the mutex causes deadlock. If a thread attempts to unlock a
+ mutex that it has not locked or a mutex
+ which is unlocked, undefined behaviour results.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then
+ error checking is provided.
+ If a thread attempts to relock a mutex that it has already
+ locked, an error will be returned. If a thread
+ attempts to unlock a mutex that it has not locked or a mutex which
+ is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
+ the concept of a lock count.
+ When a thread successfully acquires a mutex for the
+ first time, the lock count is set
+ to one. Every time a thread relocks this mutex, the lock count is
+ incremented by one. Each time the
+ thread unlocks the mutex, the lock count is decremented by one.
+ When the lock count reaches zero, the
+ mutex becomes available for other threads to acquire. If a thread
+ attempts to unlock a mutex that it has
+ not locked or a mutex which is unlocked, an error will be returned.
+ .PP
+ If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
+ lock the mutex results in
+ undefined behaviour. Attempting to unlock the mutex if it was not
+ locked by the calling thread results in
+ undefined behaviour. Attempting to unlock the mutex if it is not
+ locked results in undefined behaviour.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ is identical to
+ \fIpthread_mutex_lock()\fR
+ except that if the mutex object referenced by
+ \fImutex\fR
+ is currently locked (by any thread, including the
+ current thread), the call returns immediately.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function releases the mutex object referenced by
+ \fImutex\fR.
+ The manner in which a mutex is released is dependent upon the mutex's
+ type attribute.
+ If there are threads blocked on the mutex object referenced by
+ \fImutex\fR when
+ \fIpthread_mutex_unlock()\fR
+ is called, resulting in the mutex
+ becoming available, the scheduling policy is used to determine
+ which thread shall acquire the mutex.
+ (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes
+ available when the count reaches zero and the calling thread no
+ longer has any locks on this mutex).
+ .PP
+ If a signal is delivered to a thread waiting for a mutex,
+ upon return from the signal handler the thread resumes waiting
+ for the mutex as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ The function
+ \fIpthread_mutex_trylock()\fR
+ returns zero if a lock on the mutex object referenced by
+ \fImutex\fR
+ is acquired.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutex_lock()\fR
+ and
+ \fIpthread_mutex_trylock()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The
+ \fImutex\fR
+ was created with the protocol attribute having the value
+ \s-1PTHREAD_PRIO_PROTECT\s0
+ and the calling thread's priority is higher
+ than the mutex's current priority ceiling.
+ .PP
+ The
+ \fIpthread_mutex_trylock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The
+ \fImutex\fR
+ could not be acquired because it was already locked.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR,
+ \fIpthread_mutex_trylock()\fR
+ and
+ \fIpthread_mutex_unlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fImutex\fR
+ does not refer to an initialised mutex object.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The mutex could not be acquired because the maximum
+ number of recursive locks for \fImutex\fR has been exceeded.
+ .PP
+ The
+ \fIpthread_mutex_lock()\fR
+ function may fail if:
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the mutex.
+ .PP
+ The
+ \fIpthread_mutex_unlock()\fR
+ function may fail if:
+ .Ip "[\s-1EPERM\s0]" 4
+ The current thread does not own the mutex.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutex_destroy()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_init,\fR \fBpthread_mutexattr_destroy\fR
+ \- initialise and destroy mutex attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_init\fR\|(pthread_mutexattr_t *\fIattr\fR);
+ int \fIpthread_mutexattr_destroy\fR\|(pthread_mutexattr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_mutexattr_init()\fR
+ initialises a mutex attributes object
+ \fIattr\fR
+ with the default value for all of the attributes
+ defined by the implementation.
+ .PP
+ The effect of initialising an already initialised mutex
+ attributes object is undefined.
+ .PP
+ After a mutex attributes object has been used
+ to initialise one or more mutexes,
+ any function affecting the attributes object (including destruction)
+ does not affect any previously initialised mutexes.
+ .PP
+ The
+ \fIpthread_mutexattr_destroy()\fR
+ function destroys a mutex attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_mutexattr_destroy()\fR
+ to set the object referenced by
+ \fIattr\fR
+ to an invalid value.
+ A destroyed mutex attributes object
+ can be re-initialised using
+ \fIpthread_mutexattr_init()\fR;
+ the results of otherwise referencing the object after it has been
+ destroyed are undefined.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_mutexattr_init()\fR
+ and
+ \fIpthread_mutexattr_destroy()\fR
+ return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_init()\fR
+ function may fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the mutex attributes object.
+ .PP
+ The
+ \fIpthread_mutexattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutexattr_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_setprioceiling,\fR \fBpthread_mutexattr_getprioceiling\fR
+ \- set and get prioceiling attribute of mutex attribute object
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_setprioceiling\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIprioceiling\fR);
+ int \fIpthread_mutexattr_getprioceiling\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIprioceiling\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions, respectively, set and get the priority ceiling attribute of
+ a mutex attribute object pointed to by
+ \fIattr\fR
+ which was previously created by the function
+ \fIpthread_mutexattr_init()\fR.
+ .PP
+ The
+ \fIprioceiling\fR
+ attribute contains the priority ceiling of initialised mutexes.
+ The values of
+ \fIprioceiling\fR
+ will be within the maximum range of priorities defined by SCHED_FIFO.
+ .PP
+ The
+ \fIprioceiling\fR
+ attribute defines the priority ceiling of initialised mutexes,
+ which is the minimum priority level
+ at which the critical section guarded by the mutex is executed.
+ In order to avoid priority inversion,
+ the priority ceiling of the mutex will be set to a priority
+ higher than or equal to the highest priority of all the threads
+ that may lock that mutex.
+ The values of
+ \fIprioceiling\fR
+ will be within the maximum range of priorities
+ defined under the SCHED_FIFO scheduling policy.
+ .SH "RETURN VALUE"
+ Upon successful completion, the
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ or
+ \fIprioceiling\fR
+ is invalid.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_setprotocol,\fR \fBpthread_mutexattr_getprotocol\fR
+ \- set and get protocol attribute of mutex attribute object
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_setprotocol\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIprotocol\fR);
+ int \fIpthread_mutexattr_getprotocol\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIprotocol\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions, respectively, set and get the protocol attribute of a mutex
+ attribute object pointed to by
+ \fIattr\fR
+ which was previously created by the function
+ \fIpthread_mutexattr_init()\fR.
+ .PP
+ The
+ \fIprotocol\fR
+ attribute defines the protocol to be followed in utilising mutexes.
+ The value of
+ \fIprotocol\fR
+ may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or
+ PTHREAD_PRIO_PROTECT, which are defined by the header
+ \fI<pthread.h\fR>.
+ .PP
+ When a thread owns a mutex with the PTHREAD_PRIO_NONE
+ protocol attribute, its priority and scheduling are not affected
+ by its mutex ownership.
+ .PP
+ When a thread is blocking higher priority threads because of owning one or
+ more mutexes with the PTHREAD_PRIO_INHERIT
+ protocol attribute, it executes at the higher of its priority
+ or the priority of the highest priority thread waiting on any of the mutexes
+ owned by this thread and initialised with this protocol.
+ .PP
+ When a thread owns one or more mutexes initialised with the
+ PTHREAD_PRIO_PROTECT
+ protocol, it executes at the higher of its priority or the highest
+ of the priority ceilings of all the mutexes
+ owned by this thread and initialised with this attribute,
+ regardless of whether other threads are blocked on any of these
+ mutexes or not.
+ .PP
+ While a thread is holding a mutex which has been initialised with the
+ PRIO_INHERIT or PRIO_PROTECT protocol attributes,
+ it will not be subject to being moved
+ to the tail of the scheduling queue at its priority
+ in the event that its original priority is changed,
+ such as by a call to
+ \fIsched_setparam()\fR.
+ Likewise,
+ when a thread unlocks a mutex that has been initialised with the
+ PRIO_INHERIT or PRIO_PROTECT protocol attributes,
+ it will not be subject to being moved
+ to the tail of the scheduling queue at its priority
+ in the event that its original priority is changed.
+ .PP
+ If a thread simultaneously owns several mutexes
+ initialised with different protocols,
+ it will execute at the highest of the priorities
+ that it would have obtained by each of these protocols.
+ .PP
+ When a thread makes a call to
+ \fIpthread_mutex_lock()\fR,
+ if the symbol _POSIX_THREAD_PRIO_INHERIT
+ is defined and the mutex was
+ initialised with the protocol attribute having the value
+ PTHREAD_PRIO_INHERIT, when the calling thread is blocked
+ because the mutex is owned by another thread,
+ that owner thread will inherit the priority level
+ of the calling thread as long as it continues to own the mutex.
+ The implementation updates its execution priority
+ to the maximum of its assigned priority and all its inherited priorities.
+ Furthermore, if this owner thread itself becomes blocked on another mutex,
+ the same priority inheritance effect will be propagated
+ to this other owner thread, in a recursive manner.
+ .SH "RETURN VALUE"
+ Upon successful completion, the
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ Neither one of the options _POSIX_THREAD_PRIO_PROTECT and
+ _POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not
+ support the function.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ The value specified by
+ \fIprotocol\fR
+ is an unsupported value.
+ .PP
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ ro
+ \fIprotocol\fR
+ is invalid.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_getpshared,\fR \fBpthread_mutexattr_setpshared\fR
+ \- set and get process-shared attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_getpshared\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIpshared\fR);
+ int \fIpthread_mutexattr_setpshared\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the attributes object referenced by
+ \fIattr\fR.
+ The
+ \fIpthread_mutexattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by
+ \fIattr\fR.
+ .PP
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex
+ to be operated upon by any thread that has access to the memory
+ where the mutex is allocated, even if the mutex
+ is allocated in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon
+ by threads created within the same process as the thread
+ that initialised the mutex;
+ if threads of differing processes attempt to operate on such a mutex,
+ the behaviour is undefined.
+ The default value of the attribute is
+ PTHREAD_PROCESS_PRIVATE.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_mutexattr_setpshared()\fR
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ Upon successful completion,
+ \fIpthread_mutexattr_getpshared()\fR
+ returns zero and stores the value of the
+ \fIprocess-shared\fR
+ attribute of
+ \fIattr\fR
+ into the object referenced by the
+ \fIpshared\fR
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_getpshared()\fR
+ and
+ \fIpthread_mutexattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_mutexattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutexattr_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_gettype,\fR \fBpthread_mutexattr_settype\fR
+ \- get or set a mutex type
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_gettype\fR\|(const pthread_mutexattr_t \fI*attr\fR, int \fI*type\fR);
+ int \fIpthread_mutexattr_settype\fR\|(pthread_mutexattr_t \fI*attr\fR, int \fItype\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions respectively get and set the mutex \fItype\fR attribute.
+ This attribute is set in the \fItype\fR parameter
+ to these functions. The default value of the \fItype\fR
+ attribute is PTHREAD_MUTEX_DEFAULT.
+ .PP
+ The type of mutex is contained in the \fItype\fR attribute of the
+ mutex attributes. Valid mutex types include:
+ .Ip "\s-1PTHREAD_MUTEX_NORMAL\s0" 4
+ This type of mutex does not detect deadlock. A thread
+ attempting to relock this mutex without first unlocking it
+ will deadlock.  Attempting to unlock a
+ mutex locked by a different thread results in undefined behaviour.
+ Attempting to unlock an unlocked
+ mutex results in undefined behaviour.
+ .Ip "\s-1PTHREAD_MUTEX_ERRORCHECK\s0" 4
+ This type of mutex provides error checking.  A thread
+ attempting to relock this mutex without first unlocking it
+ will return with an error.
+ A thread attempting to unlock a mutex which another
+ thread has locked will return with an error.
+ A thread attempting to unlock an unlocked mutex will
+ return with an error.
+ .Ip "\s-1PTHREAD_MUTEX_RECURSIVE\s0" 4
+ A thread attempting to relock this mutex without first
+ unlocking it will succeed in locking the mutex. The relocking
+ deadlock which can occur with
+ mutexes of type \s-1PTHREAD_MUTEX_NORMAL\s0 cannot occur with this type
+ of mutex. Multiple
+ locks of this mutex require the same number of unlocks to release
+ the mutex before another thread
+ can acquire the mutex.
+ A thread attempting to unlock a mutex which another thread has
+ locked will return with an error. A thread attempting to
+ unlock an unlocked mutex will return with an error.
+ .Ip "\s-1PTHREAD_MUTEX_DEFAULT\s0" 4
+ Attempting to recursively lock a mutex of this type results in
+ undefined behaviour. Attempting to unlock a mutex of this type which
+ was not locked by the calling
+ thread results in undefined behaviour. Attempting to unlock a mutex
+ of this type which is not locked results in undefined behaviour.
+ An implementation is allowed to map this mutex to one of the
+ other mutex types.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutexattr_settype()\fR
+ function
+ returns zero.  Otherwise, an error number is
+ returned to indicate the error.
+ .PP
+ Upon successful completion, the
+ \fIpthread_mutexattr_gettype()\fR
+ function returns zero and stores the value of the
+ \fItype\fR attribute of \fIattr\fR into the object referenced by the
+ \fItype\fR
+ parameter.  Otherwise an error is returned to indicate
+ the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value \fItype\fR is invalid.
+ .PP
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ It is advised that an application should not use
+ a PTHREAD_MUTEX_RECURSIVE mutex with condition variables
+ because the implicit unlock performed for a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ may not actually release the
+ mutex (if it had been locked multiple times). If this happens,
+ no other thread can satisfy the condition of the predicate.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_init,\fR \fBpthread_mutexattr_destroy\fR
+ \- initialise and destroy mutex attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_init\fR\|(pthread_mutexattr_t *\fIattr\fR);
+ int \fIpthread_mutexattr_destroy\fR\|(pthread_mutexattr_t *\fIattr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_mutexattr_init()\fR
+ initialises a mutex attributes object
+ \fIattr\fR
+ with the default value for all of the attributes
+ defined by the implementation.
+ .PP
+ The effect of initialising an already initialised mutex
+ attributes object is undefined.
+ .PP
+ After a mutex attributes object has been used
+ to initialise one or more mutexes,
+ any function affecting the attributes object (including destruction)
+ does not affect any previously initialised mutexes.
+ .PP
+ The
+ \fIpthread_mutexattr_destroy()\fR
+ function destroys a mutex attributes object;
+ the object becomes, in effect, uninitialised.
+ An implementation may cause
+ \fIpthread_mutexattr_destroy()\fR
+ to set the object referenced by
+ \fIattr\fR
+ to an invalid value.
+ A destroyed mutex attributes object
+ can be re-initialised using
+ \fIpthread_mutexattr_init()\fR;
+ the results of otherwise referencing the object after it has been
+ destroyed are undefined.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_mutexattr_init()\fR
+ and
+ \fIpthread_mutexattr_destroy()\fR
+ return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_init()\fR
+ function may fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the mutex attributes object.
+ .PP
+ The
+ \fIpthread_mutexattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutexattr_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_setprioceiling,\fR \fBpthread_mutexattr_getprioceiling\fR
+ \- set and get prioceiling attribute of mutex attribute object
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_setprioceiling\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIprioceiling\fR);
+ int \fIpthread_mutexattr_getprioceiling\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIprioceiling\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions, respectively, set and get the priority ceiling attribute of
+ a mutex attribute object pointed to by
+ \fIattr\fR
+ which was previously created by the function
+ \fIpthread_mutexattr_init()\fR.
+ .PP
+ The
+ \fIprioceiling\fR
+ attribute contains the priority ceiling of initialised mutexes.
+ The values of
+ \fIprioceiling\fR
+ will be within the maximum range of priorities defined by SCHED_FIFO.
+ .PP
+ The
+ \fIprioceiling\fR
+ attribute defines the priority ceiling of initialised mutexes,
+ which is the minimum priority level
+ at which the critical section guarded by the mutex is executed.
+ In order to avoid priority inversion,
+ the priority ceiling of the mutex will be set to a priority
+ higher than or equal to the highest priority of all the threads
+ that may lock that mutex.
+ The values of
+ \fIprioceiling\fR
+ will be within the maximum range of priorities
+ defined under the SCHED_FIFO scheduling policy.
+ .SH "RETURN VALUE"
+ Upon successful completion, the
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIO_PROTECT is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_mutexattr_setprioceiling()\fR
+ and
+ \fIpthread_mutexattr_getprioceiling()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ or
+ \fIprioceiling\fR
+ is invalid.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_setprotocol,\fR \fBpthread_mutexattr_getprotocol\fR
+ \- set and get protocol attribute of mutex attribute object
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_setprotocol\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIprotocol\fR);
+ int \fIpthread_mutexattr_getprotocol\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIprotocol\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions, respectively, set and get the protocol attribute of a mutex
+ attribute object pointed to by
+ \fIattr\fR
+ which was previously created by the function
+ \fIpthread_mutexattr_init()\fR.
+ .PP
+ The
+ \fIprotocol\fR
+ attribute defines the protocol to be followed in utilising mutexes.
+ The value of
+ \fIprotocol\fR
+ may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or
+ PTHREAD_PRIO_PROTECT, which are defined by the header
+ \fI<pthread.h\fR>.
+ .PP
+ When a thread owns a mutex with the PTHREAD_PRIO_NONE
+ protocol attribute, its priority and scheduling are not affected
+ by its mutex ownership.
+ .PP
+ When a thread is blocking higher priority threads because of owning one or
+ more mutexes with the PTHREAD_PRIO_INHERIT
+ protocol attribute, it executes at the higher of its priority
+ or the priority of the highest priority thread waiting on any of the mutexes
+ owned by this thread and initialised with this protocol.
+ .PP
+ When a thread owns one or more mutexes initialised with the
+ PTHREAD_PRIO_PROTECT
+ protocol, it executes at the higher of its priority or the highest
+ of the priority ceilings of all the mutexes
+ owned by this thread and initialised with this attribute,
+ regardless of whether other threads are blocked on any of these
+ mutexes or not.
+ .PP
+ While a thread is holding a mutex which has been initialised with the
+ PRIO_INHERIT or PRIO_PROTECT protocol attributes,
+ it will not be subject to being moved
+ to the tail of the scheduling queue at its priority
+ in the event that its original priority is changed,
+ such as by a call to
+ \fIsched_setparam()\fR.
+ Likewise,
+ when a thread unlocks a mutex that has been initialised with the
+ PRIO_INHERIT or PRIO_PROTECT protocol attributes,
+ it will not be subject to being moved
+ to the tail of the scheduling queue at its priority
+ in the event that its original priority is changed.
+ .PP
+ If a thread simultaneously owns several mutexes
+ initialised with different protocols,
+ it will execute at the highest of the priorities
+ that it would have obtained by each of these protocols.
+ .PP
+ When a thread makes a call to
+ \fIpthread_mutex_lock()\fR,
+ if the symbol _POSIX_THREAD_PRIO_INHERIT
+ is defined and the mutex was
+ initialised with the protocol attribute having the value
+ PTHREAD_PRIO_INHERIT, when the calling thread is blocked
+ because the mutex is owned by another thread,
+ that owner thread will inherit the priority level
+ of the calling thread as long as it continues to own the mutex.
+ The implementation updates its execution priority
+ to the maximum of its assigned priority and all its inherited priorities.
+ Furthermore, if this owner thread itself becomes blocked on another mutex,
+ the same priority inheritance effect will be propagated
+ to this other owner thread, in a recursive manner.
+ .SH "RETURN VALUE"
+ Upon successful completion, the
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ Neither one of the options _POSIX_THREAD_PRIO_PROTECT and
+ _POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not
+ support the function.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ The value specified by
+ \fIprotocol\fR
+ is an unsupported value.
+ .PP
+ The
+ \fIpthread_mutexattr_setprotocol()\fR
+ and
+ \fIpthread_mutexattr_getprotocol()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ ro
+ \fIprotocol\fR
+ is invalid.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_getpshared,\fR \fBpthread_mutexattr_setpshared\fR
+ \- set and get process-shared attribute
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_getpshared\fR\|(const pthread_mutexattr_t *\fIattr\fR,
+ int *\fIpshared\fR);
+ int \fIpthread_mutexattr_setpshared\fR\|(pthread_mutexattr_t *\fIattr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the attributes object referenced by
+ \fIattr\fR.
+ The
+ \fIpthread_mutexattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by
+ \fIattr\fR.
+ .PP
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex
+ to be operated upon by any thread that has access to the memory
+ where the mutex is allocated, even if the mutex
+ is allocated in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon
+ by threads created within the same process as the thread
+ that initialised the mutex;
+ if threads of differing processes attempt to operate on such a mutex,
+ the behaviour is undefined.
+ The default value of the attribute is
+ PTHREAD_PROCESS_PRIVATE.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_mutexattr_setpshared()\fR
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ Upon successful completion,
+ \fIpthread_mutexattr_getpshared()\fR
+ returns zero and stores the value of the
+ \fIprocess-shared\fR
+ attribute of
+ \fIattr\fR
+ into the object referenced by the
+ \fIpshared\fR
+ parameter.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_getpshared()\fR
+ and
+ \fIpthread_mutexattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIattr\fR
+ is invalid.
+ .PP
+ The
+ \fIpthread_mutexattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute
+ is outside the range of legal values for that attribute.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_mutex_init()\fR,
+ \fIpthread_mutexattr_init()\fR,
+ \fIpthread_cond_init()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_mutexattr_gettype,\fR \fBpthread_mutexattr_settype\fR
+ \- get or set a mutex type
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_mutexattr_gettype\fR\|(const pthread_mutexattr_t \fI*attr\fR, int \fI*type\fR);
+ int \fIpthread_mutexattr_settype\fR\|(pthread_mutexattr_t \fI*attr\fR, int \fItype\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions respectively get and set the mutex \fItype\fR attribute.
+ This attribute is set in the \fItype\fR parameter
+ to these functions. The default value of the \fItype\fR
+ attribute is PTHREAD_MUTEX_DEFAULT.
+ .PP
+ The type of mutex is contained in the \fItype\fR attribute of the
+ mutex attributes. Valid mutex types include:
+ .Ip "\s-1PTHREAD_MUTEX_NORMAL\s0" 4
+ This type of mutex does not detect deadlock. A thread
+ attempting to relock this mutex without first unlocking it
+ will deadlock.  Attempting to unlock a
+ mutex locked by a different thread results in undefined behaviour.
+ Attempting to unlock an unlocked
+ mutex results in undefined behaviour.
+ .Ip "\s-1PTHREAD_MUTEX_ERRORCHECK\s0" 4
+ This type of mutex provides error checking.  A thread
+ attempting to relock this mutex without first unlocking it
+ will return with an error.
+ A thread attempting to unlock a mutex which another
+ thread has locked will return with an error.
+ A thread attempting to unlock an unlocked mutex will
+ return with an error.
+ .Ip "\s-1PTHREAD_MUTEX_RECURSIVE\s0" 4
+ A thread attempting to relock this mutex without first
+ unlocking it will succeed in locking the mutex. The relocking
+ deadlock which can occur with
+ mutexes of type \s-1PTHREAD_MUTEX_NORMAL\s0 cannot occur with this type
+ of mutex. Multiple
+ locks of this mutex require the same number of unlocks to release
+ the mutex before another thread
+ can acquire the mutex.
+ A thread attempting to unlock a mutex which another thread has
+ locked will return with an error. A thread attempting to
+ unlock an unlocked mutex will return with an error.
+ .Ip "\s-1PTHREAD_MUTEX_DEFAULT\s0" 4
+ Attempting to recursively lock a mutex of this type results in
+ undefined behaviour. Attempting to unlock a mutex of this type which
+ was not locked by the calling
+ thread results in undefined behaviour. Attempting to unlock a mutex
+ of this type which is not locked results in undefined behaviour.
+ An implementation is allowed to map this mutex to one of the
+ other mutex types.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_mutexattr_settype()\fR
+ function
+ returns zero.  Otherwise, an error number is
+ returned to indicate the error.
+ .PP
+ Upon successful completion, the
+ \fIpthread_mutexattr_gettype()\fR
+ function returns zero and stores the value of the
+ \fItype\fR attribute of \fIattr\fR into the object referenced by the
+ \fItype\fR
+ parameter.  Otherwise an error is returned to indicate
+ the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions will fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value \fItype\fR is invalid.
+ .PP
+ The
+ \fIpthread_mutexattr_gettype()\fR
+ and
+ \fIpthread_mutexattr_settype()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ It is advised that an application should not use
+ a PTHREAD_MUTEX_RECURSIVE mutex with condition variables
+ because the implicit unlock performed for a
+ \fIpthread_cond_wait()\fR
+ or
+ \fIpthread_cond_timedwait()\fR
+ may not actually release the
+ mutex (if it had been locked multiple times). If this happens,
+ no other thread can satisfy the condition of the predicate.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cond_wait()\fR,
+ \fIpthread_cond_timedwait()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_once\fR \- dynamic package initialisation
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_once\fR\|(pthread_once_t *\fIonce_control\fR,
+ void (*\fIinit_routine\fR)(void));
+ pthread_once_t \fIonce_control\fR = PTHREAD_ONCE_INIT;
+ .SH "DESCRIPTION"
+ The first call to
+ \fIpthread_once()\fR
+ by any thread in a process, with a given
+ \fIonce_control\fR,
+ will call the
+ \fIinit_routine()\fR
+ with no arguments.
+ Subsequent calls of
+ \fIpthread_once()\fR
+ with the same
+ \fIonce_control\fR
+ will not call the
+ \fIinit_routine()\fR.
+ On return from
+ \fIpthread_once()\fR,
+ it is guaranteed that
+ \fIinit_routine()\fR
+ has completed.
+ The
+ \fIonce_control\fR
+ parameter is used to determine whether
+ the associated initialisation routine has been called.
+ .PP
+ The function
+ \fIpthread_once()\fR
+ is not a cancellation point.
+ However, if
+ \fIinit_routine()\fR
+ is a cancellation point and is canceled,
+ the effect on
+ \fIonce_control\fR
+ is as if
+ \fIpthread_once()\fR
+ was never called.
+ .PP
+ The constant PTHREAD_ONCE_INIT
+ is defined by the header
+ \fI<pthread.h\fR>.
+ .PP
+ The behaviour of
+ \fIpthread_once()\fR
+ is undefined if
+ \fIonce_control\fR
+ has automatic storage duration or is not initialised by
+ PTHREAD_ONCE_INIT.
+ .SH "RETURN VALUE"
+ Upon successful completion,
+ \fIpthread_once()\fR
+ returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ The
+ \fIpthread_once()\fR
+ function will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread,h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_init,\fR \fBpthread_rwlock_destroy\fR
+ \- initialise or destroy a read-write lock object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_init\fR\|(pthread_rwlock_t *rwlock,
+ const pthread_rwlockattr_t \fI*attr\fR);
+ int \fIpthread_rwlock_destroy\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ pthread_rwlock_t \fIrwlock\fR=PTHREAD_RWLOCK_INITIALIZER;
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_init()\fR
+ function initialises the read-write lock referenced by \fIrwlock\fR with
+ the attributes referenced by \fIattr\fR.  If \fIattr\fR is NULL, the
+ default
+ read-write lock attributes are used; the effect is the same as
+ passing the address of a default read-write lock attributes object.
+ Once initialised, the lock can be used any
+ number of times without being re-initialised.
+ Upon successful initialisation, the state of the read-write lock
+ becomes initialised and unlocked.
+ Results are undefined if
+ \fIpthread_rwlock_init()\fR
+ is called specifying an already initialised read-write lock.
+ Results are undefined if a read-write lock is used without first being
+ initialised.
+ .PP
+ If the
+ \fIpthread_rwlock_init()\fR
+ function fails, \fIrwlock\fR is not initialised and the contents of
+ \fIrwlock\fR are undefined.
+ .PP
+ The
+ \fIpthread_rwlock_destroy()\fR
+ function destroys the read-write lock object referenced by \fIrwlock\fR
+ and
+ releases any resources used by the lock.
+ The effect of subsequent use of the lock is undefined until the lock
+ is re-initialised by another call to
+ \fIpthread_rwlock_init()\fR.
+ An implementation may cause
+ \fIpthread_rwlock_destroy()\fR
+ to set the object referenced by \fIrwlock\fR to an invalid value.
+ Results are undefined if
+ \fIpthread_rwlock_destroy()\fR
+ is called when any thread holds \fIrwlock\fR.
+ Attempting to destroy an uninitialised
+ read-write lock results in undefined behaviour.
+ A destroyed read-write lock object can be re-initialised using
+ \fIpthread_rwlock_init()\fR;
+ the results of otherwise referencing the read-write lock object after it
+ has been destroyed are undefined.
+ .PP
+ In cases where default read-write lock attributes are appropriate, the
+ macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks
+ that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_rwlock_init()\fR
+ with the parameter \fIattr\fR specified as NULL, except that no error
+ checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_init()\fR
+ and
+ \fIpthread_rwlock_destroy()\fR
+ functions return zero.  Otherwise, an
+ error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL] error checks, if implemented, will
+ act as if they were performed immediately at the beginning of processing
+ for the function and caused an error return
+ prior to modifying the state of the read-write lock specified by
+ \fIrwlock\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other than memory)
+ to initialise another read-write lock.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the read-write lock.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .PP
+ The
+ \fIpthread_rwlock_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to re-initialise the
+ object referenced by \fIrwlock\fR, a previously initialised but
+ not yet destroyed read-write lock.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .PP
+ The
+ \fIpthread_rwlock_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy the
+ object referenced by \fIrwlock\fR while it is locked.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_unlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_init,\fR \fBpthread_rwlock_destroy\fR
+ \- initialise or destroy a read-write lock object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_init\fR\|(pthread_rwlock_t *rwlock,
+ const pthread_rwlockattr_t \fI*attr\fR);
+ int \fIpthread_rwlock_destroy\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ pthread_rwlock_t \fIrwlock\fR=PTHREAD_RWLOCK_INITIALIZER;
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_init()\fR
+ function initialises the read-write lock referenced by \fIrwlock\fR with
+ the attributes referenced by \fIattr\fR.  If \fIattr\fR is NULL, the
+ default
+ read-write lock attributes are used; the effect is the same as
+ passing the address of a default read-write lock attributes object.
+ Once initialised, the lock can be used any
+ number of times without being re-initialised.
+ Upon successful initialisation, the state of the read-write lock
+ becomes initialised and unlocked.
+ Results are undefined if
+ \fIpthread_rwlock_init()\fR
+ is called specifying an already initialised read-write lock.
+ Results are undefined if a read-write lock is used without first being
+ initialised.
+ .PP
+ If the
+ \fIpthread_rwlock_init()\fR
+ function fails, \fIrwlock\fR is not initialised and the contents of
+ \fIrwlock\fR are undefined.
+ .PP
+ The
+ \fIpthread_rwlock_destroy()\fR
+ function destroys the read-write lock object referenced by \fIrwlock\fR
+ and
+ releases any resources used by the lock.
+ The effect of subsequent use of the lock is undefined until the lock
+ is re-initialised by another call to
+ \fIpthread_rwlock_init()\fR.
+ An implementation may cause
+ \fIpthread_rwlock_destroy()\fR
+ to set the object referenced by \fIrwlock\fR to an invalid value.
+ Results are undefined if
+ \fIpthread_rwlock_destroy()\fR
+ is called when any thread holds \fIrwlock\fR.
+ Attempting to destroy an uninitialised
+ read-write lock results in undefined behaviour.
+ A destroyed read-write lock object can be re-initialised using
+ \fIpthread_rwlock_init()\fR;
+ the results of otherwise referencing the read-write lock object after it
+ has been destroyed are undefined.
+ .PP
+ In cases where default read-write lock attributes are appropriate, the
+ macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks
+ that are statically allocated.
+ The effect is equivalent to dynamic initialisation by a call to
+ \fIpthread_rwlock_init()\fR
+ with the parameter \fIattr\fR specified as NULL, except that no error
+ checks are performed.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_init()\fR
+ and
+ \fIpthread_rwlock_destroy()\fR
+ functions return zero.  Otherwise, an
+ error number is returned to indicate the error.
+ The [EBUSY] and [EINVAL] error checks, if implemented, will
+ act as if they were performed immediately at the beginning of processing
+ for the function and caused an error return
+ prior to modifying the state of the read-write lock specified by
+ \fIrwlock\fR.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_init()\fR
+ function will fail if:
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The system lacked the necessary resources (other than memory)
+ to initialise another read-write lock.
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the read-write lock.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the privilege to perform the operation.
+ .PP
+ The
+ \fIpthread_rwlock_init()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to re-initialise the
+ object referenced by \fIrwlock\fR, a previously initialised but
+ not yet destroyed read-write lock.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .PP
+ The
+ \fIpthread_rwlock_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The implementation has detected an attempt to destroy the
+ object referenced by \fIrwlock\fR while it is locked.
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_unlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_rdlock,\fR \fBpthread_rwlock_tryrdlock\fR
+ \- lock a read-write lock object for reading
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_rdlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ int \fIpthread_rwlock_tryrdlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_rdlock()\fR
+ function applies a read lock to the read-write lock referenced by
+ \fIrwlock\fR.
+ The calling thread acquires the read lock if a writer does not
+ hold the lock and there are no writers blocked
+ on the lock.  It is unspecified whether the calling thread
+ acquires the lock when a writer does not hold the lock
+ and there are writers waiting for the lock.  If a writer holds
+ the lock, the calling thread will not acquire the
+ read lock.  If the read lock is not acquired, the calling
+ thread blocks (that is, it does not return from the
+ \fIpthread_rwlock_rdlock()\fR
+ call) until it can acquire the lock.
+ Results are undefined if the calling thread holds
+ a write lock on \fIrwlock\fR
+ at the time the call is made.
+ .PP
+ Implementations are allowed to favour writers over readers
+ to avoid writer starvation.
+ .PP
+ A thread may hold multiple concurrent read locks on \fIrwlock\fR
+ (that is, successfully call the
+ \fIpthread_rwlock_rdlock()\fR
+ function \fIn\fR times). If so, the thread
+ must perform matching unlocks (that is, it must
+ call the
+ \fIpthread_rwlock_unlock()\fR
+ function \fIn\fR times).
+ .PP
+ The function
+ \fIpthread_rwlock_tryrdlock()\fR
+ applies a read lock
+ as in the
+ \fIpthread_rwlock_rdlock()\fR
+ function
+ with the exception that the function fails if any thread holds a
+ write lock on \fIrwlock\fR or there are writers blocked
+ on \fIrwlock\fR.
+ .PP
+ Results are undefined if any of these functions are called with
+ an uninitialised read-write lock.
+ .PP
+ If a signal is delivered to a thread waiting for a read-write
+ lock for reading, upon return from the signal handler
+ the thread resumes waiting for the read-write lock for
+ reading as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_rdlock()\fR
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+ .PP
+ The function
+ \fIpthread_rwlock_tryrdlock()\fR
+ returns zero if the
+ lock for reading on the read-write lock object
+ referenced by \fIrwlock\fR is acquired.
+ Otherwise an error number
+ is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_tryrdlock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The read-write lock could not be acquired for reading because a
+ writer holds the
+ lock or was blocked on it.
+ .PP
+ The
+ \fIpthread_rwlock_rdlock()\fR
+ and
+ \fIpthread_rwlock_tryrdlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIrwlock\fR does not refer to an initialised
+ read-write lock object.
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the read-write lock for writing.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The read lock could not be acquired because the maximum number of
+ read locks
+ for \fIrwlock\fR has been exceeded.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .PP
+ Realtime applications may encounter priority inversion when using
+ read-write locks.
+ The problem occurs when a high priority thread &quot;locks&quot; a read-write
+ lock that is about to be &quot;unlocked&quot; by a low priority thread, but
+ the low priority thread is preempted by a medium priority thread.
+ This scenario leads to priority inversion; a high priority thread is
+ blocked by lower priority threads for an unlimited period of time.
+ During system design, realtime programmers must take into account the
+ possibility of this kind of priority inversion.
+ They can deal with it in a number of ways, such as by having critical
+ sections that are guarded by read-write locks execute at a high
+ priority, so that a thread cannot be preempted while executing in its
+ critical section.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_unlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_rdlock,\fR \fBpthread_rwlock_tryrdlock\fR
+ \- lock a read-write lock object for reading
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_rdlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ int \fIpthread_rwlock_tryrdlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_rdlock()\fR
+ function applies a read lock to the read-write lock referenced by
+ \fIrwlock\fR.
+ The calling thread acquires the read lock if a writer does not
+ hold the lock and there are no writers blocked
+ on the lock.  It is unspecified whether the calling thread
+ acquires the lock when a writer does not hold the lock
+ and there are writers waiting for the lock.  If a writer holds
+ the lock, the calling thread will not acquire the
+ read lock.  If the read lock is not acquired, the calling
+ thread blocks (that is, it does not return from the
+ \fIpthread_rwlock_rdlock()\fR
+ call) until it can acquire the lock.
+ Results are undefined if the calling thread holds
+ a write lock on \fIrwlock\fR
+ at the time the call is made.
+ .PP
+ Implementations are allowed to favour writers over readers
+ to avoid writer starvation.
+ .PP
+ A thread may hold multiple concurrent read locks on \fIrwlock\fR
+ (that is, successfully call the
+ \fIpthread_rwlock_rdlock()\fR
+ function \fIn\fR times). If so, the thread
+ must perform matching unlocks (that is, it must
+ call the
+ \fIpthread_rwlock_unlock()\fR
+ function \fIn\fR times).
+ .PP
+ The function
+ \fIpthread_rwlock_tryrdlock()\fR
+ applies a read lock
+ as in the
+ \fIpthread_rwlock_rdlock()\fR
+ function
+ with the exception that the function fails if any thread holds a
+ write lock on \fIrwlock\fR or there are writers blocked
+ on \fIrwlock\fR.
+ .PP
+ Results are undefined if any of these functions are called with
+ an uninitialised read-write lock.
+ .PP
+ If a signal is delivered to a thread waiting for a read-write
+ lock for reading, upon return from the signal handler
+ the thread resumes waiting for the read-write lock for
+ reading as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_rdlock()\fR
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+ .PP
+ The function
+ \fIpthread_rwlock_tryrdlock()\fR
+ returns zero if the
+ lock for reading on the read-write lock object
+ referenced by \fIrwlock\fR is acquired.
+ Otherwise an error number
+ is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_tryrdlock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The read-write lock could not be acquired for reading because a
+ writer holds the
+ lock or was blocked on it.
+ .PP
+ The
+ \fIpthread_rwlock_rdlock()\fR
+ and
+ \fIpthread_rwlock_tryrdlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIrwlock\fR does not refer to an initialised
+ read-write lock object.
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the read-write lock for writing.
+ .Ip "[\s-1EAGAIN\s0]" 4
+ The read lock could not be acquired because the maximum number of
+ read locks
+ for \fIrwlock\fR has been exceeded.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .PP
+ Realtime applications may encounter priority inversion when using
+ read-write locks.
+ The problem occurs when a high priority thread &quot;locks&quot; a read-write
+ lock that is about to be &quot;unlocked&quot; by a low priority thread, but
+ the low priority thread is preempted by a medium priority thread.
+ This scenario leads to priority inversion; a high priority thread is
+ blocked by lower priority threads for an unlimited period of time.
+ During system design, realtime programmers must take into account the
+ possibility of this kind of priority inversion.
+ They can deal with it in a number of ways, such as by having critical
+ sections that are guarded by read-write locks execute at a high
+ priority, so that a thread cannot be preempted while executing in its
+ critical section.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_unlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_wrlock,\fR \fBpthread_rwlock_trywrlock\fR
+ \- lock a read-write lock object for writing
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_wrlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ int \fIpthread_rwlock_trywrlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_wrlock()\fR
+ function applies a write lock to
+ the read-write lock referenced by \fIrwlock\fR. The
+ calling thread acquires the write lock if no other thread
+ (reader or writer) holds the read-write lock \fIrwlock\fR.
+ Otherwise, the thread blocks (that is, does not return from the
+ \fIpthread_rwlock_wrlock()\fR
+ call) until it can
+ acquire the lock. Results are undefined if the calling thread
+ holds the read-write lock (whether a read or write
+ lock) at the time the call is made.
+ .PP
+ Implementations are allowed to favour writers over
+ readers to avoid writer starvation.
+ .PP
+ The function
+ \fIpthread_rwlock_trywrlock()\fR
+ applies a write lock
+ like the
+ \fIpthread_rwlock_wrlock()\fR
+ function, with the exception that the function fails if any
+ thread currently holds \fIrwlock\fR (for reading or writing).
+ .PP
+ Results are undefined if any of these functions are called with
+ an uninitialised read-write lock.
+ .PP
+ If a signal is delivered to a thread waiting for a read-write
+ lock for writing, upon return from the signal handler
+ the thread resumes waiting for the read-write lock for
+ writing as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_wrlock()\fR
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+ .PP
+ The function
+ \fIpthread_rwlock_trywrlock()\fR
+ returns zero if the
+ lock for writing on the read-write lock object
+ referenced by \fIrwlock\fR is acquired.
+ Otherwise an error number is
+ returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_trywrlock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The read-write lock could not be acquired for writing because it
+ was already locked for reading or writing.
+ .PP
+ The
+ \fIpthread_rwlock_wrlock()\fR
+ and
+ \fIpthread_rwlock_trywrlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIrwlock\fR does not refer to an initialised
+ read-write lock object.
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the read-write lock for writing or
+ reading.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .PP
+ Realtime applications may encounter priority inversion when using
+ read-write locks.
+ The problem occurs when a high priority thread &quot;locks&quot; a read-write
+ lock that is about to be &quot;unlocked&quot; by a low priority thread, but
+ the low priority thread is preempted by a medium priority thread.
+ This scenario leads to priority inversion; a high priority thread is
+ blocked by lower priority threads for an unlimited period of time.
+ During system design, realtime programmers must take into account the
+ possibility of this kind of priority inversion.
+ They can deal with it in a number of ways, such as by having critical
+ sections that are guarded by read-write locks execute at a high
+ priority, so that a thread cannot be preempted while executing in its
+ critical section.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_rdlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_unlock\fR \- unlock a read-write lock object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_unlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_unlock()\fR
+ function is called to release a lock held on the read-write lock
+ object referenced by \fIrwlock\fR.
+ Results are undefined if the read-write lock \fIrwlock\fR is not
+ held by the calling thread.
+ .PP
+ If this function is called to release a read lock from the
+ read-write lock object and there are other read locks
+ currently held on this read-write lock object, the read-write
+ lock object remains in the read locked state.
+ If this function releases the calling thread's last read lock on this
+ read-write lock object, then the calling thread is no longer one of
+ the owners of the object.
+ If this function releases the last read lock for this read-write lock
+ object, the read-write lock object will be put in the unlocked state
+ with no owners.
+ .PP
+ If this function is called to release a write lock for this
+ read-write lock object, the read-write lock object will
+ be put in the unlocked state with no owners.
+ .PP
+ If the call to the
+ \fIpthread_rwlock_unlock()\fR
+ function results in
+ the read-write lock object becoming unlocked
+ and there are multiple threads waiting to acquire the read-write
+ lock object for writing, the scheduling policy
+ is used to determine which thread acquires the read-write
+ lock object for writing. If there are multiple
+ threads waiting to acquire the read-write lock object for reading,
+ the scheduling policy is used to determine
+ the order in which the waiting threads acquire the
+ read-write lock object for reading.
+ If there are multiple threads blocked on \fIrwlock\fR
+ for both read locks and write locks, it is
+ unspecified whether the readers acquire the lock first or whether
+ a writer acquires the lock first.
+ .PP
+ Results are undefined if any of these functions are called with
+ an uninitialised read-write lock.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_unlock()\fR
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_unlock()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIrwlock\fR does not refer to an initialised
+ read-write lock object.
+ .Ip "[\s-1EPERM\s0]" 4
+ The current thread does not own the read-write lock.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_rdlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlock_wrlock,\fR \fBpthread_rwlock_trywrlock\fR
+ \- lock a read-write lock object for writing
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlock_wrlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ int \fIpthread_rwlock_trywrlock\fR\|(pthread_rwlock_t \fI*rwlock\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_rwlock_wrlock()\fR
+ function applies a write lock to
+ the read-write lock referenced by \fIrwlock\fR. The
+ calling thread acquires the write lock if no other thread
+ (reader or writer) holds the read-write lock \fIrwlock\fR.
+ Otherwise, the thread blocks (that is, does not return from the
+ \fIpthread_rwlock_wrlock()\fR
+ call) until it can
+ acquire the lock. Results are undefined if the calling thread
+ holds the read-write lock (whether a read or write
+ lock) at the time the call is made.
+ .PP
+ Implementations are allowed to favour writers over
+ readers to avoid writer starvation.
+ .PP
+ The function
+ \fIpthread_rwlock_trywrlock()\fR
+ applies a write lock
+ like the
+ \fIpthread_rwlock_wrlock()\fR
+ function, with the exception that the function fails if any
+ thread currently holds \fIrwlock\fR (for reading or writing).
+ .PP
+ Results are undefined if any of these functions are called with
+ an uninitialised read-write lock.
+ .PP
+ If a signal is delivered to a thread waiting for a read-write
+ lock for writing, upon return from the signal handler
+ the thread resumes waiting for the read-write lock for
+ writing as if it was not interrupted.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlock_wrlock()\fR
+ function returns zero.
+ Otherwise, an error number is returned
+ to indicate the error.
+ .PP
+ The function
+ \fIpthread_rwlock_trywrlock()\fR
+ returns zero if the
+ lock for writing on the read-write lock object
+ referenced by \fIrwlock\fR is acquired.
+ Otherwise an error number is
+ returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlock_trywrlock()\fR
+ function will fail if:
+ .Ip "[\s-1EBUSY\s0]" 4
+ The read-write lock could not be acquired for writing because it
+ was already locked for reading or writing.
+ .PP
+ The
+ \fIpthread_rwlock_wrlock()\fR
+ and
+ \fIpthread_rwlock_trywrlock()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIrwlock\fR does not refer to an initialised
+ read-write lock object.
+ .Ip "[\s-1EDEADLK\s0]" 4
+ The current thread already owns the read-write lock for writing or
+ reading.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .PP
+ Realtime applications may encounter priority inversion when using
+ read-write locks.
+ The problem occurs when a high priority thread &quot;locks&quot; a read-write
+ lock that is about to be &quot;unlocked&quot; by a low priority thread, but
+ the low priority thread is preempted by a medium priority thread.
+ This scenario leads to priority inversion; a high priority thread is
+ blocked by lower priority threads for an unlimited period of time.
+ During system design, realtime programmers must take into account the
+ possibility of this kind of priority inversion.
+ They can deal with it in a number of ways, such as by having critical
+ sections that are guarded by read-write locks execute at a high
+ priority, so that a thread cannot be preempted while executing in its
+ critical section.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlockattr_init()\fR,
+ \fIpthread_rwlock_rdlock()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlockattr_init,\fR \fBpthread_rwlockattr_destroy\fR
+ \- initialise and destroy read-write lock attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlockattr_init\fR\|(pthread_rwlockattr_t \fI*attr\fR);
+ int \fIpthread_rwlockattr_destroy\fR\|(pthread_rwlockattr_t \fI*attr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_rwlockattr_init()\fR
+ initialises a read-write
+ lock attributes object \fIattr\fR with the default
+ value for all of the attributes defined by the implementation.
+ .PP
+ Results are undefined if
+ \fIpthread_rwlockattr_init()\fR
+ is called
+ specifying an already initialised read-write lock
+ attributes object.
+ .PP
+ After a read-write lock attributes object has been used to
+ initialise one or more read-write locks, any function
+ affecting the attributes object (including destruction) does not
+ affect any previously initialised read-write locks.
+ .PP
+ The
+ \fIpthread_rwlockattr_destroy()\fR
+ function destroys a read-write
+ lock attributes object. The effect of
+ subsequent use of the object is undefined until the object is
+ re-initialised by another call to
+ \fIpthread_rwlockattr_init()\fR.
+ An implementation may cause
+ \fIpthread_rwlockattr_destroy()\fR
+ to set the object
+ referenced by attr to an invalid value.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlockattr_init()\fR
+ and
+ \fIpthread_rwlockattr_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to
+ indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlockattr_init()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the read-write
+ lock attributes object.
+ .PP
+ The
+ \fIpthread_rwlockattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlockattr_getpshared()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlockattr_getpshared,\fR \fBpthread_rwlockattr_setpshared\fR
+ \- get and set process-shared attribute of read-write lock
+ attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlockattr_getpshared\fR\|(const pthread_rwlockattr_t \fI*attr\fR,
+ int \fI*pshared\fR);
+ int \fIpthread_rwlockattr_setpshared\fR\|(pthread_rwlockattr_t \fI*attr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED to
+ permit a read-write lock to be operated upon by any thread that
+ has access to the memory where the read-write lock is allocated,
+ even if the read-write lock is allocated
+ in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the
+ read-write lock will only be
+ operated upon by threads created within the same process as the
+ thread that initialised the read-write lock; if
+ threads of differing processes attempt to operate on such a
+ read-write lock, the behaviour is undefined. The
+ default value of the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE.
+ .PP
+ The
+ \fIpthread_rwlockattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the initialised attributes object referenced by \fIattr\fR.
+ The
+ \fIpthread_rwlockattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by attr.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlockattr_setpshared()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ Upon successful completion, the
+ \fIpthread_rwlockattr_getpshared()\fR
+ returns zero and stores the value of the
+ \fIprocess-shared\fR
+ attribute of \fIattr\fR into the object referenced by the
+ \fIpshared\fR parameter. Otherwise an error number is
+ returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlockattr_getpshared()\fR
+ and
+ \fIpthread_rwlockattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .PP
+ The
+ \fIpthread_rwlockattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute is outside the range
+ of legal values for
+ that attribute.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlockattr_init()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlockattr_init,\fR \fBpthread_rwlockattr_destroy\fR
+ \- initialise and destroy read-write lock attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlockattr_init\fR\|(pthread_rwlockattr_t \fI*attr\fR);
+ int \fIpthread_rwlockattr_destroy\fR\|(pthread_rwlockattr_t \fI*attr\fR);
+ .SH "DESCRIPTION"
+ The function
+ \fIpthread_rwlockattr_init()\fR
+ initialises a read-write
+ lock attributes object \fIattr\fR with the default
+ value for all of the attributes defined by the implementation.
+ .PP
+ Results are undefined if
+ \fIpthread_rwlockattr_init()\fR
+ is called
+ specifying an already initialised read-write lock
+ attributes object.
+ .PP
+ After a read-write lock attributes object has been used to
+ initialise one or more read-write locks, any function
+ affecting the attributes object (including destruction) does not
+ affect any previously initialised read-write locks.
+ .PP
+ The
+ \fIpthread_rwlockattr_destroy()\fR
+ function destroys a read-write
+ lock attributes object. The effect of
+ subsequent use of the object is undefined until the object is
+ re-initialised by another call to
+ \fIpthread_rwlockattr_init()\fR.
+ An implementation may cause
+ \fIpthread_rwlockattr_destroy()\fR
+ to set the object
+ referenced by attr to an invalid value.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlockattr_init()\fR
+ and
+ \fIpthread_rwlockattr_destroy()\fR
+ functions return zero.
+ Otherwise, an error number is returned to
+ indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlockattr_init()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to initialise the read-write
+ lock attributes object.
+ .PP
+ The
+ \fIpthread_rwlockattr_destroy()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlockattr_getpshared()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_rwlockattr_getpshared,\fR \fBpthread_rwlockattr_setpshared\fR
+ \- get and set process-shared attribute of read-write lock
+ attributes object
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_rwlockattr_getpshared\fR\|(const pthread_rwlockattr_t \fI*attr\fR,
+ int \fI*pshared\fR);
+ int \fIpthread_rwlockattr_setpshared\fR\|(pthread_rwlockattr_t \fI*attr\fR,
+ int \fIpshared\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIprocess-shared\fR
+ attribute is set to PTHREAD_PROCESS_SHARED to
+ permit a read-write lock to be operated upon by any thread that
+ has access to the memory where the read-write lock is allocated,
+ even if the read-write lock is allocated
+ in memory that is shared by multiple processes.
+ If the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE, the
+ read-write lock will only be
+ operated upon by threads created within the same process as the
+ thread that initialised the read-write lock; if
+ threads of differing processes attempt to operate on such a
+ read-write lock, the behaviour is undefined. The
+ default value of the
+ \fIprocess-shared\fR
+ attribute is PTHREAD_PROCESS_PRIVATE.
+ .PP
+ The
+ \fIpthread_rwlockattr_getpshared()\fR
+ function obtains the value of the
+ \fIprocess-shared\fR
+ attribute from the initialised attributes object referenced by \fIattr\fR.
+ The
+ \fIpthread_rwlockattr_setpshared()\fR
+ function is used to set the
+ \fIprocess-shared\fR
+ attribute in an initialised attributes object referenced by attr.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_rwlockattr_setpshared()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .PP
+ Upon successful completion, the
+ \fIpthread_rwlockattr_getpshared()\fR
+ returns zero and stores the value of the
+ \fIprocess-shared\fR
+ attribute of \fIattr\fR into the object referenced by the
+ \fIpshared\fR parameter. Otherwise an error number is
+ returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_rwlockattr_getpshared()\fR
+ and
+ \fIpthread_rwlockattr_setpshared()\fR
+ functions may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by \fIattr\fR is invalid.
+ .PP
+ The
+ \fIpthread_rwlockattr_setpshared()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The new value specified for the attribute is outside the range
+ of legal values for
+ that attribute.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ Similar functions are being developed by IEEE PASC.
+ In keeping with its objective of ensuring that CAE
+ Specifications are fully aligned with formal standards, The Open Group
+ intends to add any new interfaces adopted by an official IEEE standard
+ in this area.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fI<pthread.h\fR>,
+ \fIpthread_rwlock_init()\fR,
+ \fIpthread_rwlock_unlock()\fR,
+ \fIpthread_rwlock_wrlock()\fR,
+ \fIpthread_rwlock_rdlock()\fR,
+ \fIpthread_rwlockattr_init()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_self\fR \- get calling thread's ID
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ pthread_t \fIpthread_self\fR\|(void);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_self()\fR
+ function returns the thread ID of the calling thread.
+ .SH "RETURN VALUE"
+ See DESCRIPTION above.
+ .SH "ERRORS"
+ No errors are defined.
+ .PP
+ The
+ \fIpthread_self()\fR
+ function will not return an error code of [EINTR].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_create()\fR,
+ \fIpthread_equal()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setcancelstate,\fR \fBpthread_setcanceltype,\fR \fBpthread_testcancel\fR
+ \- set cancelability state
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setcancelstate\fR\|(int \fIstate\fR, int *\fIoldstate\fR);
+ int \fIpthread_setcanceltype\fR\|(int \fItype\fR, int *\fIoldtype\fR);
+ void \fIpthread_testcancel\fR\|(void);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_setcancelstate()\fR
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ \fIstate\fR
+ and returns the previous cancelability state
+ at the location referenced by \fIoldstate\fR.
+ Legal values for
+ \fIstate\fR
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ \fItype\fR
+ and returns the previous cancelability type
+ at the location referenced by \fIoldtype\fR.
+ Legal values for
+ \fItype\fR
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+ .PP
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ \fImain()\fR
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+ .PP
+ The
+ \fIpthread_testcancel()\fR
+ function creates a cancellation point in the calling thread.
+ The
+ \fIpthread_testcancel()\fR
+ function has no effect if cancelability is disabled.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_setcancelstate()\fR
+ and
+ \fIpthread_setcanceltype()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_setcancelstate()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified state is not
+ \s-1PTHREAD_CANCEL_ENABLE\s0 or \s-1PTHREAD_CANCEL_DISABLE\s0.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified type is not \s-1PTHREAD_CANCEL_DEFERRED\s0
+ or \s-1PTHREAD_CANCEL_ASYNCHRONOUS\s0.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cancel()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setcancelstate,\fR \fBpthread_setcanceltype,\fR \fBpthread_testcancel\fR
+ \- set cancelability state
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setcancelstate\fR\|(int \fIstate\fR, int *\fIoldstate\fR);
+ int \fIpthread_setcanceltype\fR\|(int \fItype\fR, int *\fIoldtype\fR);
+ void \fIpthread_testcancel\fR\|(void);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_setcancelstate()\fR
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ \fIstate\fR
+ and returns the previous cancelability state
+ at the location referenced by \fIoldstate\fR.
+ Legal values for
+ \fIstate\fR
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ \fItype\fR
+ and returns the previous cancelability type
+ at the location referenced by \fIoldtype\fR.
+ Legal values for
+ \fItype\fR
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+ .PP
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ \fImain()\fR
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+ .PP
+ The
+ \fIpthread_testcancel()\fR
+ function creates a cancellation point in the calling thread.
+ The
+ \fIpthread_testcancel()\fR
+ function has no effect if cancelability is disabled.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_setcancelstate()\fR
+ and
+ \fIpthread_setcanceltype()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_setcancelstate()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified state is not
+ \s-1PTHREAD_CANCEL_ENABLE\s0 or \s-1PTHREAD_CANCEL_DISABLE\s0.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified type is not \s-1PTHREAD_CANCEL_DEFERRED\s0
+ or \s-1PTHREAD_CANCEL_ASYNCHRONOUS\s0.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cancel()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setconcurrency\fR \- get or set level of concurrency
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setconcurrency\fR\|(int \fInew_level\fR);
+ .SH "DESCRIPTION"
+ Refer to
+ \fIpthread_getconcurrency()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_getschedparam,\fR \fBpthread_setschedparam\fR
+ \- dynamic thread scheduling parameters access
+ (\fBREALTIME THREADS\fR)
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_getschedparam\fR\|(pthread_t \fIthread\fR, int *\fIpolicy\fR,
+ struct sched_param *\fIparam\fR);
+ int \fIpthread_setschedparam\fR\|(pthread_t \fIthread\fR, int \fIpolicy\fR,
+ const struct sched_param *\fIparam\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ allow the scheduling policy and scheduling parameters of individual threads
+ within a multi-threaded process to be retrieved and set.
+ For SCHED_FIFO and SCHED_RR,
+ the only required member of the
+ \fBsched_param\fR
+ structure is the priority
+ \fIsched_priority\fR.
+ For SCHED_OTHER,
+ the affected scheduling parameters are implementation-dependent.
+ .PP
+ The
+ \fIpthread_getschedparam()\fR
+ function retrieves the scheduling policy and scheduling parameters
+ for the thread whose thread ID is given by
+ \fIthread\fR
+ and stores those values in
+ \fIpolicy\fR
+ and
+ \fIparam\fR,
+ respectively.
+ The priority value returned from
+ \fIpthread_getschedparam()\fR
+ is the value specified by the most recent
+ \fIpthread_setschedparam()\fR
+ or
+ \fIpthread_create()\fR
+ call affecting the target thread,
+ and reflects any temporary adjustments to its priority
+ as a result of any priority inheritance or ceiling functions.
+ The
+ \fIpthread_setschedparam()\fR
+ function sets the scheduling policy
+ and associated scheduling parameters for the thread whose
+ thread ID is given by
+ \fIthread\fR
+ to the policy and associated parameters provided in
+ \fIpolicy\fR
+ and
+ \fIparam\fR,
+ respectively.
+ .PP
+ The
+ \fIpolicy\fR
+ parameter may have the value SCHED_OTHER,
+ that has implementation-dependent scheduling parameters,
+ SCHED_FIFO or SCHED_RR,
+ that have the single scheduling parameter,
+ \fIpriority.\fR
+ .PP
+ If the
+ \fIpthread_setschedparam()\fR
+ function fails, no scheduling parameters will be changed
+ for the target thread.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_getschedparam()\fR
+ and
+ \fIpthread_setschedparam()\fR
+ functions will fail if:
+ .Ip "[\s-1ENOSYS\s0]" 4
+ The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the
+ implementation does not support the function.
+ .PP
+ The
+ \fIpthread_getschedparam()\fR
+ function may fail if:
+ .Ip "[\s-1ESRCH\s0]" 4
+ The value specified by
+ \fIthread\fR
+ does not refer to a existing thread.
+ .PP
+ The
+ \fIpthread_setschedparam()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The value specified by
+ \fIpolicy\fR
+ or one of the scheduling parameters associated with
+ the scheduling policy
+ \fIpolicy\fR
+ is invalid.
+ .Ip "[\s-1ENOTSUP\s0]" 4
+ An attempt was made to set the policy or scheduling parameters to
+ an unsupported value.
+ .Ip "[\s-1EPERM\s0]" 4
+ The caller does not have the appropriate permission to set
+ either the scheduling parameters or the scheduling policy of the
+ specified thread.
+ .Ip "[\s-1EPERM\s0]" 4
+ The implementation does not allow the application to modify
+ one of the parameters to the value specified.
+ .Ip "[\s-1ESRCH\s0]" 4
+ The value specified by
+ \fIthread\fR
+ does not refer to a existing thread.
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIsched_setparam()\fR,
+ \fIsched_getparam()\fR,
+ \fIsched_setscheduler()\fR,
+ \fIsched_getscheduler()\fR,
+ \fI<pthread.h\fR>,
+ \fI<sched.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setspecific,\fR \fBpthread_getspecific\fR \- thread-specific data management
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setspecific\fR\|(pthread_key_t \fIkey\fR, const void *\fIvalue\fR);
+ void *\fIpthread_getspecific\fR\|(pthread_key_t \fIkey\fR);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_setspecific()\fR
+ function associates a thread-specific
+ \fIvalue\fR
+ with a
+ \fIkey\fR
+ obtained via a previous call to
+ \fIpthread_key_create()\fR.
+ Different threads may bind different values to the same key.
+ These values are typically pointers to blocks of dynamically allocated memory
+ that have been reserved for use by the calling thread.
+ .PP
+ The
+ \fIpthread_getspecific()\fR
+ function returns the value currently bound to the specified
+ \fIkey\fR
+ on behalf of the calling thread.
+ .PP
+ The effect of calling
+ \fIpthread_setspecific()\fR
+ or
+ \fIpthread_getspecific()\fR
+ with a
+ \fIkey\fR
+ value not obtained from
+ \fIpthread_key_create()\fR
+ or after
+ \fIkey\fR
+ has been deleted with
+ \fIpthread_key_delete()\fR
+ is undefined.
+ .PP
+ Both
+ \fIpthread_setspecific()\fR
+ and
+ \fIpthread_getspecific()\fR
+ may be called from a thread-specific data destructor function.
+ However, calling
+ \fIpthread_setspecific()\fR
+ from a destructor may result in lost storage or infinite loops.
+ .PP
+ Both functions may be implemented as macros.
+ .SH "RETURN VALUE"
+ The function
+ \fIpthread_getspecific()\fR
+ returns the thread-specific data value
+ associated with the given
+ \fIkey\fR.
+ If no thread-specific data value is associated with
+ \fIkey\fR,
+ then the value NULL is returned.
+ .PP
+ If successful, the
+ \fIpthread_setspecific()\fR
+ function returns zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_setspecific()\fR
+ function will fail if:
+ .Ip "[\s-1ENOMEM\s0]" 4
+ Insufficient memory exists to associate the value with the key.
+ .PP
+ The
+ \fIpthread_setspecific()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The key value is invalid.
+ .PP
+ No errors are returned from
+ \fIpthread_getspecific()\fR.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_key_create()\fR,
+ \fI<pthread.h\fR>.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_sigmask\fR \- examine and change blocked signals
+ .SH "SYNOPSIS"
+ #include <signal.h>
+ .PP
+ int \fIpthread_sigmask\fR\|(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR);
+ .SH "DESCRIPTION"
+ Refer to
+ \fIsigprocmask()\fR.
+ .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ .SH "NAME"
+ \fBpthread_setcancelstate,\fR \fBpthread_setcanceltype,\fR \fBpthread_testcancel\fR
+ \- set cancelability state
+ .SH "SYNOPSIS"
+ #include <pthread.h>
+ .PP
+ int \fIpthread_setcancelstate\fR\|(int \fIstate\fR, int *\fIoldstate\fR);
+ int \fIpthread_setcanceltype\fR\|(int \fItype\fR, int *\fIoldtype\fR);
+ void \fIpthread_testcancel\fR\|(void);
+ .SH "DESCRIPTION"
+ The
+ \fIpthread_setcancelstate()\fR
+ function atomically both sets the calling thread's cancelability
+ state to the indicated
+ \fIstate\fR
+ and returns the previous cancelability state
+ at the location referenced by \fIoldstate\fR.
+ Legal values for
+ \fIstate\fR
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function atomically both sets the calling thread's cancelability
+ type to the indicated
+ \fItype\fR
+ and returns the previous cancelability type
+ at the location referenced by \fIoldtype\fR.
+ Legal values for
+ \fItype\fR
+ are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
+ .PP
+ The cancelability state and type of any newly
+ created threads, including the thread in which
+ \fImain()\fR
+ was first invoked,
+ are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
+ respectively.
+ .PP
+ The
+ \fIpthread_testcancel()\fR
+ function creates a cancellation point in the calling thread.
+ The
+ \fIpthread_testcancel()\fR
+ function has no effect if cancelability is disabled.
+ .SH "RETURN VALUE"
+ If successful, the
+ \fIpthread_setcancelstate()\fR
+ and
+ \fIpthread_setcanceltype()\fR
+ functions return zero.
+ Otherwise, an error number is returned to indicate the error.
+ .SH "ERRORS"
+ The
+ \fIpthread_setcancelstate()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified state is not
+ \s-1PTHREAD_CANCEL_ENABLE\s0 or \s-1PTHREAD_CANCEL_DISABLE\s0.
+ .PP
+ The
+ \fIpthread_setcanceltype()\fR
+ function may fail if:
+ .Ip "[\s-1EINVAL\s0]" 4
+ The specified type is not \s-1PTHREAD_CANCEL_DEFERRED\s0
+ or \s-1PTHREAD_CANCEL_ASYNCHRONOUS\s0.
+ .PP
+ These functions will not return an error code of [\s-1EINTR\s0].
+ .SH "EXAMPLES"
+ None.
+ .SH "APPLICATION USAGE"
+ None.
+ .SH "FUTURE DIRECTIONS"
+ None.
+ .SH "SEE ALSO"
+ \fIpthread_cancel()\fR,
+ \fI<pthread.h\fR>.
+ 
+ .rn }` ''
+ .IX Title "pthread 3"
+ .IX Name "B<pthread> - POSIX.1c Threading API of GNU Pth"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "VERSION"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Subsection "Overview"
+ 
+ .IX Subsection "Supported Features"
+ 
+ .IX Subsection "Notes"
+ 
+ .IX Item "\fBNon-Preemptive Scheduling\fR"
+ 
+ .IX Item "\fBConflicts with Vendor Implementation\fR"
+ 
+ .IX Subsection "Further Reading"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "AUTHOR"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "1."
+ 
+ .IX Item "2."
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "\s-1PTHREAD_INHERIT_SCHED\s0"
+ 
+ .IX Item "\s-1PTHREAD_EXPLICIT_SCHED\s0"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "1."
+ 
+ .IX Item "2."
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "\s-1PTHREAD_INHERIT_SCHED\s0"
+ 
+ .IX Item "\s-1PTHREAD_EXPLICIT_SCHED\s0"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ETIMEDOUT\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ETIMEDOUT\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "o"
+ 
+ .IX Item "o"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_NORMAL\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_ERRORCHECK\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_RECURSIVE\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_DEFAULT\s0"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_NORMAL\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_ERRORCHECK\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_RECURSIVE\s0"
+ 
+ .IX Item "\s-1PTHREAD_MUTEX_DEFAULT\s0"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Item "[\s-1EAGAIN\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EBUSY\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EDEADLK\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOSYS\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1ENOTSUP\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1EPERM\s0]"
+ 
+ .IX Item "[\s-1ESRCH\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1ENOMEM\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_"
+ 
+ .IX Header "NAME"
+ 
+ .IX Header "SYNOPSIS"
+ 
+ .IX Header "DESCRIPTION"
+ 
+ .IX Header "RETURN VALUE"
+ 
+ .IX Header "ERRORS"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Item "[\s-1EINVAL\s0]"
+ 
+ .IX Header "EXAMPLES"
+ 
+ .IX Header "APPLICATION USAGE"
+ 
+ .IX Header "FUTURE DIRECTIONS"
+ 
+ .IX Header "SEE ALSO"
+

CVSTrac 2.0.1