Index: ossp-pkg/pth/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/pth/ChangeLog,v rcsdiff -q -kk '-r1.524' '-r1.525' -u '/v/ossp/cvs/ossp-pkg/pth/ChangeLog,v' 2>/dev/null --- ChangeLog 2000/08/01 06:13:15 1.524 +++ ChangeLog 2000/08/18 07:39:08 1.525 @@ -21,6 +21,13 @@ Changes between 1.4a3 and 1.4a4 (29-Jul-2000 to xx-Aug-2000) + *) Fixed pthread.pod: the newer pod2man versions seems to dislike + embedded comments, so I moved them to the top of the file. + [Ralf S. Engelschall] + + *) Changed CVS URL in HACKING document. + [Ralf S. Engelschall] + *) Mention http://www.mail-archive.com/pth-users@gnu.org/ in pth.pod and SUPPORT document. [Ralf S. Engelschall] Index: ossp-pkg/pth/README RCS File: /v/ossp/cvs/ossp-pkg/pth/README,v rcsdiff -q -kk '-r1.187' '-r1.188' -u '/v/ossp/cvs/ossp-pkg/pth/README,v' 2>/dev/null --- README 2000/07/29 14:40:25 1.187 +++ README 2000/08/18 07:39:09 1.188 @@ -5,7 +5,7 @@ |_| \__|_| |_| the impossible.'' GNU Pth - The GNU Portable Threads - Version 1.4a3 (29-Jul-2000) + Version 1.4a3 (18-Aug-2000) ABSTRACT Index: ossp-pkg/pth/pth-config.1 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pth-config.1,v rcsdiff -q -kk '-r1.125' '-r1.126' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pth-config.1,v' 2>/dev/null --- pth-config.1 2000/07/18 09:03:20 1.125 +++ pth-config.1 2000/08/18 07:39:09 1.126 @@ -2,7 +2,7 @@ ''' $RCSfile$$Revision$$Date$ ''' ''' $Log$ -''' Revision 1.125 2000/07/18 09:03:20 rse +''' Revision 1.126 2000/08/18 07:39:09 rse ''' *** empty log message *** ''' ''' @@ -96,7 +96,7 @@ .nr % 0 .rr F .\} -.TH PTH-CONFIG 1 "18-Jul-2000" "GNU Pth 1.4a3" "GNU Portable Threads" +.TH PTH-CONFIG 1 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" .UC .if n .hy 0 .if n .na @@ -193,7 +193,7 @@ .SH "NAME" \fBpth-config\fR \- Pth library build utility .SH "VERSION" -GNU Pth 1.4a3 (18-Jul-2000) +GNU Pth 1.4a3 (18-Aug-2000) .SH "SYNOPSIS" \fBpth-config\fR [\fB--help\fR] Index: ossp-pkg/pth/pth.3 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pth.3,v rcsdiff -q -kk '-r1.220' '-r1.221' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pth.3,v' 2>/dev/null --- pth.3 2000/07/18 09:03:20 1.220 +++ pth.3 2000/08/18 07:39:09 1.221 @@ -2,7 +2,7 @@ ''' $RCSfile$$Revision$$Date$ ''' ''' $Log$ -''' Revision 1.220 2000/07/18 09:03:20 rse +''' Revision 1.221 2000/08/18 07:39:09 rse ''' *** empty log message *** ''' ''' @@ -96,7 +96,7 @@ .nr % 0 .rr F .\} -.TH pth 3 "18-Jul-2000" "GNU Pth 1.4a3" "GNU Portable Threads" +.TH pth 3 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" .UC .if n .hy 0 .if n .na @@ -193,7 +193,7 @@ .SH "NAME" \fBpth\fR \- GNU Portable Threads .SH "VERSION" -GNU Pth 1.4a3 (18-Jul-2000) +GNU Pth 1.4a3 (18-Aug-2000) .SH "SYNOPSIS" .Ip "\fBGlobal Library Management\fR" 4 pth_init, @@ -1992,8 +1992,9 @@ `\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. +\fIpth-users@gnu.org\fR. Currently (as of August 2000) you can reach about +110 Pth users on this mailing list. Old postings you can find at +\fIhttp://www.mail-archive.com/pth-users@gnu.org/\fR. .SH "SEE ALSO" .Sh "Related Web Locations" `comp.programming.threads Newsgroup Archive\*(R', Index: ossp-pkg/pth/pth_vers.c RCS File: /v/ossp/cvs/ossp-pkg/pth/pth_vers.c,v rcsdiff -q -kk '-r1.134' '-r1.135' -u '/v/ossp/cvs/ossp-pkg/pth/pth_vers.c,v' 2>/dev/null --- pth_vers.c 2000/07/29 14:40:25 1.134 +++ pth_vers.c 2000/08/18 07:39:09 1.135 @@ -34,11 +34,11 @@ pth_internal_version_t pth_internal_version = { 0x104003, "1.4a3", - "1.4a3 (29-Jul-2000)", - "This is GNU Pth, Version 1.4a3 (29-Jul-2000)", - "GNU Pth 1.4a3 (29-Jul-2000)", + "1.4a3 (18-Aug-2000)", + "This is GNU Pth, Version 1.4a3 (18-Aug-2000)", + "GNU Pth 1.4a3 (18-Aug-2000)", "GNU Pth/1.4a3", - "@(#)GNU Pth 1.4a3 (29-Jul-2000)", + "@(#)GNU Pth 1.4a3 (18-Aug-2000)", "$Id$" }; Index: ossp-pkg/pth/pthread-config.1 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pthread-config.1,v rcsdiff -q -kk '-r1.91' '-r1.92' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pthread-config.1,v' 2>/dev/null --- pthread-config.1 2000/07/18 09:03:20 1.91 +++ pthread-config.1 2000/08/18 07:39:09 1.92 @@ -2,7 +2,7 @@ ''' $RCSfile$$Revision$$Date$ ''' ''' $Log$ -''' Revision 1.91 2000/07/18 09:03:20 rse +''' Revision 1.92 2000/08/18 07:39:09 rse ''' *** empty log message *** ''' ''' @@ -96,7 +96,7 @@ .nr % 0 .rr F .\} -.TH PTHREAD-CONFIG 1 "18-Jul-2000" "GNU Pth 1.4a3" "POSIX Threading API of GNU Pth" +.TH PTHREAD-CONFIG 1 "18-Aug-2000" "GNU Pth 1.4a3" "POSIX Threading API of GNU Pth" .UC .if n .hy 0 .if n .na @@ -193,7 +193,7 @@ .SH "NAME" \fBpthread-config\fR \- Pth pthread library build utility .SH "VERSION" -GNU Pth 1.4a3 (18-Jul-2000) +GNU Pth 1.4a3 (18-Aug-2000) .SH "SYNOPSIS" \fBpthread-config\fR [\fB--help\fR] Index: ossp-pkg/pth/pthread.3 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pthread.3,v rcsdiff -q -kk '-r1.95' '-r1.96' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pthread.3,v' 2>/dev/null --- pthread.3 2000/07/18 09:03:20 1.95 +++ pthread.3 2000/08/18 07:39:09 1.96 @@ -2,7 +2,7 @@ ''' $RCSfile$$Revision$$Date$ ''' ''' $Log$ -''' Revision 1.95 2000/07/18 09:03:20 rse +''' Revision 1.96 2000/08/18 07:39:09 rse ''' *** empty log message *** ''' ''' @@ -96,7 +96,7 @@ .nr % 0 .rr F .\} -.TH pthread 3 "18-Jul-2000" "GNU Pth 1.4a3" "POSIX Threading API of GNU Pth" +.TH pthread 3 "18-Aug-2000" "GNU Pth 1.4a3" "POSIX Threading API of GNU Pth" .UC .if n .hy 0 .if n .na @@ -193,7 +193,7 @@ .SH "NAME" \fBpthread\fR \- POSIX.1c Threading API of GNU Pth .SH "VERSION" -GNU Pth 1.4a3 (18-Jul-2000) +GNU Pth 1.4a3 (18-Aug-2000) .SH "SYNOPSIS" \fBApplication Makefiles:\fR .PP @@ -283,11 +283,6 @@ \& 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 Index: ossp-pkg/pth/pthread.pod RCS File: /v/ossp/cvs/ossp-pkg/pth/pthread.pod,v co -q -kk -p'1.19' '/v/ossp/cvs/ossp-pkg/pth/pthread.pod,v' | diff -u /dev/null - -L'ossp-pkg/pth/pthread.pod' 2>/dev/null --- ossp-pkg/pth/pthread.pod +++ - 2024-05-09 09:25:25.233882591 +0200 @@ -0,0 +1,9843 @@ +## +## GNU Pth - The GNU Portable Threads +## Copyright (c) 1999-2000 Ralf S. Engelschall +## +## 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 . +## +## pthread.pod: POSIX.1c Threads ("Pthreads") manual page for Pth +## +## This manual page includes parts from: +## 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. +## +## + # ``The trouble with computers is that they + # do what you tell them, not what you want.'' + +=pod + +=head1 NAME + +B - POSIX.1c Threading API of GNU Pth + +=head1 VERSION + +GNU Pth PTH_VERSION_STR + +=head1 SYNOPSIS + +B + + # manually + CFLAGS=-I/path/to/pth/include + LDFLAGS=-L/path/to/pth/lib + LIBS=-lpthread + + # automatically + CFLAGS=`pthread-config --cflags` + LDFLAGS=`pthread-config --ldflags` + LIBS=`pthread-config --libs` + +B + + #include + +=head1 DESCRIPTION + +=head2 Overview + +This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of +GNU Portable Threads (B). This API is commonly known as ``I'' or in short ``I''. It is provided by B with +the intention of backward compatibility to existing multithreaded +applications. It is implemented by mapping the various Pthread API +functions to the corresponding native B API functions. + +=head2 Supported Features + +The following defined feature macros in C indicate supported +features: + + #define _POSIX_THREADS + #define _POSIX_THREAD_ATTR_STACKADDR + #define _POSIX_THREAD_ATTR_STACKSIZE + +The following undefined feature macros in C indicate (still) +unsupported features: + + #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 + +=head2 Notes + +A few notes which you should keep in mind when working with the B Pthread +API. + +=over 4 + +=item B + +First you have to always remember when working with this Pthread library that +it uses non-preemptive scheduling, because it is directly based on B +(B for portability reasons is a pure non-preemptive thread scheduling +system). So there is no implicit yielding of execution control unless you can +C 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. + +=item B + +There can be a conflict between the B C header and a possibly +existing vendor C header which was implicitly included +by some standard vendor headers (like C). When this +occurs try to ``C<#define>'' header-dependent values which prevent the +inclusion of the vendor header. + +=back + +=head2 Further Reading + +There is ``I'', from I of 1997 under +http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html. This is +a very complete publically available description of the Pthread API. For +convinience reasons, a translated copy of these freely available HTML +pages are appended to this manpage below. These are I. + +Second, you can also buy the official standard from IEEE. It is the IEEE +POSIX 1003.1c-1995 standard (also known as ISO/IEC 9945-1:1996), which +is available as part of the ANSI/IEEE 1003.1, 1996 edition, standard. + +Finally you can look at the files C and C in the B +source tree for details of the implementation, of course. + +=head1 SEE ALSO + +pthread-config(1), pth(3). + +=head1 AUTHOR + + Ralf S. Engelschall + rse@engelschall.com + www.engelschall.com + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - threads + +=head1 SYNOPSIS + +#include + +=head1 DESCRIPTION + +The +I<> +header defines the following symbols: + + 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 + +The B, B, B, +B, B, B, +B, B, B and +B types are defined as described in I<>. + +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. + + 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); + +Inclusion of the I<> header will make visible symbols defined +in the headers I<> and I<>. + +=head1 APPLICATION USAGE + +An interpretation request has been filed with IEEE PASC concerning +requirements for visibility of symbols in this header. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - register fork handlers + +=head1 SYNOPSIS + +#include + +#include + +int pthread_atfork(void (*I)(void), void (*I)(void), +void (*I)(void)); + +=head1 DESCRIPTION + +The I function declares fork handlers to be called +before and after I, in the context of the thread that called +I. The I fork handler is called before I +processing commences. The I fork handle is called after +I processing completes in the parent process. The I fork +handler is called after I processing completes in the child +process. If no handling is desired at one or more of these three points, +the corresponding fork handler address(es) may be set to NULL. + +The order of calls to I is significant. The I +and I fork handlers are called in the order in which they were +established by calls to I. The I fork +handlers are called in the opposite order. + +=head1 RETURN VALUE + +Upon successful completion, I returns a value of zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The I function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient table space exists to record the fork handler addresses. + +=back + +The I function will not return an error code of +[EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<> + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy threads attribute object + +=head1 SYNOPSIS + +#include + +int pthread_attr_init(pthread_attr_t *I); + +int pthread_attr_destroy(pthread_attr_t *I); + +=head1 DESCRIPTION + +The function I initialises a thread attributes +object I with the default value for all of the individual +attributes used by a given implementation. + +The resulting attribute object (possibly modified by setting individual +attribute values), when used by I, defines the +attributes of the thread created. A single attributes object can be used +in multiple simultaneous calls to I. + +The I function is used to destroy a thread +attributes object. An implementation may cause I +to set I to an implementation-dependent invalid value. The +behaviour of using the attribute after it has been destroyed is +undefined. + +=head1 RETURN VALUE + +Upon successful completion, I and +I return a value of 0. Otherwise, an error +number is returned to indicate the error. + +=head1 ERRORS + +The I function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the thread attributes object. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get detachstate attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setdetachstate(pthread_attr_t *I, int I); + +int pthread_attr_getdetachstate(const pthread_attr_t *I, int *I); + +=head1 DESCRIPTION + +The I 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 I or I +function is an error. + +The I and +I, respectively, set and get the +I attribute in the I object. + +The I can be set to either PTHREAD_CREATE_DETACHED or +PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes +all threads created with I to be in the detached state, whereas +using a value of PTHREAD_CREATE_JOINABLE causes all threads created +with I to be in the joinable state. The default value of the +I attribute is PTHREAD_CREATE_JOINABLE . + +=head1 RETURN VALUE + +Upon successful completion, I and +I return a value of 0. Otherwise, an +error number is returned to indicate the error. + +The I function stores the value of the +I attribute in I if successful. + +=head1 ERRORS + +The I function will fail if: + +=over 4 + +=item [EINVAL] + +The value of I was not valid + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - +get or set the thread guardsize attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_getguardsize(const pthread_attr_t I<*attr>, size_t +I<*guardsize>); int pthread_attr_setguardsize(pthread_attr_t I<*attr>, +size_t I); + +=head1 DESCRIPTION + +The I attribute controls the size of the guard area for the +created thread's stack. The I 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). + +The I attribute is provided to the application +for two reasons: + +=over 4 + +=item 1. + +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. + +=item 2. + +When threads allocate large data structures on the stack, +large guard areas may be needed to detect stack overflow. + +=back + +The I function gets the I +attribute in the I object. This attribute is returned in the +I parameter. + +The I function sets the I +attribute in the I object. The new value of this attribute is +obtained from the I parameter. If I is zero, +a guard area will not be provided for threads created with I. +If I is greater than zero, a guard area of at least size +I bytes is provided for each thread created with I. + +A conforming implementation is permitted to round up the value +contained in I to a multiple of the configurable system +variable PAGESIZE (see I<>). If an implementation rounds +up the value of I to a multiple of PAGESIZE, a call to +I specifying I will store in the +I parameter the guard size specified by the previous +I function call. + +The default value of the I attribute is PAGESIZE bytes. The +actual value of PAGESIZE is implementation-dependent and may not be the +same on all implementations. + +If the I attribute has been set (that is, the caller is +allocating and managing its own thread stacks), the I +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. + +=head1 RETURN VALUE + +If successful, the I and +I functions return zero. Otherwise, an +error number is returned to indicate the error. + +=head1 ERRORS + +The I and I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The attribute I is invalid. + +=item [EINVAL] + +The parameter I is invalid. + +=item [EINVAL] + +The parameter I contains an invalid value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get inheritsched attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setinheritsched(pthread_attr_t *I, +int I); +int pthread_attr_getinheritsched(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The functions I and +I, respectively, set and get the +I attribute in the I argument. + +When the attribute objects are used by I, the +I attribute determines how the other scheduling attributes +of the created thread are to be set: + +=over 4 + +=item PTHREAD_INHERIT_SCHED + +Specifies that the scheduling policy and associated attributes are to +be inherited from the creating thread, and the scheduling attributes in +this I argument are to be ignored. + +=item PTHREAD_EXPLICIT_SCHED + +Specifies that the scheduling policy and associated attributes +are to be set to the corresponding values from this attribute object. + +=back + +The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined +in the header I<>. + +=head1 RETURN VALUE + +If successful, the I and +I functions return zero. Otherwise, an +error number is returned to indicate the error. + +=head1 ERRORS + +The I and +I functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with the +specified attributes using I. Using these routines +does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get schedparam attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setschedparam(pthread_attr_t *I, const struct sched_param *I); + +int pthread_attr_getschedparam(const pthread_attr_t *I, struct sched_param *I); + +=head1 DESCRIPTION + +The functions I and +I, respectively, set and get the +scheduling parameter attributes in the I argument. The contents of +the I structure are defined in I<>. For the SCHED_FIFO +and SCHED_RR policies, the only required member of I is +I. + +=head1 RETURN VALUE + +If successful, the I and +I functions return zero. Otherwise, an +error number is returned to indicate the error. + +=head1 ERRORS + +The I function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +The +I +and +I +functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with the +specified attributes using I. Using these routines +does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get schedpolicy attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setschedpolicy(pthread_attr_t *I, int I); +int pthread_attr_getschedpolicy(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The functions I and +I, respectively, set and get the +I attribute in the I argument. + +The supported values of I include SCHED_FIFO, SCHED_RR and +SCHED_OTHER, which are defined by the header I<>. 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. + +=head1 RETURN VALUE + +If successful, the I and +I functions return zero. Otherwise, an +error number is returned to indicate the error. + +=head1 ERRORS + +The I and +I functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The I function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with the +specified attributes using I. Using these routines +does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get contentionscope attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setscope(pthread_attr_t *I, int I); +int pthread_attr_getscope(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The I and I functions +are used to set and get the I attribute in the I +object. + +The I 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 I<>. + +=head1 RETURN VALUE + +If successful, the I and +I functions return zero. Otherwise, an error +number is returned to indicate the error. + +=head1 ERRORS + +The I and I functions +will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I, +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with the +specified attributes using I. Using these routines +does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get stackaddr attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setstackaddr(pthread_attr_t *I, void *I); + +int pthread_attr_getstackaddr(const pthread_attr_t *I, void **I); + +=head1 DESCRIPTION + +The functions I and +I, respectively, set and get the thread +creation I attribute in the I object. + +The I 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. + +=head1 RETURN VALUE + +Upon successful completion, I and +I return a value of 0. Otherwise, an error +number is returned to indicate the error. + +The I function stores the I +attribute value in I if successful. + +=head1 ERRORS + +No errors are defined. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get stacksize attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setstacksize(pthread_attr_t *I, size_t I); +int pthread_attr_getstacksize(const pthread_attr_t *I, +size_t *I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the thread creation +I +attribute in the +I +object. + +The +I +attribute defines the minimum stack size (in bytes) allocated for +the created threads stack. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return a value of 0. +Otherwise, an error number is returned to indicate the error. +The +I +function stores the +I +attribute value in +I +if successful. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The value of +I +is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy threads attribute object + +=head1 SYNOPSIS + +#include + +int pthread_attr_init(pthread_attr_t *I); +int pthread_attr_destroy(pthread_attr_t *I); + +=head1 DESCRIPTION + +The function +I +initialises a thread attributes object +I +with the default value for all of the individual attributes +used by a given implementation. + +The resulting attribute object +(possibly modified by setting individual attribute values), +when used by +I, +defines the attributes of the thread created. +A single attributes object can be used in multiple simultaneous calls to +I. + +The +I +function is used to destroy a thread attributes object. +An implementation may cause +I +to set +I +to an implementation-dependent invalid value. +The behaviour of using the attribute after it has been destroyed is undefined. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return a value of 0. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the thread attributes object. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get detachstate attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setdetachstate(pthread_attr_t *I, int I); +int pthread_attr_getdetachstate(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +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 +I +or +I +function is an error. + +The +I +and +I, +respectively, set and get the +I +attribute in the +I +object. + +The +I +can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. +A value of PTHREAD_CREATE_DETACHED causes all threads created with +I +to be in the detached state, whereas using a value of +PTHREAD_CREATE_JOINABLE +causes all threads created with +I +to be in the joinable state. +The default value of the +I +attribute is +PTHREAD_CREATE_JOINABLE . + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return a value of 0. +Otherwise, an error number is returned to indicate the error. + +The +I +function stores the value of the +I +attribute in +I +if successful. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The value of +I +was not valid + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - +get or set the thread guardsize attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_getguardsize(const pthread_attr_t I<*attr>, +size_t I<*guardsize>); +int pthread_attr_setguardsize(pthread_attr_t I<*attr>, +size_t I); + +=head1 DESCRIPTION + +The I attribute controls the size +of the guard area for the created thread's stack. The I +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). + +The I attribute is provided to the application +for two reasons: + +=over 4 + +=item 1. + +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. + +=item 2. + +When threads allocate large data structures on the stack, +large guard areas may be needed to detect stack overflow. + +=back + +The +I +function gets the +I attribute in the I object. This attribute is +returned in the I parameter. + +The +I +function sets the +I attribute in the I object. The new value of +this attribute is obtained from the I parameter. +If I is zero, a guard area will not be +provided for threads created with I. If I is +greater +than zero, a guard area of at least size I +bytes is provided for each thread created with I. + +A conforming implementation is permitted to round up +the value contained in I to a multiple +of the configurable system variable PAGESIZE (see +I<>). +If an implementation rounds up the +value of I to a multiple of PAGESIZE, a call to +I +specifying I will +store in the I parameter the guard size specified by the +previous +I +function call. + +The default value of the I attribute is PAGESIZE bytes. +The actual value of PAGESIZE is +implementation-dependent and may not be the same on all implementations. + +If the I attribute has been set (that is, the caller +is allocating and managing its own thread stacks), the +I 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. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The attribute I is invalid. + +=item [EINVAL] + +The parameter I is invalid. + +=item [EINVAL] + +The parameter I contains an invalid value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get inheritsched attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setinheritsched(pthread_attr_t *I, +int I); +int pthread_attr_getinheritsched(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the +I +attribute in the +I +argument. + +When the attribute objects are used by +I, +the +I +attribute determines how the other scheduling attributes of +the created thread are to be set: + +=over 4 + +=item PTHREAD_INHERIT_SCHED + +Specifies that the scheduling policy and associated attributes +are to be inherited from the creating thread, and the scheduling +attributes in this +I +argument are to be ignored. + +=item PTHREAD_EXPLICIT_SCHED + +Specifies that the scheduling policy and associated attributes +are to be set to the corresponding values from this attribute object. + +=back + +The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED +are defined in the header +I<>. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with +the specified attributes using +I. +Using these routines does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get schedparam attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setschedparam(pthread_attr_t *I, +const struct sched_param *I); +int pthread_attr_getschedparam(const pthread_attr_t *I, +struct sched_param *I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the scheduling parameter +attributes in the +I +argument. +The contents of the +I +structure are defined in +I<>. +For the SCHED_FIFO and SCHED_RR policies, +the only required member of +I +is +I. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +The +I +and +I +functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with +the specified attributes using +I. +Using these routines does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get schedpolicy attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setschedpolicy(pthread_attr_t *I, int I); +int pthread_attr_getschedpolicy(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the +I +attribute in the +I +argument. + +The supported values of +I +include SCHED_FIFO, SCHED_RR and SCHED_OTHER, +which are defined by the header +I<>. +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. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with +the specified attributes using +I. +Using these routines does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get contentionscope attribute +(B) + +=head1 SYNOPSIS + +#include + +int pthread_attr_setscope(pthread_attr_t *I, int I); +int pthread_attr_getscope(const pthread_attr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +and +I +functions are used to set and get the +I +attribute in the +I +object. + +The +I +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 +I<>. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I, +function may fail if: + +=over 4 + +=item [EINVAL] + +The value of the attribute being set is not valid. + +=item [ENOTSUP] + +An attempt was made to set the attribute to an unsupported value. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +After these attributes have been set, a thread can be created with +the specified attributes using +I. +Using these routines does not affect the current running thread. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get stackaddr attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setstackaddr(pthread_attr_t *I, void *I); +int pthread_attr_getstackaddr(const pthread_attr_t *I, +void **I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the thread creation +I +attribute in the +I +object. + +The +I +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. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return a value of 0. +Otherwise, an error number is returned to indicate the error. + +The +I +function stores the +I +attribute value in +I +if successful. + +=head1 ERRORS + +No errors are defined. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get stacksize attribute + +=head1 SYNOPSIS + +#include + +int pthread_attr_setstacksize(pthread_attr_t *I, size_t I); +int pthread_attr_getstacksize(const pthread_attr_t *I, +size_t *I); + +=head1 DESCRIPTION + +The functions +I +and +I, +respectively, set and get the thread creation +I +attribute in the +I +object. + +The +I +attribute defines the minimum stack size (in bytes) allocated for +the created threads stack. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return a value of 0. +Otherwise, an error number is returned to indicate the error. +The +I +function stores the +I +attribute value in +I +if successful. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The value of +I +is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - cancel execution of a thread + +=head1 SYNOPSIS + +#include + +int pthread_cancel(pthread_t I); + +=head1 DESCRIPTION + +The +I +function requests that +I +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 +I +are called. +When the last cancellation cleanup handler returns, +the thread-specific data destructor functions are called for +I. +When the last destructor function returns, +I +is terminated. + +The cancellation processing in the target thread runs asynchronously +with respect to the calling thread returning from +I. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [ESRCH] + +No thread could be found corresponding to that specified +by the given thread ID. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - establish cancellation handlers + +=head1 SYNOPSIS + +#include + +void pthread_cleanup_push(void (*I)(void*), void *I); +void pthread_cleanup_pop(int I); + +=head1 DESCRIPTION + +The +I +function pushes the specified cancellation cleanup handler +I +onto the calling thread's cancellation cleanup stack. +The cancellation cleanup handler is popped from the +cancellation cleanup stack and invoked with the argument +I +when: (a) the thread exits (that is, calls +I), +(b) the thread acts upon a cancellation request, or +(c) the thread calls +I +with a non-zero +I +argument. + +The +I +function removes the routine at the top of the calling thread's +cancellation cleanup stack and optionally invokes it (if +I +is non-zero). + +These functions may be implemented as macros and will +appear as statements and in pairs within the same lexical scope (that is, the +I +macro may be thought to expand to a token list whose first +token is +B<`{'> +with +I +expanding to a token list whose last token is the corresponding +B<`}'>. + +The effect of calling +I +or +I +is undefined if there have been any calls to +I +or +I +made without the matching call +since the jump buffer was filled. +The effect of calling +I +or +I +from inside a cancellation cleanup handler is also +undefined unless the jump buffer was also filled in the +cancellation cleanup handler. + +=head1 RETURN VALUE + +The +I +and +I +functions return no value. + +=head1 ERRORS + +No errors are defined. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - establish cancellation handlers + +=head1 SYNOPSIS + +#include + +void pthread_cleanup_push(void (*I)(void*), void *I); +void pthread_cleanup_pop(int I); + +=head1 DESCRIPTION + +The +I +function pushes the specified cancellation cleanup handler +I +onto the calling thread's cancellation cleanup stack. +The cancellation cleanup handler is popped from the +cancellation cleanup stack and invoked with the argument +I +when: (a) the thread exits (that is, calls +I), +(b) the thread acts upon a cancellation request, or +(c) the thread calls +I +with a non-zero +I +argument. + +The +I +function removes the routine at the top of the calling thread's +cancellation cleanup stack and optionally invokes it (if +I +is non-zero). + +These functions may be implemented as macros and will +appear as statements and in pairs within the same lexical scope (that is, the +I +macro may be thought to expand to a token list whose first +token is +B<`{'> +with +I +expanding to a token list whose last token is the corresponding +B<`}'>. + +The effect of calling +I +or +I +is undefined if there have been any calls to +I +or +I +made without the matching call +since the jump buffer was filled. +The effect of calling +I +or +I +from inside a cancellation cleanup handler is also +undefined unless the jump buffer was also filled in the +cancellation cleanup handler. + +=head1 RETURN VALUE + +The +I +and +I +functions return no value. + +=head1 ERRORS + +No errors are defined. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - signal or broadcast a +condition + +=head1 SYNOPSIS + +#include + +int pthread_cond_signal(pthread_cond_t *I); +int pthread_cond_broadcast(pthread_cond_t *I); + +=head1 DESCRIPTION + +These two functions are used to unblock +threads blocked on a condition variable. + +The +I +call unblocks at least one of the threads that are blocked on the +specified condition variable +I +(if any threads are blocked on +I). + +The +I +call unblocks all threads currently blocked on the specified condition variable +I. + +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 +I +or +I +returns from its call to +I +or +I, +the thread owns the mutex with which it called +I +or +I. +The thread(s) that are unblocked contend for the mutex +according to the scheduling policy (if applicable), +and as if each had called +I. + +The +I +or +I +functions may be called by a thread whether or not it +currently owns the mutex that threads calling +I +or +I +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 +I +or +I. + +The +I +and +I +functions have no effect if there are no threads +currently blocked on +I. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value +I +does not refer to an initialised condition variable. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - initialise and destroy +condition variables + +=head1 SYNOPSIS + +#include + +int pthread_cond_init(pthread_cond_t *I, +const pthread_condattr_t *I); +int pthread_cond_destroy(pthread_cond_t *I); +pthread_cond_t I = PTHREAD_COND_INITIALIZER; + +=head1 DESCRIPTION + +The function +I +initialises the condition variable referenced by +I +with attributes referenced by +I. +If +I +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. + +Attempting to initialise an already initialised +condition variable +results in undefined behaviour. + +The function +I +destroys the given condition variable specified by +I; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed condition variable object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +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. + +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 +I +with parameter +I +specified as NULL, except that no error checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other +than memory) to initialise another condition variable. + +=item [ENOMEM] + +Insufficient memory exists to initialise the condition variable. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt +to re-initialise the object referenced by +I, +a previously initialised, but +not yet destroyed, condition variable. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + + + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy +the object referenced by +I +while it is referenced +(for example, while being used in a +I +or +I) +by another thread. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - initialise and destroy +condition variables + +=head1 SYNOPSIS + +#include + +int pthread_cond_init(pthread_cond_t *I, +const pthread_condattr_t *I); +int pthread_cond_destroy(pthread_cond_t *I); +pthread_cond_t I = PTHREAD_COND_INITIALIZER; + +=head1 DESCRIPTION + +The function +I +initialises the condition variable referenced by +I +with attributes referenced by +I. +If +I +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. + +Attempting to initialise an already initialised +condition variable +results in undefined behaviour. + +The function +I +destroys the given condition variable specified by +I; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed condition variable object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +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. + +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 +I +with parameter +I +specified as NULL, except that no error checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other +than memory) to initialise another condition variable. + +=item [ENOMEM] + +Insufficient memory exists to initialise the condition variable. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt +to re-initialise the object referenced by +I, +a previously initialised, but +not yet destroyed, condition variable. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + + + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy +the object referenced by +I +while it is referenced +(for example, while being used in a +I +or +I) +by another thread. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - signal or broadcast a +condition + +=head1 SYNOPSIS + +#include + +int pthread_cond_signal(pthread_cond_t *I); +int pthread_cond_broadcast(pthread_cond_t *I); + +=head1 DESCRIPTION + +These two functions are used to unblock +threads blocked on a condition variable. + +The +I +call unblocks at least one of the threads that are blocked on the +specified condition variable +I +(if any threads are blocked on +I). + +The +I +call unblocks all threads currently blocked on the specified condition variable +I. + +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 +I +or +I +returns from its call to +I +or +I, +the thread owns the mutex with which it called +I +or +I. +The thread(s) that are unblocked contend for the mutex +according to the scheduling policy (if applicable), +and as if each had called +I. + +The +I +or +I +functions may be called by a thread whether or not it +currently owns the mutex that threads calling +I +or +I +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 +I +or +I. + +The +I +and +I +functions have no effect if there are no threads +currently blocked on +I. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value +I +does not refer to an initialised condition variable. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - wait on a condition + +=head1 SYNOPSIS + +#include + +int pthread_cond_wait(pthread_cond_t *I, pthread_mutex_t *I); +int pthread_cond_timedwait(pthread_cond_t *I, +pthread_mutex_t *I, const struct timespec *I); + +=head1 DESCRIPTION + +The +I +and +I +functions are used to block on a condition variable. +They are called with +I +locked by the calling thread or undefined behaviour will result. + +These functions atomically release +I +and cause the calling thread to block on the condition variable +I; +atomically here means "atomically with respect to access by another +thread to the mutex and then the condition variable". +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 +I +or +I +in that thread behaves as if it were issued +after the about-to-block thread has blocked. + +Upon successful return, the mutex has been +locked and is owned by the calling thread. + +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 +I +or +I +functions may occur. +Since the return from +I +or +I +does not imply anything about the value of this predicate, +the predicate should be re-evaluated upon such return. + +The effect of using more than one mutex for concurrent +I +or +I +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. + +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 +I +or +I, +but at that point +notices the cancellation request and instead of returning to the caller +of +I +or +I, +starts the thread cancellation activities, which includes calling +cancellation cleanup handlers. + +A thread that has been unblocked because it has been +canceled while blocked in a call to +I +or +I +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. + +The +I +function is the same as +I +except that +an error is returned +if the absolute time specified by +I +passes (that is, system time equals or exceeds +I) +before the condition +I +is signaled or broadcasted, +or if the absolute time specified by +I +has already been passed at the time of the call. +When such time-outs occur, +I +will nonetheless release +and reacquire the mutex referenced by +I. +The function +I +is also a cancellation point. + +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. + +=head1 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 +I +or the condition variable specified by +I. + +Upon successful completion, a value of zero is returned. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ETIMEDOUT] + +The time specified by +I +to +I +has passed. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I, +I, +or +I +is invalid. + +=item [EINVAL] + +Different mutexes were supplied for concurrent +I +or +I +operations on the same condition variable. + +=item [EINVAL] + +The mutex was not owned by the current thread at the time of the call. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - wait on a condition + +=head1 SYNOPSIS + +#include + +int pthread_cond_wait(pthread_cond_t *I, pthread_mutex_t *I); +int pthread_cond_timedwait(pthread_cond_t *I, +pthread_mutex_t *I, const struct timespec *I); + +=head1 DESCRIPTION + +The +I +and +I +functions are used to block on a condition variable. +They are called with +I +locked by the calling thread or undefined behaviour will result. + +These functions atomically release +I +and cause the calling thread to block on the condition variable +I; +atomically here means "atomically with respect to access by another +thread to the mutex and then the condition variable". +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 +I +or +I +in that thread behaves as if it were issued +after the about-to-block thread has blocked. + +Upon successful return, the mutex has been +locked and is owned by the calling thread. + +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 +I +or +I +functions may occur. +Since the return from +I +or +I +does not imply anything about the value of this predicate, +the predicate should be re-evaluated upon such return. + +The effect of using more than one mutex for concurrent +I +or +I +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. + +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 +I +or +I, +but at that point +notices the cancellation request and instead of returning to the caller +of +I +or +I, +starts the thread cancellation activities, which includes calling +cancellation cleanup handlers. + +A thread that has been unblocked because it has been +canceled while blocked in a call to +I +or +I +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. + +The +I +function is the same as +I +except that +an error is returned +if the absolute time specified by +I +passes (that is, system time equals or exceeds +I) +before the condition +I +is signaled or broadcasted, +or if the absolute time specified by +I +has already been passed at the time of the call. +When such time-outs occur, +I +will nonetheless release +and reacquire the mutex referenced by +I. +The function +I +is also a cancellation point. + +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. + +=head1 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 +I +or the condition variable specified by +I. + +Upon successful completion, a value of zero is returned. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ETIMEDOUT] + +The time specified by +I +to +I +has passed. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I, +I, +or +I +is invalid. + +=item [EINVAL] + +Different mutexes were supplied for concurrent +I +or +I +operations on the same condition variable. + +=item [EINVAL] + +The mutex was not owned by the current thread at the time of the call. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy condition variable attributes object + +=head1 SYNOPSIS + +#include + +int pthread_condattr_init(pthread_condattr_t *I); +int pthread_condattr_destroy(pthread_condattr_t *I); + +=head1 DESCRIPTION + +The function +I +initialises a condition variable attributes object +I +with the default value for all of the attributes +defined by the implementation. + +Attempting to initialise an already initialised +condition variable attributes object +results in undefined behaviour. + +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. + +The +I +function destroys a condition variable attributes object; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed condition variable attributes object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +Additional attributes, their default values, and the names +of the associated functions to get and set those attribute values are +implementation-dependent. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the condition variable +attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get and set the process-shared condition variable attributes + +=head1 SYNOPSIS + +#include + +int pthread_condattr_getpshared(const pthread_condattr_t *I, +int *I); +int pthread_condattr_setpshared(pthread_condattr_t *I, +int I); + +=head1 DESCRIPTION + +The +I +function obtains the value of the +I +attribute from the attributes object referenced by +I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by +I. + +The +I +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 +I +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. + +Additional attributes, their default values, and the names +of the associated functions to get and set those attribute values are +implementation-dependent. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +If successful, the +I +function returns zero +and stores the value of the +I +attribute of +I +into the object referenced by the +I +parameter. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute +is outside the range of legal values for that attribute. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy condition variable attributes object + +=head1 SYNOPSIS + +#include + +int pthread_condattr_init(pthread_condattr_t *I); +int pthread_condattr_destroy(pthread_condattr_t *I); + +=head1 DESCRIPTION + +The function +I +initialises a condition variable attributes object +I +with the default value for all of the attributes +defined by the implementation. + +Attempting to initialise an already initialised +condition variable attributes object +results in undefined behaviour. + +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. + +The +I +function destroys a condition variable attributes object; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed condition variable attributes object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +Additional attributes, their default values, and the names +of the associated functions to get and set those attribute values are +implementation-dependent. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the condition variable +attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get and set the process-shared condition variable attributes + +=head1 SYNOPSIS + +#include + +int pthread_condattr_getpshared(const pthread_condattr_t *I, +int *I); +int pthread_condattr_setpshared(pthread_condattr_t *I, +int I); + +=head1 DESCRIPTION + +The +I +function obtains the value of the +I +attribute from the attributes object referenced by +I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by +I. + +The +I +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 +I +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. + +Additional attributes, their default values, and the names +of the associated functions to get and set those attribute values are +implementation-dependent. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +If successful, the +I +function returns zero +and stores the value of the +I +attribute of +I +into the object referenced by the +I +parameter. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute +is outside the range of legal values for that attribute. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - thread creation + +=head1 SYNOPSIS + +#include + +int pthread_create(pthread_t *I, const pthread_attr_t *I, +void *(*I)(void*), void *I); + +=head1 DESCRIPTION + +The +I +function is used to create a new thread, with attributes specified by +I, +within a process. +If +I +is NULL, +the default attributes are used. +If the attributes specified by +I +are modified later, the thread's attributes are not affected. +Upon successful completion, +I +stores the ID of the created thread in the location referenced by +I. + +The thread is created executing +I +with +I +as its sole argument. +If the +I +returns, the effect is as if there was an implicit call to +I +using the return value of +I +as the exit status. +Note that the thread in which +I +was originally invoked differs from this. +When it returns from +I, +the effect is as if there was an implicit call to +I +using the return value of +I +as the exit status. + +The signal state of the new thread is initialised as follows: + +=over 4 + +=item o + +The signal mask is inherited from the creating thread. + +=item o + +The set of signals pending for the new thread is empty. + +=back + +If +I +fails, no new thread is created +and the contents of the location referenced by +I +are undefined. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources to create another thread, +or the system-imposed limit on the total number of threads +in a process PTHREAD_THREADS_MAX would be exceeded. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=item [EPERM] + +The caller does not have appropriate permission to set the required +scheduling parameters or scheduling policy. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - detach a thread + +=head1 SYNOPSIS + +#include + +int pthread_detach(pthread_t I); + +=head1 DESCRIPTION + +The +I +function is used to indicate to the implementation that storage +for the thread +I +can be reclaimed when that thread terminates. +If +I +has not terminated, +I +will not cause it to terminate. +The effect of multiple +I +calls on the same target thread is unspecified. + +=head1 RETURN VALUE + +If the call succeeds, +I +returns 0. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The implementation has detected that the value specified by +I +does not refer to a joinable thread. + +=item [ESRCH] + +No thread could be found corresponding to that specified +by the given thread ID. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - compare thread IDs + +=head1 SYNOPSIS + +#include + +int pthread_equal(pthread_t I, pthread_t I); + +=head1 DESCRIPTION + +This function compares the thread IDs +I +and +I. + +=head1 RETURN VALUE + +The +I +function returns a non-zero value if +I +and +I +are equal; +otherwise, zero is returned. + +If either +I +or +I +are not valid thread IDs, the behaviour is undefined. + +=head1 ERRORS + +No errors are defined. + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - thread termination + +=head1 SYNOPSIS + +#include + +void pthread_exit(void *I); + +=head1 DESCRIPTION + +The +I +function terminates the calling thread and makes the value +I +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 +I +routines that may exist. + +An implicit call to +I +is made when a thread other than the thread in which +I +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. + +The behaviour of +I +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 +I. + +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 +I +I +parameter value. + +The process exits with an exit status of 0 after the +last thread has been terminated. +The behaviour is as if the implementation called +I +with a zero argument at thread termination time. + +=head1 RETURN VALUE + +The +I +function cannot return to its caller. + +=head1 ERRORS + +No errors are defined. + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<_exit()>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - +get or set level of concurrency + +=head1 SYNOPSIS + +#include + +int pthread_getconcurrency(void); +int pthread_setconcurrency(int I); + +=head1 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. + +The +I +function allows an application to inform +the threads implementation of its desired concurrency level, +I. +The actual level of concurrency provided by the implementation as a +result of this function call is unspecified. + +If I is zero, it causes the implementation to maintain +the concurrency level at its discretion as if +I +was never called. + +The +I +function returns the +value set by a previous call to the +I +function. If the +I +function was not previously called, +this function returns zero to indicate that the implementation +is maintaining the concurrency level. + +When an application calls +I +it is +informing the implementation of its desired +concurrency level. The implementation uses this as a hint, +not a requirement. + +If an implementation does not support multiplexing of user threads +on top of several kernel scheduled entities, +the +I +and +I +functions +will be provided for source code +compatibility but they will have no effect when called. To maintain +the function semantics, the I +parameter will be saved when +I +is called so +that a subsequent call to +I +returns the same value. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. Otherwise, an error number is returned +to indicate the error. + +The +I +function always returns the concurrency level set by a previous call to +I. +If the +I +function has never been called, +I +returns zero. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is negative. + +=item [EAGAIN] + +The value specific by I would cause a system resource +to be exceeded. + +=back + +=head1 EXAMPLES + +None. + +=head1 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 +I +and +I +functions since their +use may conflict with an applications use of these functions. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- dynamic thread scheduling parameters access +(B) + +=head1 SYNOPSIS + +#include + +int pthread_getschedparam(pthread_t I, int *I, +struct sched_param *I); +int pthread_setschedparam(pthread_t I, int I, +const struct sched_param *I); + +=head1 DESCRIPTION + +The +I +and +I +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 +B +structure is the priority +I. +For SCHED_OTHER, +the affected scheduling parameters are implementation-dependent. + +The +I +function retrieves the scheduling policy and scheduling parameters +for the thread whose thread ID is given by +I +and stores those values in +I +and +I, +respectively. +The priority value returned from +I +is the value specified by the most recent +I +or +I +call affecting the target thread, +and reflects any temporary adjustments to its priority +as a result of any priority inheritance or ceiling functions. +The +I +function sets the scheduling policy +and associated scheduling parameters for the thread whose +thread ID is given by +I +to the policy and associated parameters provided in +I +and +I, +respectively. + +The +I +parameter may have the value SCHED_OTHER, +that has implementation-dependent scheduling parameters, +SCHED_FIFO or SCHED_RR, +that have the single scheduling parameter, +I + +If the +I +function fails, no scheduling parameters will be changed +for the target thread. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I +function may fail if: + +=over 4 + +=item [ESRCH] + +The value specified by +I +does not refer to a existing thread. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +or one of the scheduling parameters associated with +the scheduling policy +I +is invalid. + +=item [ENOTSUP] + +An attempt was made to set the policy or scheduling parameters to +an unsupported value. + +=item [EPERM] + +The caller does not have the appropriate permission to set +either the scheduling parameters or the scheduling policy of the +specified thread. + +=item [EPERM] + +The implementation does not allow the application to modify +one of the parameters to the value specified. + +=item [ESRCH] + +The value specified by +I +does not refer to a existing thread. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - thread-specific data management + +=head1 SYNOPSIS + +#include + +int pthread_setspecific(pthread_key_t I, const void *I); +void *pthread_getspecific(pthread_key_t I); + +=head1 DESCRIPTION + +The +I +function associates a thread-specific +I +with a +I +obtained via a previous call to +I. +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. + +The +I +function returns the value currently bound to the specified +I +on behalf of the calling thread. + +The effect of calling +I +or +I +with a +I +value not obtained from +I +or after +I +has been deleted with +I +is undefined. + +Both +I +and +I +may be called from a thread-specific data destructor function. +However, calling +I +from a destructor may result in lost storage or infinite loops. + +Both functions may be implemented as macros. + +=head1 RETURN VALUE + +The function +I +returns the thread-specific data value +associated with the given +I. +If no thread-specific data value is associated with +I, +then the value NULL is returned. + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to associate the value with the key. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The key value is invalid. + +=back + +No errors are returned from +I. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - wait for thread termination + +=head1 SYNOPSIS + +#include + +int pthread_join(pthread_t I, void **I); + +=head1 DESCRIPTION + +The +I +function suspends execution of the calling thread until the target +I +terminates, unless the target +I +has already terminated. +On return from a successful +I +call with a non-NULL +I +argument, the value passed to +I +by the terminating thread is made available in the location referenced by +I. +When a +I +returns successfully, the target thread has been terminated. +The results of multiple simultaneous calls to +I +specifying the same target thread are undefined. +If the thread calling +I +is canceled, then the target thread will not be detached. + +It is unspecified whether a thread that has exited but remains unjoined +counts against _POSIX_THREAD_THREADS_MAX. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EINVAL] + +The implementation has detected that the value specified by +I +does not refer to a joinable thread. + +=item [ESRCH] + +No thread could be found corresponding to that specified +by the given thread ID. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EDEADLK] + +A deadlock was detected or +the value of +I +specifies the calling thread. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - thread-specific data key creation + +=head1 SYNOPSIS + +#include + +int pthread_key_create(pthread_key_t *I, void (*I)(void*)); + +=head1 DESCRIPTION + +This function creates a thread-specific data +key visible to all threads in the process. +Key values provided by +I +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 +I +are maintained on a per-thread basis and persist +for the life of the calling thread. + +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. + +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. + +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. + +=head1 RETURN VALUE + +If successful, the +I +function stores the newly created key value at +I<*key> +and returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +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 +PTHREAD_KEYS_MAX has been exceeded. + +=item [ENOMEM] + +Insufficient memory exists to create the key. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - thread-specific data key deletion + +=head1 SYNOPSIS + +#include + +int pthread_key_delete(pthread_key_t I); + +=head1 DESCRIPTION + +This function deletes a thread-specific data +key previously returned by +I. +The thread-specific data values associated with +I +need not be NULL at the time +I +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 +I +is called. +Any attempt to use +I +following the call to +I +results in undefined behaviour. + +The +I +function is callable from within destructor functions. +No destructor functions will be invoked by +I. +Any destructor function that may have been associated with +I +will no longer be called upon thread exit. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The +I +value is invalid. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - send a signal to a thread + +=head1 SYNOPSIS + +#include + +int pthread_kill(pthread_t I, int I); + +=head1 DESCRIPTION + +The +I +function is used to request that a signal be delivered to the specified thread. + +As in +I, +if +I +is zero, error checking is performed but no signal is actually sent. + +=head1 RETURN VALUE + +Upon successful completion, the function returns a value of zero. +Otherwise the function returns an error number. +If the +I +function fails, no signal is sent. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ESRCH] + +No thread could be found corresponding to that specified +by the given thread ID. + +=item [EINVAL] + +The value of the +I +argument is an invalid or unsupported signal number. + +=back + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - initialise or destroy a mutex + +=head1 SYNOPSIS + +#include + +int pthread_mutex_init(pthread_mutex_t *I, +const pthread_mutexattr_t *I); +int pthread_mutex_destroy(pthread_mutex_t *I); +pthread_mutex_t I = PTHREAD_MUTEX_INITIALIZER; + +=head1 DESCRIPTION + +The +I +function initialises the mutex referenced by +I +with attributes specified +by +I. +If +I +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. + +Attempting to initialise an already initialised +mutex results in +undefined behaviour. + +The +I +function destroys the mutex object referenced by +I; +the mutex object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed mutex object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +It is safe to destroy an initialised mutex that is unlocked. +Attempting to destroy a locked mutex results in +undefined behaviour. + +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 +I +with parameter +I +specified as NULL, +except that no error checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other than memory) +to initialise another mutex. + +=item [ENOMEM] + +Insufficient memory exists to initialise the mutex. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt +to re-initialise the object referenced by +I, +a previously initialised, but +not yet destroyed, mutex. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy +the object referenced by +I +while it is locked or referenced +(for example, while being used in a +I +or +I) +by another thread. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- change the priority ceiling of a mutex +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutex_setprioceiling(pthread_mutex_t *I, int I, int *I); + +int pthread_mutex_getprioceiling(const pthread_mutex_t *I, int *I); + +=head1 DESCRIPTION + +The +I +function returns the current priority ceiling of the mutex. + +The +I +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 +I. +The process of locking the mutex need not adhere +to the priority protect protocol. + +If the +I +function fails, the mutex priority ceiling is not changed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIO_PROTECT is not defined and +the implementation does not support the function. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The priority requested by +I +is out of range. + +=item [EINVAL] + +The value specified by +I +does not refer to a currently existing mutex. + +=item [ENOSYS] + +The implementation does not support the priority ceiling protocol for mutexes. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - initialise or destroy a mutex + +=head1 SYNOPSIS + +#include + +int pthread_mutex_init(pthread_mutex_t *I, +const pthread_mutexattr_t *I); +int pthread_mutex_destroy(pthread_mutex_t *I); +pthread_mutex_t I = PTHREAD_MUTEX_INITIALIZER; + +=head1 DESCRIPTION + +The +I +function initialises the mutex referenced by +I +with attributes specified +by +I. +If +I +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. + +Attempting to initialise an already initialised +mutex results in +undefined behaviour. + +The +I +function destroys the mutex object referenced by +I; +the mutex object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed mutex object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been destroyed +are undefined. + +It is safe to destroy an initialised mutex that is unlocked. +Attempting to destroy a locked mutex results in +undefined behaviour. + +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 +I +with parameter +I +specified as NULL, +except that no error checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other than memory) +to initialise another mutex. + +=item [ENOMEM] + +Insufficient memory exists to initialise the mutex. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt +to re-initialise the object referenced by +I, +a previously initialised, but +not yet destroyed, mutex. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy +the object referenced by +I +while it is locked or referenced +(for example, while being used in a +I +or +I) +by another thread. + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- lock and unlock a mutex + +=head1 SYNOPSIS + +#include + +int pthread_mutex_lock(pthread_mutex_t *I); +int pthread_mutex_trylock(pthread_mutex_t *I); +int pthread_mutex_unlock(pthread_mutex_t *I); + +=head1 DESCRIPTION + +The mutex object referenced by +I +is locked by calling +I. +If the mutex is already locked, +the calling thread blocks until the mutex becomes available. +This operation returns with the mutex object referenced by +I +in the locked state with the calling thread as its owner. + +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. + +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. + +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. + +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. + +The function +I +is identical to +I +except that if the mutex object referenced by +I +is currently locked (by any thread, including the +current thread), the call returns immediately. + +The +I +function releases the mutex object referenced by +I. +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 +I when +I +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). + +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. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +The function +I +returns zero if a lock on the mutex object referenced by +I +is acquired. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The +I +was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher +than the mutex's current priority ceiling. + +=back + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The +I +could not be acquired because it was already locked. + +=back + +The +I, +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +does not refer to an initialised mutex object. + +=item [EAGAIN] + +The mutex could not be acquired because the maximum +number of recursive locks for I has been exceeded. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EDEADLK] + +The current thread already owns the mutex. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EPERM] + +The current thread does not own the mutex. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- change the priority ceiling of a mutex +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutex_setprioceiling(pthread_mutex_t *I, int +I, int *I); + +int pthread_mutex_getprioceiling(const pthread_mutex_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +function returns the current priority ceiling of the mutex. + +The +I +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 +I. +The process of locking the mutex need not adhere +to the priority protect protocol. + +If the +I +function fails, the mutex priority ceiling is not changed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIO_PROTECT is not defined and +the implementation does not support the function. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The priority requested by +I +is out of range. + +=item [EINVAL] + +The value specified by +I +does not refer to a currently existing mutex. + +=item [ENOSYS] + +The implementation does not support the priority ceiling protocol for mutexes. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- lock and unlock a mutex + +=head1 SYNOPSIS + +#include + +int pthread_mutex_lock(pthread_mutex_t *I); +int pthread_mutex_trylock(pthread_mutex_t *I); +int pthread_mutex_unlock(pthread_mutex_t *I); + +=head1 DESCRIPTION + +The mutex object referenced by +I +is locked by calling +I. +If the mutex is already locked, +the calling thread blocks until the mutex becomes available. +This operation returns with the mutex object referenced by +I +in the locked state with the calling thread as its owner. + +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. + +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. + +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. + +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. + +The function +I +is identical to +I +except that if the mutex object referenced by +I +is currently locked (by any thread, including the +current thread), the call returns immediately. + +The +I +function releases the mutex object referenced by +I. +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 +I when +I +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). + +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. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +The function +I +returns zero if a lock on the mutex object referenced by +I +is acquired. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The +I +was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher +than the mutex's current priority ceiling. + +=back + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The +I +could not be acquired because it was already locked. + +=back + +The +I, +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +does not refer to an initialised mutex object. + +=item [EAGAIN] + +The mutex could not be acquired because the maximum +number of recursive locks for I has been exceeded. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EDEADLK] + +The current thread already owns the mutex. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EPERM] + +The current thread does not own the mutex. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- lock and unlock a mutex + +=head1 SYNOPSIS + +#include + +int pthread_mutex_lock(pthread_mutex_t *I); +int pthread_mutex_trylock(pthread_mutex_t *I); +int pthread_mutex_unlock(pthread_mutex_t *I); + +=head1 DESCRIPTION + +The mutex object referenced by +I +is locked by calling +I. +If the mutex is already locked, +the calling thread blocks until the mutex becomes available. +This operation returns with the mutex object referenced by +I +in the locked state with the calling thread as its owner. + +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. + +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. + +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. + +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. + +The function +I +is identical to +I +except that if the mutex object referenced by +I +is currently locked (by any thread, including the +current thread), the call returns immediately. + +The +I +function releases the mutex object referenced by +I. +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 +I when +I +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). + +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. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +The function +I +returns zero if a lock on the mutex object referenced by +I +is acquired. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The +I +was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher +than the mutex's current priority ceiling. + +=back + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The +I +could not be acquired because it was already locked. + +=back + +The +I, +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +does not refer to an initialised mutex object. + +=item [EAGAIN] + +The mutex could not be acquired because the maximum +number of recursive locks for I has been exceeded. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EDEADLK] + +The current thread already owns the mutex. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EPERM] + +The current thread does not own the mutex. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy mutex attributes object + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_init(pthread_mutexattr_t *I); +int pthread_mutexattr_destroy(pthread_mutexattr_t *I); + +=head1 DESCRIPTION + +The function +I +initialises a mutex attributes object +I +with the default value for all of the attributes +defined by the implementation. + +The effect of initialising an already initialised mutex +attributes object is undefined. + +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. + +The +I +function destroys a mutex attributes object; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed mutex attributes object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been +destroyed are undefined. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the mutex attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get prioceiling attribute of mutex attribute object +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I, +int I); +int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +and +I +functions, respectively, set and get the priority ceiling attribute of +a mutex attribute object pointed to by +I +which was previously created by the function +I. + +The +I +attribute contains the priority ceiling of initialised mutexes. +The values of +I +will be within the maximum range of priorities defined by SCHED_FIFO. + +The +I +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 +I +will be within the maximum range of priorities +defined under the SCHED_FIFO scheduling policy. + +=head1 RETURN VALUE + +Upon successful completion, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIO_PROTECT is not defined and the +implementation does not support the function. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +or +I +is invalid. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get protocol attribute of mutex attribute object +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I, +int I); +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +and +I +functions, respectively, set and get the protocol attribute of a mutex +attribute object pointed to by +I +which was previously created by the function +I. + +The +I +attribute defines the protocol to be followed in utilising mutexes. +The value of +I +may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or +PTHREAD_PRIO_PROTECT, which are defined by the header +I<>. + +When a thread owns a mutex with the PTHREAD_PRIO_NONE +protocol attribute, its priority and scheduling are not affected +by its mutex ownership. + +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. + +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. + +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 +I. +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. + +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. + +When a thread makes a call to +I, +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. + +=head1 RETURN VALUE + +Upon successful completion, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +Neither one of the options _POSIX_THREAD_PRIO_PROTECT and +_POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not +support the function. + +=item [ENOTSUP] + +The value specified by +I +is an unsupported value. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +ro +I +is invalid. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get process-shared attribute + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I, +int *I); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *I, +int I); + +=head1 DESCRIPTION + +The +I +function obtains the value of the +I +attribute from the attributes object referenced by +I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by +I. + +The +I +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 +I +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. + +=head1 RETURN VALUE + +Upon successful completion, +I +returns zero. +Otherwise, an error number is returned to indicate the error. + +Upon successful completion, +I +returns zero and stores the value of the +I +attribute of +I +into the object referenced by the +I +parameter. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute +is outside the range of legal values for that attribute. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get or set a mutex type + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>); +int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I); + +=head1 DESCRIPTION + +The +I +and +I +functions respectively get and set the mutex I attribute. +This attribute is set in the I parameter +to these functions. The default value of the I +attribute is PTHREAD_MUTEX_DEFAULT. + +The type of mutex is contained in the I attribute of the +mutex attributes. Valid mutex types include: + +=over 4 + +=item PTHREAD_MUTEX_NORMAL + +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. + +=item PTHREAD_MUTEX_ERRORCHECK + +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. + +=item PTHREAD_MUTEX_RECURSIVE + +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 PTHREAD_MUTEX_NORMAL 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. + +=item PTHREAD_MUTEX_DEFAULT + +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. + +=back + +=head1 RETURN VALUE + +If successful, the +I +function +returns zero. Otherwise, an error number is +returned to indicate the error. + +Upon successful completion, the +I +function returns zero and stores the value of the +I attribute of I into the object referenced by the +I +parameter. Otherwise an error is returned to indicate +the error. + + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The value I is invalid. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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 +I +or +I +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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy mutex attributes object + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_init(pthread_mutexattr_t *I); +int pthread_mutexattr_destroy(pthread_mutexattr_t *I); + +=head1 DESCRIPTION + +The function +I +initialises a mutex attributes object +I +with the default value for all of the attributes +defined by the implementation. + +The effect of initialising an already initialised mutex +attributes object is undefined. + +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. + +The +I +function destroys a mutex attributes object; +the object becomes, in effect, uninitialised. +An implementation may cause +I +to set the object referenced by +I +to an invalid value. +A destroyed mutex attributes object +can be re-initialised using +I; +the results of otherwise referencing the object after it has been +destroyed are undefined. + +=head1 RETURN VALUE + +Upon successful completion, +I +and +I +return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the mutex attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get prioceiling attribute of mutex attribute object +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *I, +int I); +int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +and +I +functions, respectively, set and get the priority ceiling attribute of +a mutex attribute object pointed to by +I +which was previously created by the function +I. + +The +I +attribute contains the priority ceiling of initialised mutexes. +The values of +I +will be within the maximum range of priorities defined by SCHED_FIFO. + +The +I +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 +I +will be within the maximum range of priorities +defined under the SCHED_FIFO scheduling policy. + +=head1 RETURN VALUE + +Upon successful completion, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIO_PROTECT is not defined and the +implementation does not support the function. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +or +I +is invalid. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get protocol attribute of mutex attribute object +(B) + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *I, +int I); +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *I, +int *I); + +=head1 DESCRIPTION + +The +I +and +I +functions, respectively, set and get the protocol attribute of a mutex +attribute object pointed to by +I +which was previously created by the function +I. + +The +I +attribute defines the protocol to be followed in utilising mutexes. +The value of +I +may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or +PTHREAD_PRIO_PROTECT, which are defined by the header +I<>. + +When a thread owns a mutex with the PTHREAD_PRIO_NONE +protocol attribute, its priority and scheduling are not affected +by its mutex ownership. + +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. + +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. + +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 +I. +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. + +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. + +When a thread makes a call to +I, +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. + +=head1 RETURN VALUE + +Upon successful completion, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +Neither one of the options _POSIX_THREAD_PRIO_PROTECT and +_POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not +support the function. + +=item [ENOTSUP] + +The value specified by +I +is an unsupported value. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +ro +I +is invalid. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- set and get process-shared attribute + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_getpshared(const pthread_mutexattr_t *I, +int *I); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *I, +int I); + +=head1 DESCRIPTION + +The +I +function obtains the value of the +I +attribute from the attributes object referenced by +I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by +I. + +The +I +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 +I +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. + +=head1 RETURN VALUE + +Upon successful completion, +I +returns zero. +Otherwise, an error number is returned to indicate the error. + +Upon successful completion, +I +returns zero and stores the value of the +I +attribute of +I +into the object referenced by the +I +parameter. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute +is outside the range of legal values for that attribute. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get or set a mutex type + +=head1 SYNOPSIS + +#include + +int pthread_mutexattr_gettype(const pthread_mutexattr_t I<*attr>, int I<*type>); +int pthread_mutexattr_settype(pthread_mutexattr_t I<*attr>, int I); + +=head1 DESCRIPTION + +The +I +and +I +functions respectively get and set the mutex I attribute. +This attribute is set in the I parameter +to these functions. The default value of the I +attribute is PTHREAD_MUTEX_DEFAULT. + +The type of mutex is contained in the I attribute of the +mutex attributes. Valid mutex types include: + +=over 4 + +=item PTHREAD_MUTEX_NORMAL + +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. + +=item PTHREAD_MUTEX_ERRORCHECK + +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. + +=item PTHREAD_MUTEX_RECURSIVE + +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 PTHREAD_MUTEX_NORMAL 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. + +=item PTHREAD_MUTEX_DEFAULT + +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. + +=back + +=head1 RETURN VALUE + +If successful, the +I +function +returns zero. Otherwise, an error number is +returned to indicate the error. + +Upon successful completion, the +I +function returns zero and stores the value of the +I attribute of I into the object referenced by the +I +parameter. Otherwise an error is returned to indicate +the error. + + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [EINVAL] + +The value I is invalid. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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 +I +or +I +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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - dynamic package initialisation + +=head1 SYNOPSIS + +#include + +int pthread_once(pthread_once_t *I, +void (*I)(void)); +pthread_once_t I = PTHREAD_ONCE_INIT; + +=head1 DESCRIPTION + +The first call to +I +by any thread in a process, with a given +I, +will call the +I +with no arguments. +Subsequent calls of +I +with the same +I +will not call the +I. +On return from +I, +it is guaranteed that +I +has completed. +The +I +parameter is used to determine whether +the associated initialisation routine has been called. + +The function +I +is not a cancellation point. +However, if +I +is a cancellation point and is canceled, +the effect on +I +is as if +I +was never called. + +The constant PTHREAD_ONCE_INIT +is defined by the header +I<>. + +The behaviour of +I +is undefined if +I +has automatic storage duration or is not initialised by +PTHREAD_ONCE_INIT. + +=head1 RETURN VALUE + +Upon successful completion, +I +returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +No errors are defined. + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise or destroy a read-write lock object + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_init(pthread_rwlock_t *rwlock, +const pthread_rwlockattr_t I<*attr>); +int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>); +pthread_rwlock_t I=PTHREAD_RWLOCK_INITIALIZER; + +=head1 DESCRIPTION + +The +I +function initialises the read-write lock referenced by I with +the attributes referenced by I. If I 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 +I +is called specifying an already initialised read-write lock. +Results are undefined if a read-write lock is used without first being +initialised. + +If the +I +function fails, I is not initialised and the contents of +I are undefined. + +The +I +function destroys the read-write lock object referenced by I +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 +I. +An implementation may cause +I +to set the object referenced by I to an invalid value. +Results are undefined if +I +is called when any thread holds I. +Attempting to destroy an uninitialised +read-write lock results in undefined behaviour. +A destroyed read-write lock object can be re-initialised using +I; +the results of otherwise referencing the read-write lock object after it +has been destroyed are undefined. + +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 +I +with the parameter I specified as NULL, except that no error +checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other than memory) +to initialise another read-write lock. + +=item [ENOMEM] + +Insufficient memory exists to initialise the read-write lock. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to re-initialise the +object referenced by I, a previously initialised but +not yet destroyed read-write lock. + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy the +object referenced by I while it is locked. + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise or destroy a read-write lock object + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_init(pthread_rwlock_t *rwlock, +const pthread_rwlockattr_t I<*attr>); +int pthread_rwlock_destroy(pthread_rwlock_t I<*rwlock>); +pthread_rwlock_t I=PTHREAD_RWLOCK_INITIALIZER; + +=head1 DESCRIPTION + +The +I +function initialises the read-write lock referenced by I with +the attributes referenced by I. If I 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 +I +is called specifying an already initialised read-write lock. +Results are undefined if a read-write lock is used without first being +initialised. + +If the +I +function fails, I is not initialised and the contents of +I are undefined. + +The +I +function destroys the read-write lock object referenced by I +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 +I. +An implementation may cause +I +to set the object referenced by I to an invalid value. +Results are undefined if +I +is called when any thread holds I. +Attempting to destroy an uninitialised +read-write lock results in undefined behaviour. +A destroyed read-write lock object can be re-initialised using +I; +the results of otherwise referencing the read-write lock object after it +has been destroyed are undefined. + +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 +I +with the parameter I specified as NULL, except that no error +checks are performed. + +=head1 RETURN VALUE + +If successful, the +I +and +I +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 +I. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EAGAIN] + +The system lacked the necessary resources (other than memory) +to initialise another read-write lock. + +=item [ENOMEM] + +Insufficient memory exists to initialise the read-write lock. + +=item [EPERM] + +The caller does not have the privilege to perform the operation. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to re-initialise the +object referenced by I, a previously initialised but +not yet destroyed read-write lock. + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EBUSY] + +The implementation has detected an attempt to destroy the +object referenced by I while it is locked. + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- lock a read-write lock object for reading + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>); +int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>); + +=head1 DESCRIPTION + +The +I +function applies a read lock to the read-write lock referenced by +I. +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 +I +call) until it can acquire the lock. +Results are undefined if the calling thread holds +a write lock on I +at the time the call is made. + +Implementations are allowed to favour writers over readers +to avoid writer starvation. + +A thread may hold multiple concurrent read locks on I +(that is, successfully call the +I +function I times). If so, the thread +must perform matching unlocks (that is, it must +call the +I +function I times). + +The function +I +applies a read lock +as in the +I +function +with the exception that the function fails if any thread holds a +write lock on I or there are writers blocked +on I. + +Results are undefined if any of these functions are called with +an uninitialised read-write lock. + +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. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned +to indicate the error. + +The function +I +returns zero if the +lock for reading on the read-write lock object +referenced by I is acquired. +Otherwise an error number +is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The read-write lock could not be acquired for reading because a +writer holds the +lock or was blocked on it. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I does not refer to an initialised +read-write lock object. + +=item [EDEADLK] + +The current thread already owns the read-write lock for writing. + +=item [EAGAIN] + +The read lock could not be acquired because the maximum number of +read locks +for I has been exceeded. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +Realtime applications may encounter priority inversion when using +read-write locks. +The problem occurs when a high priority thread "locks" a read-write +lock that is about to be "unlocked" 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- lock a read-write lock object for reading + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_rdlock(pthread_rwlock_t I<*rwlock>); +int pthread_rwlock_tryrdlock(pthread_rwlock_t I<*rwlock>); + +=head1 DESCRIPTION + +The +I +function applies a read lock to the read-write lock referenced by +I. +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 +I +call) until it can acquire the lock. +Results are undefined if the calling thread holds +a write lock on I +at the time the call is made. + +Implementations are allowed to favour writers over readers +to avoid writer starvation. + +A thread may hold multiple concurrent read locks on I +(that is, successfully call the +I +function I times). If so, the thread +must perform matching unlocks (that is, it must +call the +I +function I times). + +The function +I +applies a read lock +as in the +I +function +with the exception that the function fails if any thread holds a +write lock on I or there are writers blocked +on I. + +Results are undefined if any of these functions are called with +an uninitialised read-write lock. + +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. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned +to indicate the error. + +The function +I +returns zero if the +lock for reading on the read-write lock object +referenced by I is acquired. +Otherwise an error number +is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The read-write lock could not be acquired for reading because a +writer holds the +lock or was blocked on it. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I does not refer to an initialised +read-write lock object. + +=item [EDEADLK] + +The current thread already owns the read-write lock for writing. + +=item [EAGAIN] + +The read lock could not be acquired because the maximum number of +read locks +for I has been exceeded. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +Realtime applications may encounter priority inversion when using +read-write locks. +The problem occurs when a high priority thread "locks" a read-write +lock that is about to be "unlocked" 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- lock a read-write lock object for writing + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>); +int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>); + +=head1 DESCRIPTION + +The +I +function applies a write lock to +the read-write lock referenced by I. The +calling thread acquires the write lock if no other thread +(reader or writer) holds the read-write lock I. +Otherwise, the thread blocks (that is, does not return from the +I +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. + +Implementations are allowed to favour writers over +readers to avoid writer starvation. + +The function +I +applies a write lock +like the +I +function, with the exception that the function fails if any +thread currently holds I (for reading or writing). + +Results are undefined if any of these functions are called with +an uninitialised read-write lock. + +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. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned +to indicate the error. + +The function +I +returns zero if the +lock for writing on the read-write lock object +referenced by I is acquired. +Otherwise an error number is +returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The read-write lock could not be acquired for writing because it +was already locked for reading or writing. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I does not refer to an initialised +read-write lock object. + +=item [EDEADLK] + +The current thread already owns the read-write lock for writing or +reading. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +Realtime applications may encounter priority inversion when using +read-write locks. +The problem occurs when a high priority thread "locks" a read-write +lock that is about to be "unlocked" 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - unlock a read-write lock object + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_unlock(pthread_rwlock_t I<*rwlock>); + +=head1 DESCRIPTION + +The +I +function is called to release a lock held on the read-write lock +object referenced by I. +Results are undefined if the read-write lock I is not +held by the calling thread. + +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. + +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. + +If the call to the +I +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 I +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. + +Results are undefined if any of these functions are called with +an uninitialised read-write lock. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned +to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I does not refer to an initialised +read-write lock object. + +=item [EPERM] + +The current thread does not own the read-write lock. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- lock a read-write lock object for writing + +=head1 SYNOPSIS + +#include + +int pthread_rwlock_wrlock(pthread_rwlock_t I<*rwlock>); +int pthread_rwlock_trywrlock(pthread_rwlock_t I<*rwlock>); + +=head1 DESCRIPTION + +The +I +function applies a write lock to +the read-write lock referenced by I. The +calling thread acquires the write lock if no other thread +(reader or writer) holds the read-write lock I. +Otherwise, the thread blocks (that is, does not return from the +I +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. + +Implementations are allowed to favour writers over +readers to avoid writer starvation. + +The function +I +applies a write lock +like the +I +function, with the exception that the function fails if any +thread currently holds I (for reading or writing). + +Results are undefined if any of these functions are called with +an uninitialised read-write lock. + +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. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned +to indicate the error. + +The function +I +returns zero if the +lock for writing on the read-write lock object +referenced by I is acquired. +Otherwise an error number is +returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [EBUSY] + +The read-write lock could not be acquired for writing because it +was already locked for reading or writing. + +=back + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I does not refer to an initialised +read-write lock object. + +=item [EDEADLK] + +The current thread already owns the read-write lock for writing or +reading. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +Realtime applications may encounter priority inversion when using +read-write locks. +The problem occurs when a high priority thread "locks" a read-write +lock that is about to be "unlocked" 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy read-write lock attributes object + +=head1 SYNOPSIS + +#include + +int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>); +int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>); + +=head1 DESCRIPTION + +The function +I +initialises a read-write +lock attributes object I with the default +value for all of the attributes defined by the implementation. + +Results are undefined if +I +is called +specifying an already initialised read-write lock +attributes object. + +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. + +The +I +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 +I. +An implementation may cause +I +to set the object +referenced by attr to an invalid value. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to +indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the read-write +lock attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get and set process-shared attribute of read-write lock +attributes object + +=head1 SYNOPSIS + +#include + +int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>, +int I<*pshared>); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>, +int I); + +=head1 DESCRIPTION + +The +I +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 +I +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 +I +attribute is PTHREAD_PROCESS_PRIVATE. + +The +I +function obtains the value of the +I +attribute from the initialised attributes object referenced by I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by attr. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +Upon successful completion, the +I +returns zero and stores the value of the +I +attribute of I into the object referenced by the +I parameter. Otherwise an error number is +returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute is outside the range +of legal values for +that attribute. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- initialise and destroy read-write lock attributes object + +=head1 SYNOPSIS + +#include + +int pthread_rwlockattr_init(pthread_rwlockattr_t I<*attr>); +int pthread_rwlockattr_destroy(pthread_rwlockattr_t I<*attr>); + +=head1 DESCRIPTION + +The function +I +initialises a read-write +lock attributes object I with the default +value for all of the attributes defined by the implementation. + +Results are undefined if +I +is called +specifying an already initialised read-write lock +attributes object. + +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. + +The +I +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 +I. +An implementation may cause +I +to set the object +referenced by attr to an invalid value. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to +indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to initialise the read-write +lock attributes object. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- get and set process-shared attribute of read-write lock +attributes object + +=head1 SYNOPSIS + +#include + +int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t I<*attr>, +int I<*pshared>); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t I<*attr>, +int I); + +=head1 DESCRIPTION + +The +I +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 +I +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 +I +attribute is PTHREAD_PROCESS_PRIVATE. + +The +I +function obtains the value of the +I +attribute from the initialised attributes object referenced by I. +The +I +function is used to set the +I +attribute in an initialised attributes object referenced by attr. + +=head1 RETURN VALUE + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +Upon successful completion, the +I +returns zero and stores the value of the +I +attribute of I into the object referenced by the +I parameter. Otherwise an error number is +returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by I is invalid. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The new value specified for the attribute is outside the range +of legal values for +that attribute. + +=back + +=head1 EXAMPLES + +None. + +=head1 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. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I<>, +I, +I, +I, +I, +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - get calling thread's ID + +=head1 SYNOPSIS + +#include + +pthread_t pthread_self(void); + +=head1 DESCRIPTION + +The +I +function returns the thread ID of the calling thread. + +=head1 RETURN VALUE + +See DESCRIPTION above. + +=head1 ERRORS + +No errors are defined. + +The +I +function will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- set cancelability state + +=head1 SYNOPSIS + +#include + +int pthread_setcancelstate(int I, int *I); +int pthread_setcanceltype(int I, int *I); +void pthread_testcancel(void); + +=head1 DESCRIPTION + +The +I +function atomically both sets the calling thread's cancelability +state to the indicated +I +and returns the previous cancelability state +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. + +The +I +function atomically both sets the calling thread's cancelability +type to the indicated +I +and returns the previous cancelability type +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. + +The cancelability state and type of any newly +created threads, including the thread in which +I +was first invoked, +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED +respectively. + +The +I +function creates a cancellation point in the calling thread. +The +I +function has no effect if cancelability is disabled. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified state is not +PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified type is not PTHREAD_CANCEL_DEFERRED +or PTHREAD_CANCEL_ASYNCHRONOUS. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- set cancelability state + +=head1 SYNOPSIS + +#include + +int pthread_setcancelstate(int I, int *I); +int pthread_setcanceltype(int I, int *I); +void pthread_testcancel(void); + +=head1 DESCRIPTION + +The +I +function atomically both sets the calling thread's cancelability +state to the indicated +I +and returns the previous cancelability state +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. + +The +I +function atomically both sets the calling thread's cancelability +type to the indicated +I +and returns the previous cancelability type +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. + +The cancelability state and type of any newly +created threads, including the thread in which +I +was first invoked, +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED +respectively. + +The +I +function creates a cancellation point in the calling thread. +The +I +function has no effect if cancelability is disabled. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified state is not +PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified type is not PTHREAD_CANCEL_DEFERRED +or PTHREAD_CANCEL_ASYNCHRONOUS. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - get or set level of concurrency + +=head1 SYNOPSIS + +#include + +int pthread_setconcurrency(int I); + +=head1 DESCRIPTION + +Refer to +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B +- dynamic thread scheduling parameters access +(B) + +=head1 SYNOPSIS + +#include + +int pthread_getschedparam(pthread_t I, int *I, +struct sched_param *I); +int pthread_setschedparam(pthread_t I, int I, +const struct sched_param *I); + +=head1 DESCRIPTION + +The +I +and +I +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 +B +structure is the priority +I. +For SCHED_OTHER, +the affected scheduling parameters are implementation-dependent. + +The +I +function retrieves the scheduling policy and scheduling parameters +for the thread whose thread ID is given by +I +and stores those values in +I +and +I, +respectively. +The priority value returned from +I +is the value specified by the most recent +I +or +I +call affecting the target thread, +and reflects any temporary adjustments to its priority +as a result of any priority inheritance or ceiling functions. +The +I +function sets the scheduling policy +and associated scheduling parameters for the thread whose +thread ID is given by +I +to the policy and associated parameters provided in +I +and +I, +respectively. + +The +I +parameter may have the value SCHED_OTHER, +that has implementation-dependent scheduling parameters, +SCHED_FIFO or SCHED_RR, +that have the single scheduling parameter, +I + +If the +I +function fails, no scheduling parameters will be changed +for the target thread. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +and +I +functions will fail if: + +=over 4 + +=item [ENOSYS] + +The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the +implementation does not support the function. + +=back + +The +I +function may fail if: + +=over 4 + +=item [ESRCH] + +The value specified by +I +does not refer to a existing thread. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The value specified by +I +or one of the scheduling parameters associated with +the scheduling policy +I +is invalid. + +=item [ENOTSUP] + +An attempt was made to set the policy or scheduling parameters to +an unsupported value. + +=item [EPERM] + +The caller does not have the appropriate permission to set +either the scheduling parameters or the scheduling policy of the +specified thread. + +=item [EPERM] + +The implementation does not allow the application to modify +one of the parameters to the value specified. + +=item [ESRCH] + +The value specified by +I +does not refer to a existing thread. + +=back + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I, +I, +I, +I<>, +I<>. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B - thread-specific data management + +=head1 SYNOPSIS + +#include + +int pthread_setspecific(pthread_key_t I, const void *I); +void *pthread_getspecific(pthread_key_t I); + +=head1 DESCRIPTION + +The +I +function associates a thread-specific +I +with a +I +obtained via a previous call to +I. +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. + +The +I +function returns the value currently bound to the specified +I +on behalf of the calling thread. + +The effect of calling +I +or +I +with a +I +value not obtained from +I +or after +I +has been deleted with +I +is undefined. + +Both +I +and +I +may be called from a thread-specific data destructor function. +However, calling +I +from a destructor may result in lost storage or infinite loops. + +Both functions may be implemented as macros. + +=head1 RETURN VALUE + +The function +I +returns the thread-specific data value +associated with the given +I. +If no thread-specific data value is associated with +I, +then the value NULL is returned. + +If successful, the +I +function returns zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function will fail if: + +=over 4 + +=item [ENOMEM] + +Insufficient memory exists to associate the value with the key. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The key value is invalid. + +=back + +No errors are returned from +I. + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + + +=head1 ______________________________________________________________________ + +=head1 NAME + +B - examine and change blocked signals + +=head1 SYNOPSIS + +#include + +int pthread_sigmask(int I, const sigset_t *I, sigset_t *I); + +=head1 DESCRIPTION + +Refer to +I. + +=head1 ______________________________________________________________________ + +=head1 NAME + +B B B +- set cancelability state + +=head1 SYNOPSIS + +#include + +int pthread_setcancelstate(int I, int *I); +int pthread_setcanceltype(int I, int *I); +void pthread_testcancel(void); + +=head1 DESCRIPTION + +The +I +function atomically both sets the calling thread's cancelability +state to the indicated +I +and returns the previous cancelability state +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. + +The +I +function atomically both sets the calling thread's cancelability +type to the indicated +I +and returns the previous cancelability type +at the location referenced by I. +Legal values for +I +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. + +The cancelability state and type of any newly +created threads, including the thread in which +I +was first invoked, +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED +respectively. + +The +I +function creates a cancellation point in the calling thread. +The +I +function has no effect if cancelability is disabled. + +=head1 RETURN VALUE + +If successful, the +I +and +I +functions return zero. +Otherwise, an error number is returned to indicate the error. + +=head1 ERRORS + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified state is not +PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. + +=back + +The +I +function may fail if: + +=over 4 + +=item [EINVAL] + +The specified type is not PTHREAD_CANCEL_DEFERRED +or PTHREAD_CANCEL_ASYNCHRONOUS. + +=back + +These functions will not return an error code of [EINTR]. + +=head1 EXAMPLES + +None. + +=head1 APPLICATION USAGE + +None. + +=head1 FUTURE DIRECTIONS + +None. + +=head1 SEE ALSO + +I, +I<>. + +=cut +