.\" 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 .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 .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \&\fI 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. .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 header will make visible symbols defined in the headers \fI and \fI. .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_atfork\fR \- register fork handlers .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .PP #include .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 .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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setdetachstate,\fR \fBpthread_attr_getdetachstate\fR \&\- set and get detachstate attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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). 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. .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 .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. .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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setschedparam,\fR \fBpthread_attr_getschedparam\fR \&\- set and get schedparam attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. 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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .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 .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. 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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .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 .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. .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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setstackaddr,\fR \fBpthread_attr_getstackaddr\fR \&\- set and get stackaddr attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setstacksize,\fR \fBpthread_attr_getstacksize\fR \&\- set and get stacksize attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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, \&\fI. .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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setdetachstate,\fR \fBpthread_attr_getdetachstate\fR \&\- set and get detachstate attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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). 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. .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 .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. .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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setschedparam,\fR \fBpthread_attr_getschedparam\fR \&\- set and get schedparam attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. 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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .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 .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. 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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .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 .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. .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, \&\fI\fIpthread_setschedparam()\fI\fR, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setstackaddr,\fR \fBpthread_attr_getstackaddr\fR \&\- set and get stackaddr attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_attr_setstacksize,\fR \fBpthread_attr_getstacksize\fR \&\- set and get stacksize attribute .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cancel\fR \- cancel execution of a thread .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cleanup_push,\fR \fBpthread_cleanup_pop\fR \- establish cancellation handlers .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cleanup_push,\fR \fBpthread_cleanup_pop\fR \- establish cancellation handlers .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_signal,\fR \fBpthread_cond_broadcast\fR \- signal or broadcast a condition .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_init,\fR \fBpthread_cond_destroy\fR \- initialise and destroy condition variables .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_init,\fR \fBpthread_cond_destroy\fR \- initialise and destroy condition variables .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_signal,\fR \fBpthread_cond_broadcast\fR \- signal or broadcast a condition .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_wait,\fR \fBpthread_cond_timedwait\fR \- wait on a condition .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_cond_wait,\fR \fBpthread_cond_timedwait\fR \- wait on a condition .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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. .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 .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. .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 .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. .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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_create\fR \- thread creation .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_detach\fR \- detach a thread .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_equal\fR \- compare thread IDs .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_exit\fR \- thread termination .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_getconcurrency,\fR \fBpthread_setconcurrency\fR \- get or set level of concurrency .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_setspecific,\fR \fBpthread_getspecific\fR \- thread-specific data management .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_join\fR \- wait for thread termination .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_key_create\fR \- thread-specific data key creation .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_key_delete\fR \- thread-specific data key deletion .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_kill\fR \- send a signal to a thread .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_mutex_init,\fR \fBpthread_mutex_destroy\fR \- initialise or destroy a mutex .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_mutex_init,\fR \fBpthread_mutex_destroy\fR \- initialise or destroy a mutex .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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 .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. .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 .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. .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 .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. .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 .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. .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 .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. .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 .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. .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 .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. .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. .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 .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. .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 .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. .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 .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. .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 .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. .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 .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. .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. .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 .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. .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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_once\fR \- dynamic package initialisation .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .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. .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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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, \&\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 .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_setcancelstate,\fR \fBpthread_setcanceltype,\fR \fBpthread_testcancel\fR \&\- set cancelability state .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_setcancelstate,\fR \fBpthread_setcanceltype,\fR \fBpthread_testcancel\fR \&\- set cancelability state .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_setconcurrency\fR \- get or set level of concurrency .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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 .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, \&\fI. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_setspecific,\fR \fBpthread_getspecific\fR \- thread-specific data management .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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. .SH "_\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|__\|_" .IX Header "______________________________________________________________________" .SH "NAME" \&\fBpthread_sigmask\fR \- examine and change blocked signals .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .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 .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.