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