FreeBSD Manual Pages
pthread(3) POSIX Threading API of GNU Pth pthread(3) NAME pthread - POSIX.1c Threading API of GNU Pth VERSION GNU Pth 2.0.7 (08-Jun-2006) SYNOPSIS Application Makefiles: # manually CFLAGS=-I/path/to/pth/include LDFLAGS=-L/path/to/pth/lib LIBS=-lpthread # automatically CFLAGS=`pthread-config --cflags` LDFLAGS=`pthread-config --ldflags` LIBS=`pthread-config --libs` Application source files: #include <pthread.h> DESCRIPTION Overview This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of GNU Portable Threads (Pth). This API is commonly known as ``POSIX threads'' or in short ``Pthreads''. It is provided by Pth with the in- tention of backward compatibility to existing multithreaded applica- tions. It is implemented by mapping the various Pthread API functions to the corresponding native Pth API functions. Supported Features The following defined feature macros in "pthread.h" indicate supported features: #define _POSIX_THREADS #define _POSIX_THREAD_ATTR_STACKADDR #define _POSIX_THREAD_ATTR_STACKSIZE The following undefined feature macros in "pthread.h" indicate (still) unsupported features: #undef _POSIX_THREAD_PRIORITY_SCHEDULING #undef _POSIX_THREAD_PRIO_INHERIT #undef _POSIX_THREAD_PRIO_PROTECT #undef _POSIX_THREAD_PROCESS_SHARED #undef _POSIX_THREAD_SAFE_FUNCTIONS Notes A few notes which you should keep in mind when working with the Pth Pthread API. Non-Preemptive Scheduling First you have to always remember when working with this Pthread library that it uses non-preemptive scheduling, because it is di- rectly based on Pth (Pth for portability reasons is a pure non-pre- emptive thread scheduling system). So there is no implicit yielding of execution control unless you can "pthread_*" functions which could block and you cannot expect granular concurrency in your ap- plication, of course. Nevertheless the responsiveness and concur- rency of an event driven application is increased greatly because of overlapping I/O. Conflicts with Vendor Implementation There can be a conflict between the Pth "pthread.h" header and a possibly existing vendor "/usr/include/pthread.h" header which was implicitly included by some standard vendor headers (like "/usr/in- clude/unistd.h"). When this occurs try to ``"#define"'' header-de- pendent values which prevent the inclusion of the vendor header. Further Reading There is ``The Single UNIX Specification, Version 2 - Threads'', from The Open Group of 1997 under http://www.opengroup.org/on- linepubs/007908799/xsh/threads.html. This is a very complete publically available description of the Pthread API. For convinience reasons, a translated copy of these freely available HTML pages are appended to this manpage below. These are Copyright (C) 1997 The Open Group. Second, you can also buy the official standard from IEEE. It is the IEEE POSIX 1003.1c-1995 standard (also known as ISO/IEC 9945-1:1996), which is available as part of the ANSI/IEEE 1003.1, 1996 edition, stan- dard. Finally you can look at the files "pthread.c" and "pthread.h" in the Pth source tree for details of the implementation, of course. SEE ALSO pthread-config(1), pth(3). AUTHOR Ralf S. Engelschall rse@engelschall.com www.engelschall.com ______________________________________________________________________ NAME pthread.h - threads SYNOPSIS #include <pthread.h> DESCRIPTION The <pthread.h> header defines the following symbols: PTHREAD_CANCEL_ASYNCHRONOUS PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_DEFERRED PTHREAD_CANCEL_DISABLE PTHREAD_CANCELED PTHREAD_COND_INITIALIZER PTHREAD_CREATE_DETACHED PTHREAD_CREATE_JOINABLE PTHREAD_EXPLICIT_SCHED PTHREAD_INHERIT_SCHED PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_ERRORCHECK PTHREAD_MUTEX_NORMAL PTHREAD_MUTEX_INITIALIZER PTHREAD_MUTEX_RECURSIVE PTHREAD_ONCE_INIT PTHREAD_PRIO_INHERIT PTHREAD_PRIO_NONE PTHREAD_PRIO_PROTECT PTHREAD_PROCESS_SHARED PTHREAD_PROCESS_PRIVATE PTHREAD_RWLOCK_INITIALIZER PTHREAD_SCOPE_PROCESS PTHREAD_SCOPE_SYSTEM The pthread_attr_t, pthread_cond_t, pthread_condattr_t, pthread_key_t, pthread_mutex_t, pthread_mutexattr_t, pthread_once_t, pthread_rwlock_t, pthread_rwlockattr_t and pthread_t types are defined as described in <sys/types.h>. The following are declared as functions and may also be declared as macros. Function prototypes must be provided for use with an ISO C com- piler. int pthread_attr_destroy(pthread_attr_t *); int pthread_attr_getdetachstate(const pthread_attr_t *, int *); int pthread_attr_getguardsize(const pthread_attr_t *, size_t *); int pthread_attr_getinheritsched(const pthread_attr_t *, int *); int pthread_attr_getschedparam(const pthread_attr_t *, struct sched_param *); int pthread_attr_getschedpolicy(const pthread_attr_t *, int *); int pthread_attr_getscope(const pthread_attr_t *, int *); int pthread_attr_getstackaddr(const pthread_attr_t *, void **); int pthread_attr_getstacksize(const pthread_attr_t *, size_t *); int pthread_attr_init(pthread_attr_t *); int pthread_attr_setdetachstate(pthread_attr_t *, int); int pthread_attr_setguardsize(pthread_attr_t *, size_t); int pthread_attr_setinheritsched(pthread_attr_t *, int); int pthread_attr_setschedparam(pthread_attr_t *, const struct sched_param *); int pthread_attr_setschedpolicy(pthread_attr_t *, int); int pthread_attr_setscope(pthread_attr_t *, int); int pthread_attr_setstackaddr(pthread_attr_t *, void *); int pthread_attr_setstacksize(pthread_attr_t *, size_t); int pthread_cancel(pthread_t); void pthread_cleanup_push(void*), void *); void pthread_cleanup_pop(int); int pthread_cond_broadcast(pthread_cond_t *); int pthread_cond_destroy(pthread_cond_t *); int pthread_cond_init(pthread_cond_t *, const pthread_condattr_t *); int pthread_cond_signal(pthread_cond_t *); int pthread_cond_timedwait(pthread_cond_t *, pthread_mutex_t *, const struct timespec *); int pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *); int pthread_condattr_destroy(pthread_condattr_t *); int pthread_condattr_getpshared(const pthread_condattr_t *, int *); int pthread_condattr_init(pthread_condattr_t *); int pthread_condattr_setpshared(pthread_condattr_t *, int); int pthread_create(pthread_t *, const pthread_attr_t *, void *(*)(void *), void *); int pthread_detach(pthread_t); int pthread_equal(pthread_t, pthread_t); void pthread_exit(void *); int pthread_getconcurrency(void); int pthread_getschedparam(pthread_t, int *, struct sched_param *); void *pthread_getspecific(pthread_key_t); int pthread_join(pthread_t, void **); int pthread_key_create(pthread_key_t *, void (*)(void *)); int pthread_key_delete(pthread_key_t); int pthread_mutex_destroy(pthread_mutex_t *); int pthread_mutex_getprioceiling(const pthread_mutex_t *, int *); int pthread_mutex_init(pthread_mutex_t *, const pthread_mutexattr_t *); int pthread_mutex_lock(pthread_mutex_t *); int pthread_mutex_setprioceiling(pthread_mutex_t *, int, int *); int pthread_mutex_trylock(pthread_mutex_t *); int pthread_mutex_unlock(pthread_mutex_t *); int pthread_mutexattr_destroy(pthread_mutexattr_t *); int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *, int *); int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *, int *); int pthread_mutexattr_getpshared(const pthread_mutexattr_t *, int *); int pthread_mutexattr_gettype(const pthread_mutexattr_t *, int *); int pthread_mutexattr_init(pthread_mutexattr_t *); int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); int pthread_mutexattr_settype(pthread_mutexattr_t *, int); int pthread_once(pthread_once_t *, void (*)(void)); int pthread_rwlock_destroy(pthread_rwlock_t *); int pthread_rwlock_init(pthread_rwlock_t *, const pthread_rwlockattr_t *); int pthread_rwlock_rdlock(pthread_rwlock_t *); int pthread_rwlock_tryrdlock(pthread_rwlock_t *); int pthread_rwlock_trywrlock(pthread_rwlock_t *); int pthread_rwlock_unlock(pthread_rwlock_t *); int pthread_rwlock_wrlock(pthread_rwlock_t *); int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *, int *); int pthread_rwlockattr_init(pthread_rwlockattr_t *); int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); pthread_t pthread_self(void); int pthread_setcancelstate(int, int *); int pthread_setcanceltype(int, int *); int pthread_setconcurrency(int); int pthread_setschedparam(pthread_t, int, const struct sched_param *); int pthread_setspecific(pthread_key_t, const void *); void pthread_testcancel(void); Inclusion of the <pthread.h> header will make visible symbols defined in the headers <sched.h> and <time.h>. APPLICATION USAGE An interpretation request has been filed with IEEE PASC concerning re- quirements for visibility of symbols in this header. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_getguardsize(), pthread_attr_setscope(), pthread_cancel(), pthread_cleanup_push(), pthread_cond_init(), pthread_cond_signal(), pthread_cond_wait(), pthread_condattr_init(), pthread_create(), pthread_detach(), pthread_equal(), pthread_exit(), pthread_getconcurrency(), pthread_getschedparam(), pthread_join(), pthread_key_create(), pthread_key_delete(), pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_setprioceiling(), pthread_mutexattr_init(), pthread_mu- texattr_gettype(), pthread_mutexattr_setprotocol(), pthread_once(), pthread_self(), pthread_setcancelstate(), pthread_setspecific(), pthread_rwlock_init(), pthread_rwlock_rdlock(), pthread_rwlock_un- lock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), <sched.h>, <time.h>. ______________________________________________________________________ NAME pthread_atfork - register fork handlers SYNOPSIS #include <sys/types.h> #include <unistd.h> int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void)); DESCRIPTION The pthread_atfork() function declares fork handlers to be called be- fore and after fork(), in the context of the thread that called fork(). The prepare fork handler is called before fork() processing commences. The parent fork handle is called after fork() processing completes in the parent process. The child fork handler is called after fork() pro- cessing completes in the child process. If no handling is desired at one or more of these three points, the corresponding fork handler ad- dress(es) may be set to NULL. The order of calls to pthread_atfork() is significant. The parent and child fork handlers are called in the order in which they were estab- lished by calls to pthread_atfork(). The prepare fork handlers are called in the opposite order. RETURN VALUE Upon successful completion, pthread_atfork() returns a value of zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_atfork() function will fail if: [ENOMEM] Insufficient table space exists to record the fork handler ad- dresses. The pthread_atfork() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO atexit(), fork(), <sys/types.h> ______________________________________________________________________ NAME pthread_attr_init, pthread_attr_destroy - initialise and destroy threads attribute object SYNOPSIS #include <pthread.h> int pthread_attr_init(pthread_attr_t *attr); int pthread_attr_destroy(pthread_attr_t *attr); DESCRIPTION The function pthread_attr_init() initialises a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. The resulting attribute object (possibly modified by setting individual attribute values), when used by pthread_create(), defines the attrib- utes of the thread created. A single attributes object can be used in multiple simultaneous calls to pthread_create(). The pthread_attr_destroy() function is used to destroy a thread attrib- utes object. An implementation may cause pthread_attr_destroy() to set attr to an implementation-dependent invalid value. The behaviour of us- ing the attribute after it has been destroyed is undefined. RETURN VALUE Upon successful completion, pthread_attr_init() and pthread_attr_de- stroy() return a value of 0. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_attr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the thread attributes ob- ject. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_attr_setdetachstate(), pthread_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setdetachstate, pthread_attr_getdetachstate - set and get detachstate attribute SYNOPSIS #include <pthread.h> int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *de- tachstate); DESCRIPTION The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then use of the ID of the newly created thread by the pthread_detach() or pthread_join() function is an error. The pthread_attr_setdetachstate() and pthread_attr_getdetachstate(), respectively, set and get the detachstate attribute in the attr object. The detachstate can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes all threads created with attr to be in the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE causes all threads created with attr to be in the joinable state. The default value of the detachstate at- tribute is PTHREAD_CREATE_JOINABLE . RETURN VALUE Upon successful completion, pthread_attr_setdetachstate() and pthread_attr_getdetachstate() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getdetachstate() function stores the value of the de- tachstate attribute in detachstate if successful. ERRORS The pthread_attr_setdetachstate() function will fail if: [EINVAL] The value of detachstate was not valid These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_set- stacksize(), pthread_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_attr_getguardsize, pthread_attr_setguardsize - get or set the thread guardsize attribute SYNOPSIS #include <pthread.h> int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize); int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize); DESCRIPTION The guardsize attribute controls the size of the guard area for the created thread's stack. The guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is created with guard protection, the implementation allocates extra memory at the overflow end of the stack as a buffer against stack overflow of the stack pointer. If an application overflows into this buffer an error results (possibly in a SIGSEGV signal being delivered to the thread). The guardsize attribute is provided to the application for two reasons: 1. Overflow protection can potentially result in wasted system re- sources. 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. 2. When threads allocate large data structures on the stack, large guard areas may be needed to detect stack overflow. The pthread_attr_getguardsize() function gets the guardsize attribute in the attr object. This attribute is returned in the guardsize parame- ter. The pthread_attr_setguardsize() function sets the guardsize attribute in the attr object. The new value of this attribute is obtained from the guardsize parameter. If guardsize is zero, a guard area will not be provided for threads created with attr. If guardsize is greater than zero, a guard area of at least size guardsize bytes is provided for each thread created with attr. A conforming implementation is permitted to round up the value con- tained in guardsize to a multiple of the configurable system variable PAGESIZE (see <sys/mman.h>). If an implementation rounds up the value of guardsize to a multiple of PAGESIZE, a call to pthread_attr_get- guardsize() specifying attr will store in the guardsize parameter the guard size specified by the previous pthread_attr_setguardsize() func- tion call. The default value of the guardsize attribute is PAGESIZE bytes. The ac- tual value of PAGESIZE is implementation-dependent and may not be the same on all implementations. If the stackaddr attribute has been set (that is, the caller is allo- cating and managing its own thread stacks), the guardsize 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. RETURN VALUE If successful, the pthread_attr_getguardsize() and pthread_attr_set- guardsize() functions return zero. Otherwise, an error number is re- turned to indicate the error. ERRORS The pthread_attr_getguardsize() and pthread_attr_setguardsize() func- tions will fail if: [EINVAL] The attribute attr is invalid. [EINVAL] The parameter guardsize is invalid. [EINVAL] The parameter guardsize contains an invalid value. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setinheritsched, pthread_attr_getinheritsched - set and get inheritsched attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setinheritsched(pthread_attr_t *attr, int inher- itsched); int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched); DESCRIPTION The functions pthread_attr_setinheritsched() and pthread_attr_getinher- itsched(), respectively, set and get the inheritsched attribute in the attr argument. When the attribute objects are used by pthread_create(), the inher- itsched attribute determines how the other scheduling attributes of the created thread are to be set: PTHREAD_INHERIT_SCHED Specifies that the scheduling policy and associated attributes are to be inherited from the creating thread, and the scheduling at- tributes in this attr argument are to be ignored. PTHREAD_EXPLICIT_SCHED Specifies that the scheduling policy and associated attributes are to be set to the corresponding values from this attribute object. The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are de- fined in the header <pthread.h>. RETURN VALUE If successful, the pthread_attr_setinheritsched() and pthread_attr_get- inheritsched() functions return zero. Otherwise, an error number is re- turned to indicate the error. ERRORS The pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setinheritsched() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setschedpol- icy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setschedparam, pthread_attr_getschedparam - set and get schedparam attribute SYNOPSIS #include <pthread.h> int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param); int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param); DESCRIPTION The functions pthread_attr_setschedparam() and pthread_attr_getsched- param(), respectively, set and get the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in <sched.h>. For the SCHED_FIFO and SCHED_RR policies, the only re- quired member of param is sched_priority. RETURN VALUE If successful, the pthread_attr_setschedparam() and pthread_attr_getschedparam() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_attr_setschedparam() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. The pthread_attr_setschedparam() and pthread_attr_getschedparam() func- tions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinher- itsched(), pthread_attr_setschedpolicy(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set and get schedpolicy attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy); DESCRIPTION The functions pthread_attr_setschedpolicy() and pthread_attr_getsched- policy(), respectively, set and get the schedpolicy attribute in the attr argument. The supported values of policy include SCHED_FIFO, SCHED_RR and SCHED_OTHER, which are defined by the header <sched.h>. When threads executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting on a mutex, they acquire the mutex in priority order when the mutex is unlocked. RETURN VALUE If successful, the pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions return zero. Otherwise, an er- ror number is returned to indicate the error. ERRORS The pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setschedpolicy() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinher- itsched(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setscope, pthread_attr_getscope - set and get contention- scope attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope); int pthread_attr_getscope(const pthread_attr_t *attr, int *contention- scope); DESCRIPTION The pthread_attr_setscope() and pthread_attr_getscope() functions are used to set and get the contentionscope attribute in the attr object. The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined by the header <pthread.h>. RETURN VALUE If successful, the pthread_attr_setscope() and pthread_attr_getscope() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_attr_setscope() and pthread_attr_getscope() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setscope(), function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setstackaddr, pthread_attr_getstackaddr - set and get stackaddr attribute SYNOPSIS #include <pthread.h> int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stack- addr); DESCRIPTION The functions pthread_attr_setstackaddr() and pthread_attr_getstack- addr(), respectively, set and get the thread creation stackaddr at- tribute in the attr object. The stackaddr attribute specifies the location of storage to be used for the created thread's stack. The size of the storage is at least PTHREAD_STACK_MIN. RETURN VALUE Upon successful completion, pthread_attr_setstackaddr() and pthread_attr_getstackaddr() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getstackaddr() function stores the stackaddr attribute value in stackaddr if successful. ERRORS No errors are defined. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setdetachstate(), pthread_attr_set- stacksize(), pthread_create(), <limits.h>, <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setstacksize, pthread_attr_getstacksize - set and get stacksize attribute SYNOPSIS #include <pthread.h> int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize); int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize); DESCRIPTION The functions pthread_attr_setstacksize() and pthread_attr_getstack- size(), respectively, set and get the thread creation stacksize at- tribute in the attr object. The stacksize attribute defines the minimum stack size (in bytes) allo- cated for the created threads stack. RETURN VALUE Upon successful completion, pthread_attr_setstacksize() and pthread_attr_getstacksize() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getstack- size() function stores the stacksize attribute value in stacksize if successful. ERRORS The pthread_attr_setstacksize() function will fail if: [EINVAL] The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setde- tachstate(), pthread_create(), <limits.h>, <pthread.h>. ______________________________________________________________________ NAME pthread_attr_init, pthread_attr_destroy - initialise and destroy threads attribute object SYNOPSIS #include <pthread.h> int pthread_attr_init(pthread_attr_t *attr); int pthread_attr_de- stroy(pthread_attr_t *attr); DESCRIPTION The function pthread_attr_init() initialises a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. The resulting attribute object (possibly modified by setting individual attribute values), when used by pthread_create(), defines the attrib- utes of the thread created. A single attributes object can be used in multiple simultaneous calls to pthread_create(). The pthread_attr_destroy() function is used to destroy a thread attrib- utes object. An implementation may cause pthread_attr_destroy() to set attr to an implementation-dependent invalid value. The behaviour of using the attribute after it has been destroyed is undefined. RETURN VALUE Upon successful completion, pthread_attr_init() and pthread_attr_de- stroy() return a value of 0. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_attr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the thread attributes ob- ject. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_setstackaddr(), pthread_attr_setstacksize(), pthread_attr_setdetachstate(), pthread_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setdetachstate, pthread_attr_getdetachstate - set and get detachstate attribute SYNOPSIS #include <pthread.h> int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *de- tachstate); DESCRIPTION The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then use of the ID of the newly created thread by the pthread_detach() or pthread_join() function is an error. The pthread_attr_setdetachstate() and pthread_attr_getdetachstate(), respectively, set and get the detachstate attribute in the attr object. The detachstate can be set to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. A value of PTHREAD_CREATE_DETACHED causes all threads created with attr to be in the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE causes all threads created with attr to be in the joinable state. The default value of the detachstate at- tribute is PTHREAD_CREATE_JOINABLE . RETURN VALUE Upon successful completion, pthread_attr_setdetachstate() and pthread_attr_getdetachstate() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getdetachstate() function stores the value of the de- tachstate attribute in detachstate if successful. ERRORS The pthread_attr_setdetachstate() function will fail if: [EINVAL] The value of detachstate was not valid These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_set- stacksize(), pthread_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_attr_getguardsize, pthread_attr_setguardsize - get or set the thread guardsize attribute SYNOPSIS #include <pthread.h> int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize); int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize); DESCRIPTION The guardsize attribute controls the size of the guard area for the created thread's stack. The guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is created with guard protection, the implementation allocates extra memory at the overflow end of the stack as a buffer against stack overflow of the stack pointer. If an application overflows into this buffer an error results (possibly in a SIGSEGV signal being delivered to the thread). The guardsize attribute is provided to the application for two reasons: 1. Overflow protection can potentially result in wasted system re- sources. 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. 2. When threads allocate large data structures on the stack, large guard areas may be needed to detect stack overflow. The pthread_attr_getguardsize() function gets the guardsize attribute in the attr object. This attribute is returned in the guardsize parame- ter. The pthread_attr_setguardsize() function sets the guardsize attribute in the attr object. The new value of this attribute is obtained from the guardsize parameter. If guardsize is zero, a guard area will not be provided for threads created with attr. If guardsize is greater than zero, a guard area of at least size guardsize bytes is provided for each thread created with attr. A conforming implementation is permitted to round up the value con- tained in guardsize to a multiple of the configurable system variable PAGESIZE (see <sys/mman.h>). If an implementation rounds up the value of guardsize to a multiple of PAGESIZE, a call to pthread_attr_get- guardsize() specifying attr will store in the guardsize parameter the guard size specified by the previous pthread_attr_setguardsize() func- tion call. The default value of the guardsize attribute is PAGESIZE bytes. The actual value of PAGESIZE is implementation-dependent and may not be the same on all implementations. If the stackaddr attribute has been set (that is, the caller is allo- cating and managing its own thread stacks), the guardsize 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. RETURN VALUE If successful, the pthread_attr_getguardsize() and pthread_attr_set- guardsize() functions return zero. Otherwise, an error number is re- turned to indicate the error. ERRORS The pthread_attr_getguardsize() and pthread_attr_setguardsize() func- tions will fail if: [EINVAL] The attribute attr is invalid. [EINVAL] The parameter guardsize is invalid. [EINVAL] The parameter guardsize contains an invalid value. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setinheritsched, pthread_attr_getinheritsched - set and get inheritsched attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setinheritsched(pthread_attr_t *attr, int inher- itsched); int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched); DESCRIPTION The functions pthread_attr_setinheritsched() and pthread_attr_getinher- itsched(), respectively, set and get the inheritsched attribute in the attr argument. When the attribute objects are used by pthread_create(), the inher- itsched attribute determines how the other scheduling attributes of the created thread are to be set: PTHREAD_INHERIT_SCHED Specifies that the scheduling policy and associated attributes are to be inherited from the creating thread, and the scheduling at- tributes in this attr argument are to be ignored. PTHREAD_EXPLICIT_SCHED Specifies that the scheduling policy and associated attributes are to be set to the corresponding values from this attribute object. The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are de- fined in the header <pthread.h>. RETURN VALUE If successful, the pthread_attr_setinheritsched() and pthread_attr_get- inheritsched() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_attr_setinheritsched() and pthread_attr_getinheritsched() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setinheritsched() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setschedpol- icy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setschedparam, pthread_attr_getschedparam - set and get schedparam attribute SYNOPSIS #include <pthread.h> int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param); int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param); DESCRIPTION The functions pthread_attr_setschedparam() and pthread_attr_getsched- param(), respectively, set and get the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in <sched.h>. For the SCHED_FIFO and SCHED_RR policies, the only re- quired member of param is sched_priority. RETURN VALUE If successful, the pthread_attr_setschedparam() and pthread_attr_getschedparam() functions return zero. Otherwise, an er- ror number is returned to indicate the error. ERRORS The pthread_attr_setschedparam() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. The pthread_attr_setschedparam() and pthread_attr_getschedparam() func- tions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinher- itsched(), pthread_attr_setschedpolicy(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - set and get schedpolicy attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy); DESCRIPTION The functions pthread_attr_setschedpolicy() and pthread_attr_getsched- policy(), respectively, set and get the schedpolicy attribute in the attr argument. The supported values of policy include SCHED_FIFO, SCHED_RR and SCHED_OTHER, which are defined by the header <sched.h>. When threads executing with the scheduling policy SCHED_FIFO or SCHED_RR are waiting on a mutex, they acquire the mutex in priority order when the mutex is unlocked. RETURN VALUE If successful, the pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions return zero. Otherwise, an er- ror number is returned to indicate the error. ERRORS The pthread_attr_setschedpolicy() and pthread_attr_getschedpolicy() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setschedpolicy() function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setscope(), pthread_attr_setinher- itsched(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setscope, pthread_attr_getscope - set and get contention- scope attribute (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope); int pthread_attr_getscope(const pthread_attr_t *attr, int *contention- scope); DESCRIPTION The pthread_attr_setscope() and pthread_attr_getscope() functions are used to set and get the contentionscope attribute in the attr object. The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined by the header <pthread.h>. RETURN VALUE If successful, the pthread_attr_setscope() and pthread_attr_getscope() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_attr_setscope() and pthread_attr_getscope() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_attr_setscope(), function may fail if: [EINVAL] The value of the attribute being set is not valid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. EXAMPLES None. APPLICATION USAGE After these attributes have been set, a thread can be created with the specified attributes using pthread_create(). Using these routines does not affect the current running thread. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setinheritsched(), pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), pthread_create(), <pthread.h>, pthread_setschedparam(), <sched.h>. ______________________________________________________________________ NAME pthread_attr_setstackaddr, pthread_attr_getstackaddr - set and get stackaddr attribute SYNOPSIS #include <pthread.h> int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stack- addr); DESCRIPTION The functions pthread_attr_setstackaddr() and pthread_attr_getstack- addr(), respectively, set and get the thread creation stackaddr at- tribute in the attr object. The stackaddr attribute specifies the location of storage to be used for the created thread's stack. The size of the storage is at least PTHREAD_STACK_MIN. RETURN VALUE Upon successful completion, pthread_attr_setstackaddr() and pthread_attr_getstackaddr() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getstackaddr() function stores the stackaddr attribute value in stackaddr if successful. ERRORS No errors are defined. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setdetachstate(), pthread_attr_set- stacksize(), pthread_create(), <limits.h>, <pthread.h>. ______________________________________________________________________ NAME pthread_attr_setstacksize, pthread_attr_getstacksize - set and get stacksize attribute SYNOPSIS #include <pthread.h> int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize); int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize); DESCRIPTION The functions pthread_attr_setstacksize() and pthread_attr_getstack- size(), respectively, set and get the thread creation stacksize at- tribute in the attr object. The stacksize attribute defines the minimum stack size (in bytes) allo- cated for the created threads stack. RETURN VALUE Upon successful completion, pthread_attr_setstacksize() and pthread_attr_getstacksize() return a value of 0. Otherwise, an error number is returned to indicate the error. The pthread_attr_getstack- size() function stores the stacksize attribute value in stacksize if successful. ERRORS The pthread_attr_setstacksize() function will fail if: [EINVAL] The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a system-imposed limit. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_attr_init(), pthread_attr_setstackaddr(), pthread_attr_setde- tachstate(), pthread_create(), <limits.h>, <pthread.h>. ______________________________________________________________________ NAME pthread_cancel - cancel execution of a thread SYNOPSIS #include <pthread.h> int pthread_cancel(pthread_t thread); DESCRIPTION The pthread_cancel() function requests that thread be canceled. The target threads cancelability state and type determines when the cancel- lation takes effect. When the cancellation is acted on, the cancella- tion cleanup handlers for thread are called. When the last cancella- tion cleanup handler returns, the thread-specific data destructor func- tions are called for thread. When the last destructor function re- turns, thread is terminated. The cancellation processing in the target thread runs asynchronously with respect to the calling thread returning from pthread_cancel(). RETURN VALUE If successful, the pthread_cancel() function returns zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_cancel() function may fail if: [ESRCH] No thread could be found corresponding to that specified by the given thread ID. The pthread_cancel() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_exit(), pthread_join(), pthread_setcancelstate(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_cleanup_push, pthread_cleanup_pop - establish cancellation han- dlers SYNOPSIS #include <pthread.h> void pthread_cleanup_push(void (*routine)(void*), void *arg); void pthread_cleanup_pop(int execute); DESCRIPTION The pthread_cleanup_push() function pushes the specified cancellation cleanup handler routine onto the calling thread's cancellation cleanup stack. The cancellation cleanup handler is popped from the cancella- tion cleanup stack and invoked with the argument arg when: (a) the thread exits (that is, calls pthread_exit()), (b) the thread acts upon a cancellation request, or (c) the thread calls pthread_cleanup_pop() with a non-zero execute argument. The pthread_cleanup_pop() function removes the routine at the top of the calling thread's cancellation cleanup stack and optionally invokes it (if execute is non-zero). These functions may be implemented as macros and will appear as state- ments and in pairs within the same lexical scope (that is, the pthread_cleanup_push() macro may be thought to expand to a token list whose first token is `{' with pthread_cleanup_pop() expanding to a to- ken list whose last token is the corresponding `}'. The effect of calling longjmp() or siglongjmp() is undefined if there have been any calls to pthread_cleanup_push() or pthread_cleanup_pop() made without the matching call since the jump buffer was filled. The effect of calling longjmp() or siglongjmp() from inside a cancellation cleanup handler is also undefined unless the jump buffer was also filled in the cancellation cleanup handler. RETURN VALUE The pthread_cleanup_push() and pthread_cleanup_pop() functions return no value. ERRORS No errors are defined. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cancel(), pthread_setcancelstate(), <pthread.h>. ______________________________________________________________________ NAME pthread_cleanup_push, pthread_cleanup_pop - establish cancellation han- dlers SYNOPSIS #include <pthread.h> void pthread_cleanup_push(void (*routine)(void*), void *arg); void pthread_cleanup_pop(int execute); DESCRIPTION The pthread_cleanup_push() function pushes the specified cancellation cleanup handler routine onto the calling thread's cancellation cleanup stack. The cancellation cleanup handler is popped from the cancella- tion cleanup stack and invoked with the argument arg when: (a) the thread exits (that is, calls pthread_exit()), (b) the thread acts upon a cancellation request, or (c) the thread calls pthread_cleanup_pop() with a non-zero execute argument. The pthread_cleanup_pop() function removes the routine at the top of the calling thread's cancellation cleanup stack and optionally invokes it (if execute is non-zero). These functions may be implemented as macros and will appear as state- ments and in pairs within the same lexical scope (that is, the pthread_cleanup_push() macro may be thought to expand to a token list whose first token is `{' with pthread_cleanup_pop() expanding to a to- ken list whose last token is the corresponding `}'. The effect of calling longjmp() or siglongjmp() is undefined if there have been any calls to pthread_cleanup_push() or pthread_cleanup_pop() made without the matching call since the jump buffer was filled. The effect of calling longjmp() or siglongjmp() from inside a cancellation cleanup handler is also undefined unless the jump buffer was also filled in the cancellation cleanup handler. RETURN VALUE The pthread_cleanup_push() and pthread_cleanup_pop() functions return no value. ERRORS No errors are defined. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cancel(), pthread_setcancelstate(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_signal, pthread_cond_broadcast - signal or broadcast a condition SYNOPSIS #include <pthread.h> int pthread_cond_signal(pthread_cond_t *cond); int pthread_cond_broad- cast(pthread_cond_t *cond); DESCRIPTION These two functions are used to unblock threads blocked on a condition variable. The pthread_cond_signal() call unblocks at least one of the threads that are blocked on the specified condition variable cond (if any threads are blocked on cond). The pthread_cond_broadcast() call unblocks all threads currently blocked on the specified condition variable cond. If more than one thread is blocked on a condition variable, the sched- uling policy determines the order in which threads are unblocked. When each thread unblocked as a result of a pthread_cond_signal() or pthread_cond_broadcast() returns from its call to pthread_cond_wait() or pthread_cond_timedwait(), the thread owns the mutex with which it called pthread_cond_wait() or pthread_cond_timedwait(). The thread(s) that are unblocked contend for the mutex according to the scheduling policy (if applicable), and as if each had called pthread_mutex_lock(). The pthread_cond_signal() or pthread_cond_broadcast() functions may be called by a thread whether or not it currently owns the mutex that threads calling pthread_cond_wait() or pthread_cond_timedwait() 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 pthread_cond_signal() or pthread_cond_broad- cast(). The pthread_cond_signal() and pthread_cond_broadcast() functions have no effect if there are no threads currently blocked on cond. RETURN VALUE If successful, the pthread_cond_signal() and pthread_cond_broadcast() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_cond_signal() and pthread_cond_broadcast() function may fail if: [EINVAL] The value cond does not refer to an initialised condition variable. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_init(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_init, pthread_cond_destroy - initialise and destroy condi- tion variables SYNOPSIS #include <pthread.h> int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr); int pthread_cond_destroy(pthread_cond_t *cond); pthread_cond_t cond = PTHREAD_COND_INITIALIZER; DESCRIPTION The function pthread_cond_init() initialises the condition variable referenced by cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used; the effect is the same as passing the address of a default condition variable attrib- utes object. Upon successful initialisation, the state of the condi- tion variable becomes initialised. Attempting to initialise an already initialised condition variable re- sults in undefined behaviour. The function pthread_cond_destroy() destroys the given condition vari- able specified by cond; the object becomes, in effect, uninitialised. An implementation may cause pthread_cond_destroy() to set the object referenced by cond to an invalid value. A destroyed condition variable object can be re-initialised using pthread_cond_init(); the results of otherwise referencing the object after it has been destroyed are unde- fined. It is safe to destroy an initialised condition variable upon which no threads are currently blocked. Attempting to destroy a condition vari- able upon which other threads are currently blocked results in unde- fined behaviour. In cases where default condition variable attributes are appropriate, the macro PTHREAD_COND_INITIALIZER can be used to initialise condition variables that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_cond_init() with parameter attr specified as NULL, except that no error checks are performed. RETURN VALUE If successful, the pthread_cond_init() and pthread_cond_destroy() func- tions return zero. Otherwise, an error number is returned to indicate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processing for the function and caused an error return prior to modifying the state of the condition variable specified by cond. ERRORS The pthread_cond_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another condition variable. [ENOMEM] Insufficient memory exists to initialise the condition variable. The pthread_cond_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by cond, a previously initialised, but not yet de- stroyed, condition variable. [EINVAL] The value specified by attr is invalid. The pthread_cond_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by an- other thread. [EINVAL] The value specified by cond is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_signal(), pthread_cond_broadcast(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_init, pthread_cond_destroy - initialise and destroy condi- tion variables SYNOPSIS #include <pthread.h> int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr); int pthread_cond_destroy(pthread_cond_t *cond); pthread_cond_t cond = PTHREAD_COND_INITIALIZER; DESCRIPTION The function pthread_cond_init() initialises the condition variable referenced by cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used; the effect is the same as passing the address of a default condition variable attrib- utes object. Upon successful initialisation, the state of the condi- tion variable becomes initialised. Attempting to initialise an already initialised condition variable re- sults in undefined behaviour. The function pthread_cond_destroy() destroys the given condition vari- able specified by cond; the object becomes, in effect, uninitialised. An implementation may cause pthread_cond_destroy() to set the object referenced by cond to an invalid value. A destroyed condition variable object can be re-initialised using pthread_cond_init(); the results of otherwise referencing the object after it has been destroyed are unde- fined. It is safe to destroy an initialised condition variable upon which no threads are currently blocked. Attempting to destroy a condition vari- able upon which other threads are currently blocked results in unde- fined behaviour. In cases where default condition variable attributes are appropriate, the macro PTHREAD_COND_INITIALIZER can be used to initialise condition variables that are statically allocated. The effect is equivalent to dynamic initialisation by a call to pthread_cond_init() with parameter attr specified as NULL, except that no error checks are performed. RETURN VALUE If successful, the pthread_cond_init() and pthread_cond_destroy() func- tions return zero. Otherwise, an error number is returned to indicate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processing for the function and caused an error return prior to modifying the state of the condition variable specified by cond. ERRORS The pthread_cond_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another condition variable. [ENOMEM] Insufficient memory exists to initialise the condition variable. The pthread_cond_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by cond, a previously initialised, but not yet de- stroyed, condition variable. [EINVAL] The value specified by attr is invalid. The pthread_cond_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timedwait()) by an- other thread. [EINVAL] The value specified by cond is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_signal(), pthread_cond_broadcast(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_signal, pthread_cond_broadcast - signal or broadcast a condition SYNOPSIS #include <pthread.h> int pthread_cond_signal(pthread_cond_t *cond); int pthread_cond_broad- cast(pthread_cond_t *cond); DESCRIPTION These two functions are used to unblock threads blocked on a condition variable. The pthread_cond_signal() call unblocks at least one of the threads that are blocked on the specified condition variable cond (if any threads are blocked on cond). The pthread_cond_broadcast() call unblocks all threads currently blocked on the specified condition variable cond. If more than one thread is blocked on a condition variable, the sched- uling policy determines the order in which threads are unblocked. When each thread unblocked as a result of a pthread_cond_signal() or pthread_cond_broadcast() returns from its call to pthread_cond_wait() or pthread_cond_timedwait(), the thread owns the mutex with which it called pthread_cond_wait() or pthread_cond_timedwait(). The thread(s) that are unblocked contend for the mutex according to the scheduling policy (if applicable), and as if each had called pthread_mutex_lock(). The pthread_cond_signal() or pthread_cond_broadcast() functions may be called by a thread whether or not it currently owns the mutex that threads calling pthread_cond_wait() or pthread_cond_timedwait() 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 pthread_cond_signal() or pthread_cond_broad- cast(). The pthread_cond_signal() and pthread_cond_broadcast() functions have no effect if there are no threads currently blocked on cond. RETURN VALUE If successful, the pthread_cond_signal() and pthread_cond_broadcast() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_cond_signal() and pthread_cond_broadcast() function may fail if: [EINVAL] The value cond does not refer to an initialised condition variable. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_init(), pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_wait, pthread_cond_timedwait - wait on a condition SYNOPSIS #include <pthread.h> int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex); int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mu- tex, const struct timespec *abstime); DESCRIPTION The pthread_cond_wait() and pthread_cond_timedwait() functions are used to block on a condition variable. They are called with mutex locked by the calling thread or undefined behaviour will result. These functions atomically release mutex and cause the calling thread to block on the condition variable cond; 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 pthread_cond_signal() or pthread_cond_broadcast() in that thread behaves as if it were issued after the about-to-block thread has blocked. Upon successful return, the mutex has been locked and is owned by the calling thread. When using condition variables there is always a boolean predicate in- volving shared variables associated with each condition wait that is true if the thread should proceed. Spurious wakeups from the pthread_cond_wait() or pthread_cond_timedwait() functions may occur. Since the return from pthread_cond_wait() or pthread_cond_timedwait() does not imply anything about the value of this predicate, the predi- cate should be re-evaluated upon such return. The effect of using more than one mutex for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable is undefined; that is, a condition variable becomes bound to a unique mutex when a thread waits on the condition variable, and this (dynamic) binding ends when the wait returns. A condition wait (whether timed or not) is a cancellation point. When the cancelability enable state of a thread is set to PTHREAD_CANCEL_DE- FERRED, 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 re- turning from the call to pthread_cond_wait() or pthread_cond_timed- wait(), but at that point notices the cancellation request and instead of returning to the caller of pthread_cond_wait() or pthread_cond_timedwait(), starts the thread cancellation activities, which includes calling cancellation cleanup handlers. A thread that has been unblocked because it has been canceled while blocked in a call to pthread_cond_wait() or pthread_cond_timedwait() does not consume any condition signal that may be directed concurrently at the condition variable if there are other threads blocked on the condition variable. The pthread_cond_timedwait() function is the same as pthread_cond_wait() except that an error is returned if the absolute time specified by abstime passes (that is, system time equals or ex- ceeds abstime) before the condition cond is signaled or broadcasted, or if the absolute time specified by abstime has already been passed at the time of the call. When such time-outs occur, pthread_cond_timed- wait() will nonetheless release and reacquire the mutex referenced by mutex. The function pthread_cond_timedwait() is also a cancellation point. If a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it was not interrupted, or it returns zero due to spurious wakeup. RETURN VALUE Except in the case of [ETIMEDOUT], all these error checks act as if they were performed immediately at the beginning of processing for the function and cause an error return, in effect, prior to modifying the state of the mutex specified by mutex or the condition variable speci- fied by cond. Upon successful completion, a value of zero is returned. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_cond_timedwait() function will fail if: [ETIMEDOUT] The time specified by abstime to pthread_cond_timedwait() has passed. The pthread_cond_wait() and pthread_cond_timedwait() functions may fail if: [EINVAL] The value specified by cond, mutex, or abstime is invalid. [EINVAL] Different mutexes were supplied for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition vari- able. [EINVAL] The mutex was not owned by the current thread at the time of the call. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_signal(), pthread_cond_broadcast(), <pthread.h>. ______________________________________________________________________ NAME pthread_cond_wait, pthread_cond_timedwait - wait on a condition SYNOPSIS #include <pthread.h> int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex); int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mu- tex, const struct timespec *abstime); DESCRIPTION The pthread_cond_wait() and pthread_cond_timedwait() functions are used to block on a condition variable. They are called with mutex locked by the calling thread or undefined behaviour will result. These functions atomically release mutex and cause the calling thread to block on the condition variable cond; 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 pthread_cond_signal() or pthread_cond_broadcast() in that thread behaves as if it were issued after the about-to-block thread has blocked. Upon successful return, the mutex has been locked and is owned by the calling thread. When using condition variables there is always a boolean predicate in- volving shared variables associated with each condition wait that is true if the thread should proceed. Spurious wakeups from the pthread_cond_wait() or pthread_cond_timedwait() functions may occur. Since the return from pthread_cond_wait() or pthread_cond_timedwait() does not imply anything about the value of this predicate, the predi- cate should be re-evaluated upon such return. The effect of using more than one mutex for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable is undefined; that is, a condition variable becomes bound to a unique mutex when a thread waits on the condition variable, and this (dynamic) binding ends when the wait returns. A condition wait (whether timed or not) is a cancellation point. When the cancelability enable state of a thread is set to PTHREAD_CANCEL_DE- FERRED, 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 re- turning from the call to pthread_cond_wait() or pthread_cond_timed- wait(), but at that point notices the cancellation request and instead of returning to the caller of pthread_cond_wait() or pthread_cond_timedwait(), starts the thread cancellation activities, which includes calling cancellation cleanup handlers. A thread that has been unblocked because it has been canceled while blocked in a call to pthread_cond_wait() or pthread_cond_timedwait() does not consume any condition signal that may be directed concurrently at the condition variable if there are other threads blocked on the condition variable. The pthread_cond_timedwait() function is the same as pthread_cond_wait() except that an error is returned if the absolute time specified by abstime passes (that is, system time equals or ex- ceeds abstime) before the condition cond is signaled or broadcasted, or if the absolute time specified by abstime has already been passed at the time of the call. When such time-outs occur, pthread_cond_timed- wait() will nonetheless release and reacquire the mutex referenced by mutex. The function pthread_cond_timedwait() is also a cancellation point. If a signal is delivered to a thread waiting for a condition variable, upon return from the signal handler the thread resumes waiting for the condition variable as if it was not interrupted, or it returns zero due to spurious wakeup. RETURN VALUE Except in the case of [ETIMEDOUT], all these error checks act as if they were performed immediately at the beginning of processing for the function and cause an error return, in effect, prior to modifying the state of the mutex specified by mutex or the condition variable speci- fied by cond. Upon successful completion, a value of zero is returned. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_cond_timedwait() function will fail if: [ETIMEDOUT] The time specified by abstime to pthread_cond_timedwait() has passed. The pthread_cond_wait() and pthread_cond_timedwait() functions may fail if: [EINVAL] The value specified by cond, mutex, or abstime is invalid. [EINVAL] Different mutexes were supplied for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition vari- able. [EINVAL] The mutex was not owned by the current thread at the time of the call. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_signal(), pthread_cond_broadcast(), <pthread.h>. ______________________________________________________________________ NAME pthread_condattr_init, pthread_condattr_destroy - initialise and de- stroy condition variable attributes object SYNOPSIS #include <pthread.h> int pthread_condattr_init(pthread_condattr_t *attr); int pthread_con- dattr_destroy(pthread_condattr_t *attr); DESCRIPTION The function pthread_condattr_init() initialises a condition variable attributes object attr with the default value for all of the attributes defined by the implementation. Attempting to initialise an already initialised condition variable at- tributes object results in undefined behaviour. After a condition variable attributes object has been used to ini- tialise one or more condition variables, any function affecting the at- tributes object (including destruction) does not affect any previously initialised condition variables. The pthread_condattr_destroy() function destroys a condition variable attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_condattr_destroy() to set the object referenced by attr to an invalid value. A destroyed condition variable attributes object can be re-initialised using pthread_condattr_init(); the results of otherwise referencing the object after it has been de- stroyed are undefined. Additional attributes, their default values, and the names of the asso- ciated functions to get and set those attribute values are implementa- tion-dependent. RETURN VALUE If successful, the pthread_condattr_init() and pthread_condattr_de- stroy() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_condattr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the condition variable at- tributes object. The pthread_condattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_condattr_getpshared(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_condattr_getpshared, pthread_condattr_setpshared - get and set the process-shared condition variable attributes SYNOPSIS #include <pthread.h> int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared); DESCRIPTION The pthread_condattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_condattr_setpshared() function is used to set the process- shared attribute in an initialised attributes object referenced by attr. The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition variable to be operated upon by any thread that has access to the memory where the condition variable is allocated, even if the condition variable is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the condition variable will only be operated upon by threads created within the same process as the thread that initialised the condition variable; if threads of differing processes attempt to operate on such a condition variable, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE. Additional attributes, their default values, and the names of the asso- ciated functions to get and set those attribute values are implementa- tion-dependent. RETURN VALUE If successful, the pthread_condattr_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error. If successful, the pthread_condattr_getpshared() function returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_condattr_getpshared() and pthread_condattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_condattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_condattr_init(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_condattr_init, pthread_condattr_destroy - initialise and de- stroy condition variable attributes object SYNOPSIS #include <pthread.h> int pthread_condattr_init(pthread_condattr_t *attr); int pthread_con- dattr_destroy(pthread_condattr_t *attr); DESCRIPTION The function pthread_condattr_init() initialises a condition variable attributes object attr with the default value for all of the attributes defined by the implementation. Attempting to initialise an already initialised condition variable at- tributes object results in undefined behaviour. After a condition variable attributes object has been used to ini- tialise one or more condition variables, any function affecting the at- tributes object (including destruction) does not affect any previously initialised condition variables. The pthread_condattr_destroy() function destroys a condition variable attributes object; the object becomes, in effect, uninitialised. An implementation may cause pthread_condattr_destroy() to set the object referenced by attr to an invalid value. A destroyed condition variable attributes object can be re-initialised using pthread_condattr_init(); the results of otherwise referencing the object after it has been de- stroyed are undefined. Additional attributes, their default values, and the names of the asso- ciated functions to get and set those attribute values are implementa- tion-dependent. RETURN VALUE If successful, the pthread_condattr_init() and pthread_condattr_de- stroy() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_condattr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the condition variable at- tributes object. The pthread_condattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_condattr_getpshared(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_condattr_getpshared, pthread_condattr_setpshared - get and set the process-shared condition variable attributes SYNOPSIS #include <pthread.h> int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared); DESCRIPTION The pthread_condattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_condattr_setpshared() function is used to set the process- shared attribute in an initialised attributes object referenced by attr. The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition variable to be operated upon by any thread that has access to the memory where the condition variable is allocated, even if the condition variable is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the condition variable will only be operated upon by threads created within the same process as the thread that initialised the condition variable; if threads of differing processes attempt to operate on such a condition variable, the behaviour is undefined. The default value of the attribute is PTHREAD_PROCESS_PRIVATE. Additional attributes, their default values, and the names of the asso- ciated functions to get and set those attribute values are implementa- tion-dependent. RETURN VALUE If successful, the pthread_condattr_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error. If successful, the pthread_condattr_getpshared() function returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_condattr_getpshared() and pthread_condattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_condattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_condattr_init(), pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_create - thread creation SYNOPSIS #include <pthread.h> int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void*), void *arg); DESCRIPTION The pthread_create() function is used to create a new thread, with at- tributes specified by attr, within a process. If attr is NULL, the de- fault attributes are used. If the attributes specified by attr are modified later, the thread's attributes are not affected. Upon suc- cessful completion, pthread_create() stores the ID of the created thread in the location referenced by thread. The thread is created executing start_routine with arg as its sole ar- gument. If the start_routine returns, the effect is as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. Note that the thread in which main() was origi- nally invoked differs from this. When it returns from main(), the ef- fect is as if there was an implicit call to exit() using the return value of main() as the exit status. The signal state of the new thread is initialised as follows: o The signal mask is inherited from the creating thread. o The set of signals pending for the new thread is empty. If pthread_create() fails, no new thread is created and the contents of the location referenced by thread are undefined. RETURN VALUE If successful, the pthread_create() function returns zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_create() function will fail if: [EAGAIN] The system lacked the necessary resources to create another thread, or the system-imposed limit on the total number of threads in a process PTHREAD_THREADS_MAX would be exceeded. [EINVAL] The value specified by attr is invalid. [EPERM] The caller does not have appropriate permission to set the required scheduling parameters or scheduling policy. The pthread_create() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_exit(), pthread_join(), fork(), <pthread.h>. ______________________________________________________________________ NAME pthread_detach - detach a thread SYNOPSIS #include <pthread.h> int pthread_detach(pthread_t thread); DESCRIPTION The pthread_detach() function is used to indicate to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, pthread_detach() will not cause it to terminate. The effect of multiple pthread_detach() calls on the same target thread is unspecified. RETURN VALUE If the call succeeds, pthread_detach() returns 0. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_detach() function will fail if: [EINVAL] The implementation has detected that the value specified by thread does not refer to a joinable thread. [ESRCH] No thread could be found corresponding to that specified by the given thread ID. The pthread_detach() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_join(), <pthread.h>. ______________________________________________________________________ NAME pthread_equal - compare thread IDs SYNOPSIS #include <pthread.h> int pthread_equal(pthread_t t1, pthread_t t2); DESCRIPTION This function compares the thread IDs t1 and t2. RETURN VALUE The pthread_equal() function returns a non-zero value if t1 and t2 are equal; otherwise, zero is returned. If either t1 or t2 are not valid thread IDs, the behaviour is unde- fined. ERRORS No errors are defined. The pthread_equal() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_self(), <pthread.h>. ______________________________________________________________________ NAME pthread_exit - thread termination SYNOPSIS #include <pthread.h> void pthread_exit(void *value_ptr); DESCRIPTION The pthread_exit() function terminates the calling thread and makes the value value_ptr 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 de- structor functions will be called in an unspecified order. Thread ter- mination 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 lim- ited to, calling any atexit() routines that may exist. An implicit call to pthread_exit() is made when a thread other than the thread in which main() was first invoked returns from the start routine that was used to create it. The function's return value serves as the thread's exit status. The behaviour of pthread_exit() is undefined if called from a cancella- tion cleanup handler or destructor function that was invoked as a re- sult of either an implicit or explicit call to pthread_exit(). After a thread has terminated, the result of access to local (auto) variables of the thread is undefined. Thus, references to local vari- ables of the exiting thread should not be used for the pthread_exit() value_ptr parameter value. The process exits with an exit status of 0 after the last thread has been terminated. The behaviour is as if the implementation called exit() with a zero argument at thread termination time. RETURN VALUE The pthread_exit() function cannot return to its caller. ERRORS No errors are defined. The pthread_exit() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_join(), exit(), _exit(), <pthread.h>. ______________________________________________________________________ NAME pthread_getconcurrency, pthread_setconcurrency - get or set level of concurrency SYNOPSIS #include <pthread.h> int pthread_getconcurrency(void); int pthread_setconcurrency(int new_level); DESCRIPTION Unbound threads in a process may or may not be required to be simulta- neously active. By default, the threads implementation ensures that a sufficient number of threads are active so that the process can con- tinue to make progress. While this conserves system resources, it may not produce the most effective level of concurrency. The pthread_setconcurrency() function allows an application to inform the threads implementation of its desired concurrency level, new_level. The actual level of concurrency provided by the implementation as a re- sult of this function call is unspecified. If new_level is zero, it causes the implementation to maintain the con- currency level at its discretion as if pthread_setconcurrency() was never called. The pthread_getconcurrency() function returns the value set by a previ- ous call to the pthread_setconcurrency() function. If the pthread_set- concurrency() function was not previously called, this function returns zero to indicate that the implementation is maintaining the concurrency level. When an application calls pthread_setconcurrency() it is informing the implementation of its desired concurrency level. The implementation uses this as a hint, not a requirement. If an implementation does not support multiplexing of user threads on top of several kernel scheduled entities, the pthread_setconcurrency() and pthread_getconcurrency() functions will be provided for source code compatibility but they will have no effect when called. To maintain the function semantics, the new_level parameter will be saved when pthread_setconcurrency() is called so that a subsequent call to pthread_getconcurrency() returns the same value. RETURN VALUE If successful, the pthread_setconcurrency() function returns zero. Otherwise, an error number is returned to indicate the error. The pthread_getconcurrency() function always returns the concurrency level set by a previous call to pthread_setconcurrency(). If the pthread_setconcurrency() function has never been called, pthread_get- concurrency() returns zero. ERRORS The pthread_setconcurrency() function will fail if: [EINVAL] The value specified by new_level is negative. [EAGAIN] The value specific by new_level would cause a system resource to be exceeded. EXAMPLES None. 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 pthread_getconcurrency() and pthread_setconcurrency() func- tions since their use may conflict with an applications use of these functions. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>. ______________________________________________________________________ NAME pthread_getschedparam, pthread_setschedparam - dynamic thread schedul- ing parameters access (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param); int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param); DESCRIPTION The pthread_getschedparam() and pthread_setschedparam() allow the scheduling policy and scheduling parameters of individual threads within a multi-threaded process to be retrieved and set. For SCHED_FIFO and SCHED_RR, the only required member of the sched_param structure is the priority sched_priority. For SCHED_OTHER, the af- fected scheduling parameters are implementation-dependent. The pthread_getschedparam() function retrieves the scheduling policy and scheduling parameters for the thread whose thread ID is given by thread and stores those values in policy and param, respectively. The priority value returned from pthread_getschedparam() is the value spec- ified by the most recent pthread_setschedparam() or pthread_create() call affecting the target thread, and reflects any temporary adjust- ments to its priority as a result of any priority inheritance or ceil- ing functions. The pthread_setschedparam() function sets the schedul- ing policy and associated scheduling parameters for the thread whose thread ID is given by thread to the policy and associated parameters provided in policy and param, respectively. The policy parameter may have the value SCHED_OTHER, that has implemen- tation-dependent scheduling parameters, SCHED_FIFO or SCHED_RR, that have the single scheduling parameter, priority. If the pthread_setschedparam() function fails, no scheduling parameters will be changed for the target thread. RETURN VALUE If successful, the pthread_getschedparam() and pthread_setschedparam() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_getschedparam() and pthread_setschedparam() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_getschedparam() function may fail if: [ESRCH] The value specified by thread does not refer to a existing thread. The pthread_setschedparam() function may fail if: [EINVAL] The value specified by policy or one of the scheduling parameters associated with the scheduling policy policy is invalid. [ENOTSUP] An attempt was made to set the policy or scheduling parameters to an unsupported value. [EPERM] The caller does not have the appropriate permission to set either the scheduling parameters or the scheduling policy of the specified thread. [EPERM] The implementation does not allow the application to modify one of the parameters to the value specified. [ESRCH] The value specified by thread does not refer to a existing thread. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO sched_setparam(), sched_getparam(), sched_setscheduler(), sched_getscheduler(), <pthread.h>, <sched.h>. ______________________________________________________________________ NAME pthread_setspecific, pthread_getspecific - thread-specific data manage- ment SYNOPSIS #include <pthread.h> int pthread_setspecific(pthread_key_t key, const void *value); void *pthread_getspecific(pthread_key_t key); DESCRIPTION The pthread_setspecific() function associates a thread-specific value with a key obtained via a previous call to pthread_key_create(). Dif- ferent threads may bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread. The pthread_getspecific() function returns the value currently bound to the specified key on behalf of the calling thread. The effect of calling pthread_setspecific() or pthread_getspecific() with a key value not obtained from pthread_key_create() or after key has been deleted with pthread_key_delete() is undefined. Both pthread_setspecific() and pthread_getspecific() may be called from a thread-specific data destructor function. However, calling pthread_setspecific() from a destructor may result in lost storage or infinite loops. Both functions may be implemented as macros. RETURN VALUE The function pthread_getspecific() returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, then the value NULL is returned. If successful, the pthread_setspecific() function returns zero. Other- wise, an error number is returned to indicate the error. ERRORS The pthread_setspecific() function will fail if: [ENOMEM] Insufficient memory exists to associate the value with the key. The pthread_setspecific() function may fail if: [EINVAL] The key value is invalid. No errors are returned from pthread_getspecific(). These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_key_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_join - wait for thread termination SYNOPSIS #include <pthread.h> int pthread_join(pthread_t thread, void **value_ptr); DESCRIPTION The pthread_join() function suspends execution of the calling thread until the target thread terminates, unless the target thread has al- ready terminated. On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by the terminating thread is made available in the location referenced by value_ptr. When a pthread_join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to pthread_join() specifying the same target thread are undefined. If the thread calling pthread_join() is canceled, then the target thread will not be detached. It is unspecified whether a thread that has exited but remains unjoined counts against _POSIX_THREAD_THREADS_MAX. RETURN VALUE If successful, the pthread_join() function returns zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_join() function will fail if: [EINVAL] The implementation has detected that the value specified by thread does not refer to a joinable thread. [ESRCH] No thread could be found corresponding to that specified by the given thread ID. The pthread_join() function may fail if: [EDEADLK] A deadlock was detected or the value of thread specifies the call- ing thread. The pthread_join() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), wait(), <pthread.h>. ______________________________________________________________________ NAME pthread_key_create - thread-specific data key creation SYNOPSIS #include <pthread.h> int pthread_key_create(pthread_key_t *key, void (*destructor)(void*)); DESCRIPTION This function creates a thread-specific data key visible to all threads in the process. Key values provided by pthread_key_create() 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 pthread_setspecific() are maintained on a per-thread basis and persist for the life of the calling thread. Upon key creation, the value NULL is associated with the new key in all active threads. Upon thread creation, the value NULL is associated with all defined keys in the new thread. An optional destructor function may be associated with each key value. At thread exit, if a key value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the function pointed to is called with the current associated value as its sole ar- gument. The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits. If, after all the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with associated destructors, then the process will be repeated. If, after at least PTHREAD_DESTRUCTOR_ITERATIONS iterations of destructor calls for outstanding non-NULL values, there are still some non-NULL values with associated destructors, implementations may stop calling destruc- tors, or they may continue calling destructors until no non-NULL values with associated destructors exist, even though this might result in an infinite loop. RETURN VALUE If successful, the pthread_key_create() function stores the newly cre- ated key value at *key and returns zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_key_create() function will fail if: [EAGAIN] The system lacked the necessary resources to create another thread- specific data key, or the system-imposed limit on the total number of keys per process PTHREAD_KEYS_MAX has been exceeded. [ENOMEM] Insufficient memory exists to create the key. The pthread_key_create() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_getspecific(), pthread_setspecific(), pthread_key_delete(), <pthread.h>. ______________________________________________________________________ NAME pthread_key_delete - thread-specific data key deletion SYNOPSIS #include <pthread.h> int pthread_key_delete(pthread_key_t key); DESCRIPTION This function deletes a thread-specific data key previously returned by pthread_key_create(). The thread-specific data values associated with key need not be NULL at the time pthread_key_delete() 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 pthread_key_delete() is called. Any attempt to use key following the call to pthread_key_delete() results in undefined behaviour. The pthread_key_delete() function is callable from within destructor functions. No destructor functions will be invoked by pthread_key_delete(). Any destructor function that may have been asso- ciated with key will no longer be called upon thread exit. RETURN VALUE If successful, the pthread_key_delete() function returns zero. Other- wise, an error number is returned to indicate the error. ERRORS The pthread_key_delete() function may fail if: [EINVAL] The key value is invalid. The pthread_key_delete() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_key_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_kill - send a signal to a thread SYNOPSIS #include <signal.h> int pthread_kill(pthread_t thread, int sig); DESCRIPTION The pthread_kill() function is used to request that a signal be deliv- ered to the specified thread. As in kill(), if sig is zero, error checking is performed but no signal is actually sent. RETURN VALUE Upon successful completion, the function returns a value of zero. Oth- erwise the function returns an error number. If the pthread_kill() function fails, no signal is sent. ERRORS The pthread_kill() function will fail if: [ESRCH] No thread could be found corresponding to that specified by the given thread ID. [EINVAL] The value of the sig argument is an invalid or unsupported signal number. The pthread_kill() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO kill(), pthread_self(), raise(), <signal.h>. ______________________________________________________________________ NAME pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a mu- tex SYNOPSIS #include <pthread.h> int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutex- attr_t *attr); int pthread_mutex_destroy(pthread_mutex_t *mutex); pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; DESCRIPTION The pthread_mutex_init() function initialises the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect is the same as passing the ad- dress of a default mutex attributes object. Upon successful initiali- sation, the state of the mutex becomes initialised and unlocked. Attempting to initialise an already initialised mutex results in unde- fined behaviour. The pthread_mutex_destroy() function destroys the mutex object refer- enced by mutex; the mutex object becomes, in effect, uninitialised. An implementation may cause pthread_mutex_destroy() to set the object ref- erenced by mutex to an invalid value. A destroyed mutex object can be re-initialised using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined. It is safe to destroy an initialised mutex that is unlocked. Attempt- ing to destroy a locked mutex results in undefined behaviour. In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialise mutexes that are statically allocated. The effect is equivalent to dynamic initialisa- tion by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed. RETURN VALUE If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return zero. Otherwise, an error number is returned to indi- cate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of process- ing for the function and cause an error return prior to modifying the state of the mutex specified by mutex. ERRORS The pthread_mutex_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another mutex. [ENOMEM] Insufficient memory exists to initialise the mutex. [EPERM] The caller does not have the privilege to perform the operation. The pthread_mutex_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by mutex, a previously initialised, but not yet de- stroyed, mutex. [EINVAL] The value specified by attr is invalid. The pthread_mutex_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timed- wait()) by another thread. [EINVAL] The value specified by mutex is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_getprioceiling(), pthread_mutex_lock(), pthread_mutex_un- lock(), pthread_mutex_setprioceiling(), pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_setprioceiling, pthread_mutex_getprioceiling - change the priority ceiling of a mutex (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceil- ing, int *old_ceiling); int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling); DESCRIPTION The pthread_mutex_getprioceiling() function returns the current prior- ity ceiling of the mutex. The pthread_mutex_setprioceiling() 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 ceil- ing is returned in old_ceiling. The process of locking the mutex need not adhere to the priority protect protocol. If the pthread_mutex_setprioceiling() function fails, the mutex prior- ity ceiling is not changed. RETURN VALUE If successful, the pthread_mutex_setprioceiling() and pthread_mu- tex_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutex_getprioceiling() and pthread_mutex_setprioceiling() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIO_PROTECT is not defined and the imple- mentation does not support the function. The pthread_mutex_setprioceiling() and pthread_mutex_getprioceiling() functions may fail if: [EINVAL] The priority requested by prioceiling is out of range. [EINVAL] The value specified by mutex does not refer to a currently existing mutex. [ENOSYS] The implementation does not support the priority ceiling protocol for mutexes. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_trylock(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a mu- tex SYNOPSIS #include <pthread.h> int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutex- attr_t *attr); int pthread_mutex_destroy(pthread_mutex_t *mutex); pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; DESCRIPTION The pthread_mutex_init() function initialises the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect is the same as passing the ad- dress of a default mutex attributes object. Upon successful initiali- sation, the state of the mutex becomes initialised and unlocked. Attempting to initialise an already initialised mutex results in unde- fined behaviour. The pthread_mutex_destroy() function destroys the mutex object refer- enced by mutex; the mutex object becomes, in effect, uninitialised. An implementation may cause pthread_mutex_destroy() to set the object ref- erenced by mutex to an invalid value. A destroyed mutex object can be re-initialised using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined. It is safe to destroy an initialised mutex that is unlocked. Attempt- ing to destroy a locked mutex results in undefined behaviour. In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialise mutexes that are statically allocated. The effect is equivalent to dynamic initialisa- tion by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed. RETURN VALUE If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return zero. Otherwise, an error number is returned to indi- cate the error. The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of process- ing for the function and cause an error return prior to modifying the state of the mutex specified by mutex. ERRORS The pthread_mutex_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another mutex. [ENOMEM] Insufficient memory exists to initialise the mutex. [EPERM] The caller does not have the privilege to perform the operation. The pthread_mutex_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by mutex, a previously initialised, but not yet de- stroyed, mutex. [EINVAL] The value specified by attr is invalid. The pthread_mutex_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait() or pthread_cond_timed- wait()) by another thread. [EINVAL] The value specified by mutex is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_getprioceiling(), pthread_mutex_lock(), pthread_mutex_un- lock(), pthread_mutex_setprioceiling(), pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a mutex SYNOPSIS #include <pthread.h> int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_try- lock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex); DESCRIPTION The mutex object referenced by mutex is locked by calling pthread_mu- tex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mu- tex object referenced by mutex in the locked state with the calling thread as its owner. If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results. If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mu- tex that it has not locked or a mutex which is unlocked, an error will be returned. If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mu- tex 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 re- turned. If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour. The function pthread_mutex_trylock() is identical to pthread_mu- tex_lock() except that if the mutex object referenced by mutex is cur- rently locked (by any thread, including the current thread), the call returns immediately. The pthread_mutex_unlock() function releases the mutex object refer- enced by mutex. 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 mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex). If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted. RETURN VALUE If successful, the pthread_mutex_lock() and pthread_mutex_unlock() functions return zero. Otherwise, an error number is returned to indi- cate the error. The function pthread_mutex_trylock() returns zero if a lock on the mu- tex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if: [EINVAL] The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling. The pthread_mutex_trylock() function will fail if: [EBUSY] The mutex could not be acquired because it was already locked. The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_un- lock() functions may fail if: [EINVAL] The value specified by mutex does not refer to an initialised mutex object. [EAGAIN] The mutex could not be acquired because the maximum number of re- cursive locks for mutex has been exceeded. The pthread_mutex_lock() function may fail if: [EDEADLK] The current thread already owns the mutex. The pthread_mutex_unlock() function may fail if: [EPERM] The current thread does not own the mutex. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_setprioceiling, pthread_mutex_getprioceiling - change the priority ceiling of a mutex (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceil- ing, int *old_ceiling); int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling); DESCRIPTION The pthread_mutex_getprioceiling() function returns the current prior- ity ceiling of the mutex. The pthread_mutex_setprioceiling() 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 ceil- ing is returned in old_ceiling. The process of locking the mutex need not adhere to the priority protect protocol. If the pthread_mutex_setprioceiling() function fails, the mutex prior- ity ceiling is not changed. RETURN VALUE If successful, the pthread_mutex_setprioceiling() and pthread_mu- tex_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutex_getprioceiling() and pthread_mutex_setprioceiling() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIO_PROTECT is not defined and the imple- mentation does not support the function. The pthread_mutex_setprioceiling() and pthread_mutex_getprioceiling() functions may fail if: [EINVAL] The priority requested by prioceiling is out of range. [EINVAL] The value specified by mutex does not refer to a currently existing mutex. [ENOSYS] The implementation does not support the priority ceiling protocol for mutexes. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_unlock(), pthread_mutex_trylock(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a mutex SYNOPSIS #include <pthread.h> int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_try- lock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex); DESCRIPTION The mutex object referenced by mutex is locked by calling pthread_mu- tex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mu- tex object referenced by mutex in the locked state with the calling thread as its owner. If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results. If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mu- tex that it has not locked or a mutex which is unlocked, an error will be returned. If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mu- tex 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 re- turned. If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour. The function pthread_mutex_trylock() is identical to pthread_mu- tex_lock() except that if the mutex object referenced by mutex is cur- rently locked (by any thread, including the current thread), the call returns immediately. The pthread_mutex_unlock() function releases the mutex object refer- enced by mutex. 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 mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex). If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted. RETURN VALUE If successful, the pthread_mutex_lock() and pthread_mutex_unlock() functions return zero. Otherwise, an error number is returned to indi- cate the error. The function pthread_mutex_trylock() returns zero if a lock on the mu- tex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if: [EINVAL] The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling. The pthread_mutex_trylock() function will fail if: [EBUSY] The mutex could not be acquired because it was already locked. The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_un- lock() functions may fail if: [EINVAL] The value specified by mutex does not refer to an initialised mutex object. [EAGAIN] The mutex could not be acquired because the maximum number of re- cursive locks for mutex has been exceeded. The pthread_mutex_lock() function may fail if: [EDEADLK] The current thread already owns the mutex. The pthread_mutex_unlock() function may fail if: [EPERM] The current thread does not own the mutex. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a mutex SYNOPSIS #include <pthread.h> int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_try- lock(pthread_mutex_t *mutex); int pthread_mutex_unlock(pthread_mutex_t *mutex); DESCRIPTION The mutex object referenced by mutex is locked by calling pthread_mu- tex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mu- tex object referenced by mutex in the locked state with the calling thread as its owner. If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, undefined behaviour results. If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mu- tex that it has not locked or a mutex which is unlocked, an error will be returned. If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mu- tex 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 re- turned. If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behaviour. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behaviour. Attempting to unlock the mutex if it is not locked results in undefined behaviour. The function pthread_mutex_trylock() is identical to pthread_mu- tex_lock() except that if the mutex object referenced by mutex is cur- rently locked (by any thread, including the current thread), the call returns immediately. The pthread_mutex_unlock() function releases the mutex object refer- enced by mutex. 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 mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy is used to determine which thread shall acquire the mutex. (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available when the count reaches zero and the calling thread no longer has any locks on this mutex). If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread resumes waiting for the mutex as if it was not interrupted. RETURN VALUE If successful, the pthread_mutex_lock() and pthread_mutex_unlock() functions return zero. Otherwise, an error number is returned to indi- cate the error. The function pthread_mutex_trylock() returns zero if a lock on the mu- tex object referenced by mutex is acquired. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutex_lock() and pthread_mutex_trylock() functions will fail if: [EINVAL] The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex's current priority ceiling. The pthread_mutex_trylock() function will fail if: [EBUSY] The mutex could not be acquired because it was already locked. The pthread_mutex_lock(), pthread_mutex_trylock() and pthread_mutex_un- lock() functions may fail if: [EINVAL] The value specified by mutex does not refer to an initialised mutex object. [EAGAIN] The mutex could not be acquired because the maximum number of re- cursive locks for mutex has been exceeded. The pthread_mutex_lock() function may fail if: [EDEADLK] The current thread already owns the mutex. The pthread_mutex_unlock() function may fail if: [EPERM] The current thread does not own the mutex. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_init, pthread_mutexattr_destroy - initialise and de- stroy mutex attributes object SYNOPSIS #include <pthread.h> int pthread_mutexattr_init(pthread_mutexattr_t *attr); int pthread_mu- texattr_destroy(pthread_mutexattr_t *attr); DESCRIPTION The function pthread_mutexattr_init() initialises a mutex attributes object attr with the default value for all of the attributes defined by the implementation. The effect of initialising an already initialised mutex attributes ob- ject is undefined. After a mutex attributes object has been used to initialise one or more mutexes, any function affecting the attributes object (including de- struction) does not affect any previously initialised mutexes. The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialised. An implementa- tion may cause pthread_mutexattr_destroy() to set the object referenced by attr to an invalid value. A destroyed mutex attributes object can be re-initialised using pthread_mutexattr_init(); the results of other- wise referencing the object after it has been destroyed are undefined. RETURN VALUE Upon successful completion, pthread_mutexattr_init() and pthread_mutex- attr_destroy() return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_init() function may fail if: [ENOMEM] Insufficient memory exists to initialise the mutex attributes ob- ject. The pthread_mutexattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling - set and get prioceiling attribute of mutex attribute object (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling); int pthread_mutexattr_getprioceiling(const pthread_mutex- attr_t *attr, int *prioceiling); DESCRIPTION The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions, respectively, set and get the priority ceiling at- tribute of a mutex attribute object pointed to by attr which was previ- ously created by the function pthread_mutexattr_init(). The prioceiling attribute contains the priority ceiling of initialised mutexes. The values of prioceiling will be within the maximum range of priorities defined by SCHED_FIFO. The prioceiling attribute defines the priority ceiling of initialised mutexes, which is the minimum priority level at which the critical sec- tion guarded by the mutex is executed. In order to avoid priority in- version, 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 prioceiling will be within the max- imum range of priorities defined under the SCHED_FIFO scheduling pol- icy. RETURN VALUE Upon successful completion, the pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIO_PROTECT is not defined and the imple- mentation does not support the function. The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions may fail if: [EINVAL] The value specified by attr or prioceiling is invalid. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol - set and get protocol attribute of mutex attribute object (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int proto- col); int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol); DESCRIPTION The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions, respectively, set and get the protocol attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init(). The protocol attribute defines the protocol to be followed in utilising mutexes. The value of protocol may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, which are defined by the header <pthread.h>. When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol at- tribute, its priority and scheduling are not affected by its mutex own- ership. When a thread is blocking higher priority threads because of owning one or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it executes at the higher of its priority or the priority of the highest priority thread waiting on any of the mutexes owned by this thread and initialised with this protocol. When a thread owns one or more mutexes initialised with the PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its prior- ity or the highest of the priority ceilings of all the mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these mutexes or not. While a thread is holding a mutex which has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be sub- ject 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 sched_setparam(). Likewise, when a thread unlocks a mutex that has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attrib- utes, it will not be subject to being moved to the tail of the schedul- ing queue at its priority in the event that its original priority is changed. If a thread simultaneously owns several mutexes initialised with dif- ferent protocols, it will execute at the highest of the priorities that it would have obtained by each of these protocols. When a thread makes a call to pthread_mutex_lock(), if the symbol _POSIX_THREAD_PRIO_INHERIT is defined and the mutex was initialised with the protocol attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the mutex is owned by another thread, that owner thread will inherit the priority level of the call- ing thread as long as it continues to own the mutex. The implementa- tion updates its execution priority to the maximum of its assigned pri- ority and all its inherited priorities. Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority in- heritance effect will be propagated to this other owner thread, in a recursive manner. RETURN VALUE Upon successful completion, the pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions will fail if: [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. [ENOTSUP] The value specified by protocol is an unsupported value. The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions may fail if: [EINVAL] The value specified by attr ro protocol is invalid. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - set and get process-shared attribute SYNOPSIS #include <pthread.h> int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared); DESCRIPTION The pthread_mutexattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_mutexattr_setpshared() function is used to set the process- shared attribute in an initialised attributes object referenced by attr. The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon by threads created within the same process as the thread that initialised the mutex; if threads of differing processes attempt to operate on such a mutex, the behaviour is undefined. The default value of the at- tribute is PTHREAD_PROCESS_PRIVATE. RETURN VALUE Upon successful completion, pthread_mutexattr_setpshared() returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, pthread_mutexattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_mutexattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_gettype, pthread_mutexattr_settype - get or set a mu- tex type SYNOPSIS #include <pthread.h> int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type); int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type); DESCRIPTION The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions respectively get and set the mutex type attribute. This at- tribute is set in the type parameter to these functions. The default value of the type attribute is PTHREAD_MUTEX_DEFAULT. The type of mutex is contained in the type attribute of the mutex at- tributes. Valid mutex types include: PTHREAD_MUTEX_NORMAL This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. At- tempting to unlock a mutex locked by a different thread results in undefined behaviour. Attempting to unlock an unlocked mutex re- sults in undefined behaviour. 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 un- lock an unlocked mutex will return with an error. PTHREAD_MUTEX_RECURSIVE A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which an- other thread has locked will return with an error. A thread at- tempting to unlock an unlocked mutex will return with an error. PTHREAD_MUTEX_DEFAULT Attempting to recursively lock a mutex of this type results in un- defined behaviour. Attempting to unlock a mutex of this type which was not locked by the calling thread results in undefined behav- iour. 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. RETURN VALUE If successful, the pthread_mutexattr_settype() function returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, the pthread_mutexattr_gettype() function returns zero and stores the value of the type attribute of attr into the object referenced by the type parameter. Otherwise an error is re- turned to indicate the error. ERRORS The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions will fail if: [EINVAL] The value type is invalid. The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions may fail if: [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE It is advised that an application should not use a PTHREAD_MUTEX_RECUR- SIVE mutex with condition variables because the implicit unlock per- formed for a pthread_cond_wait() or pthread_cond_timedwait() 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 predi- cate. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_init, pthread_mutexattr_destroy - initialise and de- stroy mutex attributes object SYNOPSIS #include <pthread.h> int pthread_mutexattr_init(pthread_mutexattr_t *attr); int pthread_mu- texattr_destroy(pthread_mutexattr_t *attr); DESCRIPTION The function pthread_mutexattr_init() initialises a mutex attributes object attr with the default value for all of the attributes defined by the implementation. The effect of initialising an already initialised mutex attributes ob- ject is undefined. After a mutex attributes object has been used to initialise one or more mutexes, any function affecting the attributes object (including de- struction) does not affect any previously initialised mutexes. The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialised. An implementa- tion may cause pthread_mutexattr_destroy() to set the object referenced by attr to an invalid value. A destroyed mutex attributes object can be re-initialised using pthread_mutexattr_init(); the results of other- wise referencing the object after it has been destroyed are undefined. RETURN VALUE Upon successful completion, pthread_mutexattr_init() and pthread_mutex- attr_destroy() return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_init() function may fail if: [ENOMEM] Insufficient memory exists to initialise the mutex attributes ob- ject. The pthread_mutexattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling - set and get prioceiling attribute of mutex attribute object (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling); int pthread_mutexattr_getprioceiling(const pthread_mutex- attr_t *attr, int *prioceiling); DESCRIPTION The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions, respectively, set and get the priority ceiling at- tribute of a mutex attribute object pointed to by attr which was previ- ously created by the function pthread_mutexattr_init(). The prioceiling attribute contains the priority ceiling of initialised mutexes. The values of prioceiling will be within the maximum range of priorities defined by SCHED_FIFO. The prioceiling attribute defines the priority ceiling of initialised mutexes, which is the minimum priority level at which the critical sec- tion guarded by the mutex is executed. In order to avoid priority in- version, 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 prioceiling will be within the max- imum range of priorities defined under the SCHED_FIFO scheduling pol- icy. RETURN VALUE Upon successful completion, the pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprioceiling() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIO_PROTECT is not defined and the imple- mentation does not support the function. The pthread_mutexattr_setprioceiling() and pthread_mutexattr_getprio- ceiling() functions may fail if: [EINVAL] The value specified by attr or prioceiling is invalid. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol - set and get protocol attribute of mutex attribute object (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int proto- col); int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol); DESCRIPTION The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions, respectively, set and get the protocol attribute of a mutex attribute object pointed to by attr which was previously created by the function pthread_mutexattr_init(). The protocol attribute defines the protocol to be followed in utilising mutexes. The value of protocol may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, which are defined by the header <pthread.h>. When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol at- tribute, its priority and scheduling are not affected by its mutex own- ership. When a thread is blocking higher priority threads because of owning one or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it executes at the higher of its priority or the priority of the highest priority thread waiting on any of the mutexes owned by this thread and initialised with this protocol. When a thread owns one or more mutexes initialised with the PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its prior- ity or the highest of the priority ceilings of all the mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these mutexes or not. While a thread is holding a mutex which has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attributes, it will not be sub- ject 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 sched_setparam(). Likewise, when a thread unlocks a mutex that has been initialised with the PRIO_INHERIT or PRIO_PROTECT protocol attrib- utes, it will not be subject to being moved to the tail of the schedul- ing queue at its priority in the event that its original priority is changed. If a thread simultaneously owns several mutexes initialised with dif- ferent protocols, it will execute at the highest of the priorities that it would have obtained by each of these protocols. When a thread makes a call to pthread_mutex_lock(), if the symbol _POSIX_THREAD_PRIO_INHERIT is defined and the mutex was initialised with the protocol attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the mutex is owned by another thread, that owner thread will inherit the priority level of the call- ing thread as long as it continues to own the mutex. The implementa- tion updates its execution priority to the maximum of its assigned pri- ority and all its inherited priorities. Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority in- heritance effect will be propagated to this other owner thread, in a recursive manner. RETURN VALUE Upon successful completion, the pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions will fail if: [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. [ENOTSUP] The value specified by protocol is an unsupported value. The pthread_mutexattr_setprotocol() and pthread_mutexattr_getprotocol() functions may fail if: [EINVAL] The value specified by attr ro protocol is invalid. [EPERM] The caller does not have the privilege to perform the operation. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - set and get process-shared attribute SYNOPSIS #include <pthread.h> int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared); DESCRIPTION The pthread_mutexattr_getpshared() function obtains the value of the process-shared attribute from the attributes object referenced by attr. The pthread_mutexattr_setpshared() function is used to set the process- shared attribute in an initialised attributes object referenced by attr. The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the mutex will only be operated upon by threads created within the same process as the thread that initialised the mutex; if threads of differing processes attempt to operate on such a mutex, the behaviour is undefined. The default value of the at- tribute is PTHREAD_PROCESS_PRIVATE. RETURN VALUE Upon successful completion, pthread_mutexattr_setpshared() returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, pthread_mutexattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_mutexattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_mutex_init(), pthread_mutexattr_init(), pthread_cond_init(), <pthread.h>. ______________________________________________________________________ NAME pthread_mutexattr_gettype, pthread_mutexattr_settype - get or set a mu- tex type SYNOPSIS #include <pthread.h> int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type); int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type); DESCRIPTION The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions respectively get and set the mutex type attribute. This at- tribute is set in the type parameter to these functions. The default value of the type attribute is PTHREAD_MUTEX_DEFAULT. The type of mutex is contained in the type attribute of the mutex at- tributes. Valid mutex types include: PTHREAD_MUTEX_NORMAL This type of mutex does not detect deadlock. A thread attempting to relock this mutex without first unlocking it will deadlock. At- tempting to unlock a mutex locked by a different thread results in undefined behaviour. Attempting to unlock an unlocked mutex re- sults in undefined behaviour. 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 un- lock an unlocked mutex will return with an error. PTHREAD_MUTEX_RECURSIVE A thread attempting to relock this mutex without first unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex require the same number of unlocks to release the mutex before another thread can acquire the mutex. A thread attempting to unlock a mutex which an- other thread has locked will return with an error. A thread at- tempting to unlock an unlocked mutex will return with an error. PTHREAD_MUTEX_DEFAULT Attempting to recursively lock a mutex of this type results in un- defined behaviour. Attempting to unlock a mutex of this type which was not locked by the calling thread results in undefined behav- iour. 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. RETURN VALUE If successful, the pthread_mutexattr_settype() function returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, the pthread_mutexattr_gettype() function returns zero and stores the value of the type attribute of attr into the object referenced by the type parameter. Otherwise an error is re- turned to indicate the error. ERRORS The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions will fail if: [EINVAL] The value type is invalid. The pthread_mutexattr_gettype() and pthread_mutexattr_settype() func- tions may fail if: [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE It is advised that an application should not use a PTHREAD_MUTEX_RECUR- SIVE mutex with condition variables because the implicit unlock per- formed for a pthread_cond_wait() or pthread_cond_timedwait() 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 predi- cate. FUTURE DIRECTIONS None. SEE ALSO pthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>. ______________________________________________________________________ NAME pthread_once - dynamic package initialisation SYNOPSIS #include <pthread.h> int pthread_once(pthread_once_t *once_control, void (*init_rou- tine)(void)); pthread_once_t once_control = PTHREAD_ONCE_INIT; DESCRIPTION The first call to pthread_once() by any thread in a process, with a given once_control, will call the init_routine() with no arguments. Subsequent calls of pthread_once() with the same once_control will not call the init_routine(). On return from pthread_once(), it is guaran- teed that init_routine() has completed. The once_control parameter is used to determine whether the associated initialisation routine has been called. The function pthread_once() is not a cancellation point. However, if init_routine() is a cancellation point and is canceled, the effect on once_control is as if pthread_once() was never called. The constant PTHREAD_ONCE_INIT is defined by the header <pthread.h>. The behaviour of pthread_once() is undefined if once_control has auto- matic storage duration or is not initialised by PTHREAD_ONCE_INIT. RETURN VALUE Upon successful completion, pthread_once() returns zero. Otherwise, an error number is returned to indicate the error. ERRORS No errors are defined. The pthread_once() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO <pthread,h>. ______________________________________________________________________ NAME pthread_rwlock_init, pthread_rwlock_destroy - initialise or destroy a read-write lock object SYNOPSIS #include <pthread.h> int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlock- attr_t *attr); int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); pthread_rwlock_t rwlock=PTHREAD_RWLOCK_INITIALIZER; DESCRIPTION The pthread_rwlock_init() function initialises the read-write lock ref- erenced by rwlock with the attributes referenced by attr. If attr is NULL, the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialised, the lock can be used any number of times without being re-initialised. Upon successful initialisation, the state of the read-write lock becomes initialised and unlocked. Results are undefined if pthread_rwlock_init() is called specifying an already initialised read-write lock. Results are undefined if a read-write lock is used without first being initialised. If the pthread_rwlock_init() function fails, rwlock is not initialised and the contents of rwlock are undefined. The pthread_rwlock_destroy() function destroys the read-write lock ob- ject referenced by rwlock 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 pthread_rwlock_init(). An implemen- tation may cause pthread_rwlock_destroy() to set the object referenced by rwlock to an invalid value. Results are undefined if pthread_rwlock_destroy() is called when any thread holds rwlock. At- tempting to destroy an uninitialised read-write lock results in unde- fined behaviour. A destroyed read-write lock object can be re-ini- tialised using pthread_rwlock_init(); the results of otherwise refer- encing the read-write lock object after it has been destroyed are unde- fined. In cases where default read-write lock attributes are appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks that are statically allocated. The effect is equivalent to dy- namic initialisation by a call to pthread_rwlock_init() with the para- meter attr specified as NULL, except that no error checks are per- formed. RETURN VALUE If successful, the pthread_rwlock_init() and pthread_rwlock_destroy() functions return zero. Otherwise, an error number is returned to indi- cate the error. The [EBUSY] and [EINVAL] error checks, if implemented, will act as if they were performed immediately at the beginning of pro- cessing for the function and caused an error return prior to modifying the state of the read-write lock specified by rwlock. ERRORS The pthread_rwlock_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another read-write lock. [ENOMEM] Insufficient memory exists to initialise the read-write lock. [EPERM] The caller does not have the privilege to perform the operation. The pthread_rwlock_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by rwlock, a previously initialised but not yet de- stroyed read-write lock. [EINVAL] The value specified by attr is invalid. The pthread_rwlock_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by rwlock while it is locked. [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_rdlock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock(). ______________________________________________________________________ NAME pthread_rwlock_init, pthread_rwlock_destroy - initialise or destroy a read-write lock object SYNOPSIS #include <pthread.h> int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlock- attr_t *attr); int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); pthread_rwlock_t rwlock=PTHREAD_RWLOCK_INITIALIZER; DESCRIPTION The pthread_rwlock_init() function initialises the read-write lock ref- erenced by rwlock with the attributes referenced by attr. If attr is NULL, the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialised, the lock can be used any number of times without being re-initialised. Upon successful initialisation, the state of the read-write lock becomes initialised and unlocked. Results are undefined if pthread_rwlock_init() is called specifying an already initialised read-write lock. Results are undefined if a read-write lock is used without first being initialised. If the pthread_rwlock_init() function fails, rwlock is not initialised and the contents of rwlock are undefined. The pthread_rwlock_destroy() function destroys the read-write lock ob- ject referenced by rwlock 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 pthread_rwlock_init(). An implemen- tation may cause pthread_rwlock_destroy() to set the object referenced by rwlock to an invalid value. Results are undefined if pthread_rwlock_destroy() is called when any thread holds rwlock. At- tempting to destroy an uninitialised read-write lock results in unde- fined behaviour. A destroyed read-write lock object can be re-ini- tialised using pthread_rwlock_init(); the results of otherwise refer- encing the read-write lock object after it has been destroyed are unde- fined. In cases where default read-write lock attributes are appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be used to initialise read-write locks that are statically allocated. The effect is equivalent to dy- namic initialisation by a call to pthread_rwlock_init() with the para- meter attr specified as NULL, except that no error checks are per- formed. RETURN VALUE If successful, the pthread_rwlock_init() and pthread_rwlock_destroy() functions return zero. Otherwise, an error number is returned to indi- cate the error. The [EBUSY] and [EINVAL] error checks, if implemented, will act as if they were performed immediately at the beginning of pro- cessing for the function and caused an error return prior to modifying the state of the read-write lock specified by rwlock. ERRORS The pthread_rwlock_init() function will fail if: [EAGAIN] The system lacked the necessary resources (other than memory) to initialise another read-write lock. [ENOMEM] Insufficient memory exists to initialise the read-write lock. [EPERM] The caller does not have the privilege to perform the operation. The pthread_rwlock_init() function may fail if: [EBUSY] The implementation has detected an attempt to re-initialise the ob- ject referenced by rwlock, a previously initialised but not yet de- stroyed read-write lock. [EINVAL] The value specified by attr is invalid. The pthread_rwlock_destroy() function may fail if: [EBUSY] The implementation has detected an attempt to destroy the object referenced by rwlock while it is locked. [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_rdlock(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock(). ______________________________________________________________________ NAME pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock a read-write lock object for reading SYNOPSIS #include <pthread.h> int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); DESCRIPTION The pthread_rwlock_rdlock() function applies a read lock to the read- write lock referenced by rwlock. 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 ac- quires 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 ac- quired, the calling thread blocks (that is, it does not return from the pthread_rwlock_rdlock() call) until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made. Implementations are allowed to favour writers over readers to avoid writer starvation. A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the pthread_rwlock_rdlock() function n times). If so, the thread must perform matching unlocks (that is, it must call the pthread_rwlock_unlock() function n times). The function pthread_rwlock_tryrdlock() applies a read lock as in the pthread_rwlock_rdlock() function with the exception that the function fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock. Results are undefined if any of these functions are called with an uninitialised read-write lock. If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the signal handler the thread resumes waiting for the read-write lock for reading as if it was not interrupted. RETURN VALUE If successful, the pthread_rwlock_rdlock() function returns zero. Oth- erwise, an error number is returned to indicate the error. The function pthread_rwlock_tryrdlock() returns zero if the lock for reading on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error. ERRORS The pthread_rwlock_tryrdlock() function will fail if: [EBUSY] The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it. The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions may fail if: [EINVAL] The value specified by rwlock does not refer to an initialised read-write lock object. [EDEADLK] The current thread already owns the read-write lock for writing. [EAGAIN] The read lock could not be acquired because the maximum number of read locks for rwlock has been exceeded. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. Realtime applications may encounter priority inversion when using read- write locks. The problem occurs when a high priority thread "locks" a read-write lock that is about to be "un- locked" 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 pro- grammers must take into account the possibility of this kind of prior- ity 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 execut- ing in its critical section. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock(). ______________________________________________________________________ NAME pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock a read-write lock object for reading SYNOPSIS #include <pthread.h> int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); DESCRIPTION The pthread_rwlock_rdlock() function applies a read lock to the read- write lock referenced by rwlock. 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 ac- quires 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 ac- quired, the calling thread blocks (that is, it does not return from the pthread_rwlock_rdlock() call) until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made. Implementations are allowed to favour writers over readers to avoid writer starvation. A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the pthread_rwlock_rdlock() function n times). If so, the thread must perform matching unlocks (that is, it must call the pthread_rwlock_unlock() function n times). The function pthread_rwlock_tryrdlock() applies a read lock as in the pthread_rwlock_rdlock() function with the exception that the function fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock. Results are undefined if any of these functions are called with an uninitialised read-write lock. If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the signal handler the thread resumes waiting for the read-write lock for reading as if it was not interrupted. RETURN VALUE If successful, the pthread_rwlock_rdlock() function returns zero. Oth- erwise, an error number is returned to indicate the error. The function pthread_rwlock_tryrdlock() returns zero if the lock for reading on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error. ERRORS The pthread_rwlock_tryrdlock() function will fail if: [EBUSY] The read-write lock could not be acquired for reading because a writer holds the lock or was blocked on it. The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions may fail if: [EINVAL] The value specified by rwlock does not refer to an initialised read-write lock object. [EDEADLK] The current thread already owns the read-write lock for writing. [EAGAIN] The read lock could not be acquired because the maximum number of read locks for rwlock has been exceeded. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. Realtime applications may encounter priority inversion when using read- write locks. The problem occurs when a high priority thread "locks" a read-write lock that is about to be "un- locked" 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 pro- grammers must take into account the possibility of this kind of prior- ity 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 execut- ing in its critical section. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_unlock(). ______________________________________________________________________ NAME pthread_rwlock_wrlock, pthread_rwlock_trywrlock - lock a read-write lock object for writing SYNOPSIS #include <pthread.h> int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); DESCRIPTION The pthread_rwlock_wrlock() function applies a write lock to the read- write lock referenced by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread blocks (that is, does not return from the pthread_rwlock_wrlock() call) until it can acquire the lock. Re- sults are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made. Implementations are allowed to favour writers over readers to avoid writer starvation. The function pthread_rwlock_trywrlock() applies a write lock like the pthread_rwlock_wrlock() function, with the exception that the function fails if any thread currently holds rwlock (for reading or writing). Results are undefined if any of these functions are called with an uninitialised read-write lock. If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the signal handler the thread resumes waiting for the read-write lock for writing as if it was not interrupted. RETURN VALUE If successful, the pthread_rwlock_wrlock() function returns zero. Oth- erwise, an error number is returned to indicate the error. The function pthread_rwlock_trywrlock() returns zero if the lock for writing on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error. ERRORS The pthread_rwlock_trywrlock() function will fail if: [EBUSY] The read-write lock could not be acquired for writing because it was already locked for reading or writing. The pthread_rwlock_wrlock() and pthread_rwlock_trywrlock() functions may fail if: [EINVAL] The value specified by rwlock does not refer to an initialised read-write lock object. [EDEADLK] The current thread already owns the read-write lock for writing or reading. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. Realtime applications may encounter priority inversion when using read- write locks. The problem occurs when a high priority thread "locks" a read-write lock that is about to be "un- locked" 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 pro- grammers must take into account the possibility of this kind of prior- ity 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 execut- ing in its critical section. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock(). ______________________________________________________________________ NAME pthread_rwlock_unlock - unlock a read-write lock object SYNOPSIS #include <pthread.h> int pthread_rwlock_unlock(pthread_rwlock_t *rwlock); DESCRIPTION The pthread_rwlock_unlock() function is called to release a lock held on the read-write lock object referenced by rwlock. Results are unde- fined if the read-write lock rwlock is not held by the calling thread. If this function is called to release a read lock from the read-write lock object and there are other read locks currently held on this read- write lock object, the read-write lock object remains in the read locked state. If this function releases the calling thread's last read lock on this read-write lock object, then the calling thread is no longer one of the owners of the object. If this function releases the last read lock for this read-write lock object, the read-write lock ob- ject will be put in the unlocked state with no owners. If this function is called to release a write lock for this read-write lock object, the read-write lock object will be put in the unlocked state with no owners. If the call to the pthread_rwlock_unlock() 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 schedul- ing policy is used to determine which thread acquires the read-write lock object for writing. If there are multiple threads waiting to ac- quire 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 rwlock for both read locks and write locks, it is unspeci- fied whether the readers acquire the lock first or whether a writer ac- quires the lock first. Results are undefined if any of these functions are called with an uninitialised read-write lock. RETURN VALUE If successful, the pthread_rwlock_unlock() function returns zero. Oth- erwise, an error number is returned to indicate the error. ERRORS The pthread_rwlock_unlock() function may fail if: [EINVAL] The value specified by rwlock does not refer to an initialised read-write lock object. [EPERM] The current thread does not own the read-write lock. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_wrlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock(). ______________________________________________________________________ NAME pthread_rwlock_wrlock, pthread_rwlock_trywrlock - lock a read-write lock object for writing SYNOPSIS #include <pthread.h> int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); DESCRIPTION The pthread_rwlock_wrlock() function applies a write lock to the read- write lock referenced by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread blocks (that is, does not return from the pthread_rwlock_wrlock() call) until it can acquire the lock. Re- sults are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made. Implementations are allowed to favour writers over readers to avoid writer starvation. The function pthread_rwlock_trywrlock() applies a write lock like the pthread_rwlock_wrlock() function, with the exception that the function fails if any thread currently holds rwlock (for reading or writing). Results are undefined if any of these functions are called with an uninitialised read-write lock. If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the signal handler the thread resumes waiting for the read-write lock for writing as if it was not interrupted. RETURN VALUE If successful, the pthread_rwlock_wrlock() function returns zero. Oth- erwise, an error number is returned to indicate the error. The function pthread_rwlock_trywrlock() returns zero if the lock for writing on the read-write lock object referenced by rwlock is acquired. Otherwise an error number is returned to indicate the error. ERRORS The pthread_rwlock_trywrlock() function will fail if: [EBUSY] The read-write lock could not be acquired for writing because it was already locked for reading or writing. The pthread_rwlock_wrlock() and pthread_rwlock_trywrlock() functions may fail if: [EINVAL] The value specified by rwlock does not refer to an initialised read-write lock object. [EDEADLK] The current thread already owns the read-write lock for writing or reading. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. Realtime applications may encounter priority inversion when using read- write locks. The problem occurs when a high priority thread "locks" a read-write lock that is about to be "un- locked" 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 pro- grammers must take into account the possibility of this kind of prior- ity 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 execut- ing in its critical section. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlockattr_init(), pthread_rwlock_rdlock(). ______________________________________________________________________ NAME pthread_rwlockattr_init, pthread_rwlockattr_destroy - initialise and destroy read-write lock attributes object SYNOPSIS #include <pthread.h> int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); DESCRIPTION The function pthread_rwlockattr_init() initialises a read-write lock attributes object attr with the default value for all of the attributes defined by the implementation. Results are undefined if pthread_rwlockattr_init() is called specifying an already initialised read-write lock attributes object. After a read-write lock attributes object has been used to initialise one or more read-write locks, any function affecting the attributes ob- ject (including destruction) does not affect any previously initialised read-write locks. The pthread_rwlockattr_destroy() function destroys a read-write lock attributes object. The effect of subsequent use of the object is unde- fined until the object is re-initialised by another call to pthread_rwlockattr_init(). An implementation may cause pthread_rwlock- attr_destroy() to set the object referenced by attr to an invalid value. RETURN VALUE If successful, the pthread_rwlockattr_init() and pthread_rwlockattr_de- stroy() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_rwlockattr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the read-write lock at- tributes object. The pthread_rwlockattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlock- attr_getpshared(). ______________________________________________________________________ NAME pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared - get and set process-shared attribute of read-write lock attributes object SYNOPSIS #include <pthread.h> int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared); int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared); DESCRIPTION The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a read-write lock to be operated upon by any thread that has access to the memory where the read-write lock is allocated, even if the read- write lock is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the read- write lock will only be operated upon by threads created within the same process as the thread that initialised the read-write lock; if threads of differing processes attempt to operate on such a read-write lock, the behaviour is undefined. The default value of the process- shared attribute is PTHREAD_PROCESS_PRIVATE. The pthread_rwlockattr_getpshared() function obtains the value of the process-shared attribute from the initialised attributes object refer- enced by attr. The pthread_rwlockattr_setpshared() function is used to set the process-shared attribute in an initialised attributes object referenced by attr. RETURN VALUE If successful, the pthread_rwlockattr_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, the pthread_rwlockattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise an error num- ber is returned to indicate the error. ERRORS The pthread_rwlockattr_getpshared() and pthread_rwlockattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_rwlockattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlock- attr_init(). ______________________________________________________________________ NAME pthread_rwlockattr_init, pthread_rwlockattr_destroy - initialise and destroy read-write lock attributes object SYNOPSIS #include <pthread.h> int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); DESCRIPTION The function pthread_rwlockattr_init() initialises a read-write lock attributes object attr with the default value for all of the attributes defined by the implementation. Results are undefined if pthread_rwlockattr_init() is called specifying an already initialised read-write lock attributes object. After a read-write lock attributes object has been used to initialise one or more read-write locks, any function affecting the attributes ob- ject (including destruction) does not affect any previously initialised read-write locks. The pthread_rwlockattr_destroy() function destroys a read-write lock attributes object. The effect of subsequent use of the object is unde- fined until the object is re-initialised by another call to pthread_rwlockattr_init(). An implementation may cause pthread_rwlock- attr_destroy() to set the object referenced by attr to an invalid value. RETURN VALUE If successful, the pthread_rwlockattr_init() and pthread_rwlockattr_de- stroy() functions return zero. Otherwise, an error number is returned to indicate the error. ERRORS The pthread_rwlockattr_init() function will fail if: [ENOMEM] Insufficient memory exists to initialise the read-write lock at- tributes object. The pthread_rwlockattr_destroy() function may fail if: [EINVAL] The value specified by attr is invalid. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlock- attr_getpshared(). ______________________________________________________________________ NAME pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared - get and set process-shared attribute of read-write lock attributes object SYNOPSIS #include <pthread.h> int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared); int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared); DESCRIPTION The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a read-write lock to be operated upon by any thread that has access to the memory where the read-write lock is allocated, even if the read- write lock is allocated in memory that is shared by multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the read- write lock will only be operated upon by threads created within the same process as the thread that initialised the read-write lock; if threads of differing processes attempt to operate on such a read-write lock, the behaviour is undefined. The default value of the process- shared attribute is PTHREAD_PROCESS_PRIVATE. The pthread_rwlockattr_getpshared() function obtains the value of the process-shared attribute from the initialised attributes object refer- enced by attr. The pthread_rwlockattr_setpshared() function is used to set the process-shared attribute in an initialised attributes object referenced by attr. RETURN VALUE If successful, the pthread_rwlockattr_setpshared() function returns zero. Otherwise, an error number is returned to indicate the error. Upon successful completion, the pthread_rwlockattr_getpshared() returns zero and stores the value of the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise an error num- ber is returned to indicate the error. ERRORS The pthread_rwlockattr_getpshared() and pthread_rwlockattr_setpshared() functions may fail if: [EINVAL] The value specified by attr is invalid. The pthread_rwlockattr_setpshared() function may fail if: [EINVAL] The new value specified for the attribute is outside the range of legal values for that attribute. EXAMPLES None. APPLICATION USAGE Similar functions are being developed by IEEE PASC. In keeping with its objective of ensuring that CAE Specifications are fully aligned with formal standards, The Open Group intends to add any new interfaces adopted by an official IEEE standard in this area. FUTURE DIRECTIONS None. SEE ALSO <pthread.h>, pthread_rwlock_init(), pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock_rdlock(), pthread_rwlock- attr_init(). ______________________________________________________________________ NAME pthread_self - get calling thread's ID SYNOPSIS #include <pthread.h> pthread_t pthread_self(void); DESCRIPTION The pthread_self() function returns the thread ID of the calling thread. RETURN VALUE See DESCRIPTION above. ERRORS No errors are defined. The pthread_self() function will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_create(), pthread_equal(), <pthread.h>. ______________________________________________________________________ NAME pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel - set cancelability state SYNOPSIS #include <pthread.h> int pthread_setcancelstate(int state, int *oldstate); int pthread_set- canceltype(int type, int *oldtype); void pthread_testcancel(void); DESCRIPTION The pthread_setcancelstate() function atomically both sets the calling thread's cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the pre- vious cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYN- CHRONOUS. The cancelability state and type of any newly created threads, includ- ing the thread in which main() was first invoked, are PTHREAD_CAN- CEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively. The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled. RETURN VALUE If successful, the pthread_setcancelstate() and pthread_setcanceltype() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_setcancelstate() function may fail if: [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function may fail if: [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CAN- CEL_ASYNCHRONOUS. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cancel(), <pthread.h>. ______________________________________________________________________ NAME pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel - set cancelability state SYNOPSIS #include <pthread.h> int pthread_setcancelstate(int state, int *oldstate); int pthread_set- canceltype(int type, int *oldtype); void pthread_testcancel(void); DESCRIPTION The pthread_setcancelstate() function atomically both sets the calling thread's cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the pre- vious cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYN- CHRONOUS. The cancelability state and type of any newly created threads, includ- ing the thread in which main() was first invoked, are PTHREAD_CAN- CEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively. The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled. RETURN VALUE If successful, the pthread_setcancelstate() and pthread_setcanceltype() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_setcancelstate() function may fail if: [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function may fail if: [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CAN- CEL_ASYNCHRONOUS. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cancel(), <pthread.h>. ______________________________________________________________________ NAME pthread_setconcurrency - get or set level of concurrency SYNOPSIS #include <pthread.h> int pthread_setconcurrency(int new_level); DESCRIPTION Refer to pthread_getconcurrency(). ______________________________________________________________________ NAME pthread_getschedparam, pthread_setschedparam - dynamic thread schedul- ing parameters access (REALTIME THREADS) SYNOPSIS #include <pthread.h> int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param); int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param); DESCRIPTION The pthread_getschedparam() and pthread_setschedparam() allow the scheduling policy and scheduling parameters of individual threads within a multi-threaded process to be retrieved and set. For SCHED_FIFO and SCHED_RR, the only required member of the sched_param structure is the priority sched_priority. For SCHED_OTHER, the af- fected scheduling parameters are implementation-dependent. The pthread_getschedparam() function retrieves the scheduling policy and scheduling parameters for the thread whose thread ID is given by thread and stores those values in policy and param, respectively. The priority value returned from pthread_getschedparam() is the value spec- ified by the most recent pthread_setschedparam() or pthread_create() call affecting the target thread, and reflects any temporary adjust- ments to its priority as a result of any priority inheritance or ceil- ing functions. The pthread_setschedparam() function sets the schedul- ing policy and associated scheduling parameters for the thread whose thread ID is given by thread to the policy and associated parameters provided in policy and param, respectively. The policy parameter may have the value SCHED_OTHER, that has implemen- tation-dependent scheduling parameters, SCHED_FIFO or SCHED_RR, that have the single scheduling parameter, priority. If the pthread_setschedparam() function fails, no scheduling parameters will be changed for the target thread. RETURN VALUE If successful, the pthread_getschedparam() and pthread_setschedparam() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_getschedparam() and pthread_setschedparam() functions will fail if: [ENOSYS] The option _POSIX_THREAD_PRIORITY_SCHEDULING is not defined and the implementation does not support the function. The pthread_getschedparam() function may fail if: [ESRCH] The value specified by thread does not refer to a existing thread. The pthread_setschedparam() function may fail if: [EINVAL] The value specified by policy or one of the scheduling parameters associated with the scheduling policy policy is invalid. [ENOTSUP] An attempt was made to set the policy or scheduling parameters to an unsupported value. [EPERM] The caller does not have the appropriate permission to set either the scheduling parameters or the scheduling policy of the specified thread. [EPERM] The implementation does not allow the application to modify one of the parameters to the value specified. [ESRCH] The value specified by thread does not refer to a existing thread. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO sched_setparam(), sched_getparam(), sched_setscheduler(), sched_getscheduler(), <pthread.h>, <sched.h>. ______________________________________________________________________ NAME pthread_setspecific, pthread_getspecific - thread-specific data manage- ment SYNOPSIS #include <pthread.h> int pthread_setspecific(pthread_key_t key, const void *value); void *pthread_getspecific(pthread_key_t key); DESCRIPTION The pthread_setspecific() function associates a thread-specific value with a key obtained via a previous call to pthread_key_create(). Dif- ferent threads may bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread. The pthread_getspecific() function returns the value currently bound to the specified key on behalf of the calling thread. The effect of calling pthread_setspecific() or pthread_getspecific() with a key value not obtained from pthread_key_create() or after key has been deleted with pthread_key_delete() is undefined. Both pthread_setspecific() and pthread_getspecific() may be called from a thread-specific data destructor function. However, calling pthread_setspecific() from a destructor may result in lost storage or infinite loops. Both functions may be implemented as macros. RETURN VALUE The function pthread_getspecific() returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, then the value NULL is returned. If successful, the pthread_setspecific() function returns zero. Other- wise, an error number is returned to indicate the error. ERRORS The pthread_setspecific() function will fail if: [ENOMEM] Insufficient memory exists to associate the value with the key. The pthread_setspecific() function may fail if: [EINVAL] The key value is invalid. No errors are returned from pthread_getspecific(). These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_key_create(), <pthread.h>. ______________________________________________________________________ NAME pthread_sigmask - examine and change blocked signals SYNOPSIS #include <signal.h> int pthread_sigmask(int how, const sigset_t *set, sigset_t *oset); DESCRIPTION Refer to sigprocmask(). ______________________________________________________________________ NAME pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel - set cancelability state SYNOPSIS #include <pthread.h> int pthread_setcancelstate(int state, int *oldstate); int pthread_set- canceltype(int type, int *oldtype); void pthread_testcancel(void); DESCRIPTION The pthread_setcancelstate() function atomically both sets the calling thread's cancelability state to the indicated state and returns the previous cancelability state at the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function atomically both sets the calling thread's cancelability type to the indicated type and returns the pre- vious cancelability type at the location referenced by oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYN- CHRONOUS. The cancelability state and type of any newly created threads, includ- ing the thread in which main() was first invoked, are PTHREAD_CAN- CEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively. The pthread_testcancel() function creates a cancellation point in the calling thread. The pthread_testcancel() function has no effect if cancelability is disabled. RETURN VALUE If successful, the pthread_setcancelstate() and pthread_setcanceltype() functions return zero. Otherwise, an error number is returned to indi- cate the error. ERRORS The pthread_setcancelstate() function may fail if: [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CAN- CEL_DISABLE. The pthread_setcanceltype() function may fail if: [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CAN- CEL_ASYNCHRONOUS. These functions will not return an error code of [EINTR]. EXAMPLES None. APPLICATION USAGE None. FUTURE DIRECTIONS None. SEE ALSO pthread_cancel(), <pthread.h>. 08-Jun-2006 GNU Pth 2.0.7 pthread(3)
NAME | VERSION | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | ______________________________________________________________________ | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pthread&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>