pthread(3) POSIX Threading API of GNU Pth pthread(3)NAMEpthread - 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
intention 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
directly based on Pth (Pth for portability reasons is a pure non-
preemptive 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 application, of course. Nevertheless the responsiveness and
concurrency 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/include/unistd.h"). When this occurs try to ``"#define"''
header-dependent 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.open‐
group.org/onlinepubs/007908799/xsh/threads.html. This is a very com‐
plete publically available description of the Pthread API. For con‐
vinience 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 ALSOpthread-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
requirements for visibility of symbols in this header.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_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_mutexattr_gettype(), pthread_mutexattr_setprotocol(),
pthread_once(), pthread_self(), pthread_setcancelstate(), pthread_set‐
specific(), pthread_rwlock_init(), pthread_rwlock_rdlock(),
pthread_rwlock_unlock(), pthread_rwlock_wrlock(), pthread_rwlock‐
attr_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
before 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() processing completes in the child process. If no handling is
desired at one or more of these three points, the corresponding fork
handler address(es) may be set to NULL.
The order of calls to 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
addresses.
The pthread_atfork() function will not return an error code of [EINTR].
EXAMPLES
None.
APPLICATION USAGE
None.
FUTURE DIRECTIONS
None.
SEE ALSOatexit(), 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
attributes 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
attributes 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_destroy() 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
object.
These functions will not return an error code of [EINTR].
EXAMPLES
None.
APPLICATION USAGE
None.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_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
*detachstate);
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
attribute 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
detachstate 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 ALSOpthread_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
resources. An application that creates a large number of threads,
and which knows its threads will never overflow their stack, can
save system resources by turning off guard areas.
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
returned 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
attributes 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
defined 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 ALSOpthread_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
required 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 ALSOpthread_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
error 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 ALSOpthread_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 ALSOpthread_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
attribute 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 ALSOpthread_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
attribute 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 ALSOpthread_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_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
attributes 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
attributes object. An implementation may cause pthread_attr_destroy()
to set attr to an implementation-dependent invalid value. The behav‐
iour of using the attribute after it has been destroyed is undefined.
RETURN VALUE
Upon successful completion, pthread_attr_init() and
pthread_attr_destroy() 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
object.
These functions will not return an error code of [EINTR].
EXAMPLES
None.
APPLICATION USAGE
None.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_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
*detachstate);
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
attribute 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
detachstate 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 ALSOpthread_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
resources. An application that creates a large number of threads,
and which knows its threads will never overflow their stack, can
save system resources by turning off guard areas.
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
returned 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
attributes 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
defined 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 ALSOpthread_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
required 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 ALSOpthread_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
error 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 ALSOpthread_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 ALSOpthread_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
attribute 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 ALSOpthread_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
attribute 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 ALSOpthread_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
returns, 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 ALSOpthread_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
token 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 ALSOpthread_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
token 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 ALSOpthread_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 ALSOpthread_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
attributes object. Upon successful initialisation, the state of the
condition variable becomes initialised.
Attempting to initialise an already initialised condition variable
results in undefined behaviour.
The function 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
object referenced by cond, a previously initialised, but not yet
destroyed, 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
another 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 ALSOpthread_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
attributes object. Upon successful initialisation, the state of the
condition variable becomes initialised.
Attempting to initialise an already initialised condition variable
results in undefined behaviour.
The function 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
object referenced by cond, a previously initialised, but not yet
destroyed, 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
another 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 ALSOpthread_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 ALSOpthread_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
*mutex, 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
involving 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_CAN‐
CEL_DEFERRED, a side effect of acting upon a cancellation request while
in a condition wait is that the mutex is (in effect) re-acquired before
calling the first cancellation cleanup handler. The effect is as if
the thread were unblocked, allowed to execute up to the point of
returning from the call to 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
exceeds 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 ALSOpthread_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
*mutex, 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
involving 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_CAN‐
CEL_DEFERRED, a side effect of acting upon a cancellation request while
in a condition wait is that the mutex is (in effect) re-acquired before
calling the first cancellation cleanup handler. The effect is as if
the thread were unblocked, allowed to execute up to the point of
returning from the call to 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
exceeds 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 ALSOpthread_cond_signal(), pthread_cond_broadcast(), <pthread.h>.
______________________________________________________________________NAME
pthread_condattr_init, pthread_condattr_destroy - initialise and
destroy 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
attributes 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
attributes object (including destruction) does not affect any previ‐
ously 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
destroyed 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_con‐
dattr_destroy() 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
attributes 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 ALSOpthread_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 ALSOpthread_condattr_init(), pthread_create(), pthread_mutex_init(),
pthread_cond_init(), <pthread.h>.
______________________________________________________________________NAME
pthread_condattr_init, pthread_condattr_destroy - initialise and
destroy 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
attributes 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
attributes object (including destruction) does not affect any previ‐
ously 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
destroyed 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_con‐
dattr_destroy() 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
attributes 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 ALSOpthread_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 ALSOpthread_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
attributes specified by attr, within a process. If attr is NULL, the
default 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
argument. If the start_routine returns, the effect is as if there was
an implicit call to pthread_exit() using the return value of start_rou‐
tine as the exit status. Note that the thread in which main() was
originally invoked differs from this. When it returns from main(), the
effect 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 ALSOpthread_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 ALSOpthread_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 ALSOpthread_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
destructor functions will be called in an unspecified order. Thread
termination does not release any application visible process resources,
including, but not limited to, mutexes and file descriptors, nor does
it perform any process level cleanup actions, including, but not 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
result 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 ALSOpthread_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
result 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
affected 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 ALSOsched_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 ALSOpthread_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
already 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 ALSOpthread_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
argument. The order of destructor calls is unspecified if more than
one destructor exists for a thread when it exits.
If, after all the destructors have been called for all non-NULL values
with associated destructors, there are still some non-NULL values with
associated destructors, then the process will be repeated. If, after
at least PTHREAD_DESTRUCTOR_ITERATIONS iterations of destructor calls
for outstanding non-NULL values, there are still some non-NULL values
with associated destructors, implementations may stop calling 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 ALSOpthread_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 ALSOpthread_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 ALSOkill(), pthread_self(), raise(), <signal.h>.
______________________________________________________________________NAME
pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a
mutex
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
address of a default mutex attributes object. Upon successful initial‐
isation, 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
object referenced by mutex, a previously initialised, but not yet
destroyed, 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 ALSOpthread_mutex_getprioceiling(), pthread_mutex_lock(),
pthread_mutex_unlock(), pthread_mutex_setprioceiling(),
pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutex‐
attr_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_mutex_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 ALSOpthread_mutex_init(), pthread_mutex_lock(), pthread_mutex_unlock(),
pthread_mutex_trylock(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutex_init, pthread_mutex_destroy - initialise or destroy a
mutex
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
address of a default mutex attributes object. Upon successful initial‐
isation, 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
object referenced by mutex, a previously initialised, but not yet
destroyed, 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 ALSOpthread_mutex_getprioceiling(), pthread_mutex_lock(),
pthread_mutex_unlock(), pthread_mutex_setprioceiling(),
pthread_mutex_trylock(), pthread_mutexattr_getpshared(), pthread_mutex‐
attr_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_mutex_lock(). If the mutex is already locked, the calling
thread blocks until the mutex becomes available. This operation
returns with the mutex 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
mutex that it has not locked or a mutex which is unlocked, an error
will be returned.
If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
the concept of a lock count. When a thread successfully acquires a
mutex for the first time, the lock count is set to one. Every time a
thread relocks this mutex, the lock count is incremented by one. Each
time the thread unlocks the mutex, the lock count is decremented by
one. When the lock count reaches zero, the mutex becomes available for
other threads to acquire. If a thread attempts to unlock a mutex that
it has not locked or a mutex which is unlocked, an error will be
returned.
If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
lock the mutex results in undefined behaviour. Attempting to unlock the
mutex if it was not locked by the calling thread results in undefined
behaviour. Attempting to unlock the mutex if it is not locked results
in undefined behaviour.
The function pthread_mutex_trylock() is identical to
pthread_mutex_lock() except that if the mutex object referenced by
mutex is currently 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
mutex object referenced by mutex is acquired. Otherwise, an error num‐
ber 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_unlock() 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
recursive 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 ALSOpthread_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_mutex_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 ALSOpthread_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_mutex_lock(). If the mutex is already locked, the calling
thread blocks until the mutex becomes available. This operation
returns with the mutex 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
mutex that it has not locked or a mutex which is unlocked, an error
will be returned.
If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
the concept of a lock count. When a thread successfully acquires a
mutex for the first time, the lock count is set to one. Every time a
thread relocks this mutex, the lock count is incremented by one. Each
time the thread unlocks the mutex, the lock count is decremented by
one. When the lock count reaches zero, the mutex becomes available for
other threads to acquire. If a thread attempts to unlock a mutex that
it has not locked or a mutex which is unlocked, an error will be
returned.
If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
lock the mutex results in undefined behaviour. Attempting to unlock the
mutex if it was not locked by the calling thread results in undefined
behaviour. Attempting to unlock the mutex if it is not locked results
in undefined behaviour.
The function pthread_mutex_trylock() is identical to
pthread_mutex_lock() except that if the mutex object referenced by
mutex is currently 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
mutex object referenced by mutex is acquired. Otherwise, an error num‐
ber 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_unlock() 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
recursive 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 ALSOpthread_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_mutex_lock(). If the mutex is already locked, the calling
thread blocks until the mutex becomes available. This operation
returns with the mutex 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
mutex that it has not locked or a mutex which is unlocked, an error
will be returned.
If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains
the concept of a lock count. When a thread successfully acquires a
mutex for the first time, the lock count is set to one. Every time a
thread relocks this mutex, the lock count is incremented by one. Each
time the thread unlocks the mutex, the lock count is decremented by
one. When the lock count reaches zero, the mutex becomes available for
other threads to acquire. If a thread attempts to unlock a mutex that
it has not locked or a mutex which is unlocked, an error will be
returned.
If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively
lock the mutex results in undefined behaviour. Attempting to unlock the
mutex if it was not locked by the calling thread results in undefined
behaviour. Attempting to unlock the mutex if it is not locked results
in undefined behaviour.
The function pthread_mutex_trylock() is identical to
pthread_mutex_lock() except that if the mutex object referenced by
mutex is currently 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
mutex object referenced by mutex is acquired. Otherwise, an error num‐
ber 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_unlock() 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
recursive 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 ALSOpthread_mutex_init(), pthread_mutex_destroy(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutexattr_init, pthread_mutexattr_destroy - initialise and
destroy mutex attributes object
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_init(pthread_mutexattr_t *attr); int
pthread_mutexattr_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
object is undefined.
After a mutex attributes object has been used to initialise one or more
mutexes, any function affecting the attributes object (including
destruction) does not affect any previously initialised mutexes.
The 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
object.
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 ALSOpthread_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
attribute of a mutex attribute object pointed to by attr which was pre‐
viously 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
inversion, the priority ceiling of the mutex will be set to a priority
higher than or equal to the highest priority of all the threads that
may lock that mutex. The values of 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 ALSOpthread_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
attribute, its priority and scheduling are not affected by its mutex
ownership.
When a thread is blocking higher priority threads because of owning one
or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it
executes at the higher of its priority or the priority of the highest
priority thread waiting on any of the mutexes owned by this thread and
initialised with this protocol.
When a thread owns one or more mutexes initialised with the
PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its 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
attributes, it will not be subject to being moved to the tail of the
scheduling queue at its priority in the event that its original prior‐
ity 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
inheritance 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 ALSOpthread_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
attribute 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 ALSOpthread_create(), pthread_mutex_init(), pthread_mutexattr_init(),
pthread_cond_init(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutexattr_gettype, pthread_mutexattr_settype - get or set a
mutex 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
attribute 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
attributes. 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.
Attempting to unlock a mutex locked by a different thread results
in undefined behaviour. Attempting to unlock an unlocked mutex
results 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
unlock 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
another thread has locked will return with an error. A thread
attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_DEFAULT
Attempting to recursively lock a mutex of this type results in
undefined behaviour. Attempting to unlock a mutex of this type
which was not locked by the calling thread results in undefined be‐
haviour. 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
returned 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 ALSOpthread_cond_wait(), pthread_cond_timedwait(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutexattr_init, pthread_mutexattr_destroy - initialise and
destroy mutex attributes object
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_init(pthread_mutexattr_t *attr); int
pthread_mutexattr_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
object is undefined.
After a mutex attributes object has been used to initialise one or more
mutexes, any function affecting the attributes object (including
destruction) does not affect any previously initialised mutexes.
The 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
object.
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 ALSOpthread_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
attribute of a mutex attribute object pointed to by attr which was pre‐
viously 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
inversion, the priority ceiling of the mutex will be set to a priority
higher than or equal to the highest priority of all the threads that
may lock that mutex. The values of 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 ALSOpthread_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
attribute, its priority and scheduling are not affected by its mutex
ownership.
When a thread is blocking higher priority threads because of owning one
or more mutexes with the PTHREAD_PRIO_INHERIT protocol attribute, it
executes at the higher of its priority or the priority of the highest
priority thread waiting on any of the mutexes owned by this thread and
initialised with this protocol.
When a thread owns one or more mutexes initialised with the
PTHREAD_PRIO_PROTECT protocol, it executes at the higher of its 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
attributes, it will not be subject to being moved to the tail of the
scheduling queue at its priority in the event that its original prior‐
ity 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
inheritance 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 ALSOpthread_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
attribute 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 ALSOpthread_create(), pthread_mutex_init(), pthread_mutexattr_init(),
pthread_cond_init(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutexattr_gettype, pthread_mutexattr_settype - get or set a
mutex 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
attribute 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
attributes. 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.
Attempting to unlock a mutex locked by a different thread results
in undefined behaviour. Attempting to unlock an unlocked mutex
results 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
unlock 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
another thread has locked will return with an error. A thread
attempting to unlock an unlocked mutex will return with an error.
PTHREAD_MUTEX_DEFAULT
Attempting to recursively lock a mutex of this type results in
undefined behaviour. Attempting to unlock a mutex of this type
which was not locked by the calling thread results in undefined be‐
haviour. 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
returned 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 ALSOpthread_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
object 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
implementation 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.
Attempting 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
dynamic initialisation by a call to pthread_rwlock_init() with the
parameter 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
object referenced by rwlock, a previously initialised but not yet
destroyed 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
object 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
implementation 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.
Attempting 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
dynamic initialisation by a call to pthread_rwlock_init() with the
parameter 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
object referenced by rwlock, a previously initialised but not yet
destroyed 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
acquires the lock when a writer does not hold the lock and there are
writers waiting for the lock. If a writer holds the lock, the calling
thread will not acquire the read lock. If the read lock is not
acquired, the calling thread blocks (that is, it does not return from
the 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
"unlocked" by a low priority thread, but the low priority
thread is preempted by a medium priority thread. This scenario leads
to priority inversion; a high priority thread is blocked by lower pri‐
ority threads for an unlimited period of time. During system design,
realtime programmers must take into account the possibility of this
kind of priority inversion. They can deal with it in a number of ways,
such as by having critical sections that are guarded by read-write
locks execute at a high priority, so that a thread cannot be preempted
while executing in its critical section.
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
acquires the lock when a writer does not hold the lock and there are
writers waiting for the lock. If a writer holds the lock, the calling
thread will not acquire the read lock. If the read lock is not
acquired, the calling thread blocks (that is, it does not return from
the 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
"unlocked" by a low priority thread, but the low priority
thread is preempted by a medium priority thread. This scenario leads
to priority inversion; a high priority thread is blocked by lower pri‐
ority threads for an unlimited period of time. During system design,
realtime programmers must take into account the possibility of this
kind of priority inversion. They can deal with it in a number of ways,
such as by having critical sections that are guarded by read-write
locks execute at a high priority, so that a thread cannot be preempted
while executing in its critical section.
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.
Results are undefined if the calling thread holds the read-write lock
(whether a read or write lock) at the time the call is made.
Implementations are allowed to favour writers over readers to avoid
writer starvation.
The function 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
"unlocked" by a low priority thread, but the low priority
thread is preempted by a medium priority thread. This scenario leads
to priority inversion; a high priority thread is blocked by lower pri‐
ority threads for an unlimited period of time. During system design,
realtime programmers must take into account the possibility of this
kind of priority inversion. They can deal with it in a number of ways,
such as by having critical sections that are guarded by read-write
locks execute at a high priority, so that a thread cannot be preempted
while executing in its critical section.
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
object will be put in the unlocked state with no owners.
If this function is called to release a write lock for this read-write
lock object, the read-write lock object will be put in the unlocked
state with no owners.
If the call to the 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
acquire the read-write lock object for reading, the scheduling policy
is used to determine the order in which the waiting threads acquire the
read-write lock object for reading. If there are multiple threads
blocked on rwlock for both read locks and write locks, it is unspeci‐
fied whether the readers acquire the lock first or whether a writer
acquires the lock first.
Results are undefined if any of these functions are called with an
uninitialised read-write lock.
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.
Results are undefined if the calling thread holds the read-write lock
(whether a read or write lock) at the time the call is made.
Implementations are allowed to favour writers over readers to avoid
writer starvation.
The function 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
"unlocked" by a low priority thread, but the low priority
thread is preempted by a medium priority thread. This scenario leads
to priority inversion; a high priority thread is blocked by lower pri‐
ority threads for an unlimited period of time. During system design,
realtime programmers must take into account the possibility of this
kind of priority inversion. They can deal with it in a number of ways,
such as by having critical sections that are guarded by read-write
locks execute at a high priority, so that a thread cannot be preempted
while executing in its critical section.
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
object (including destruction) does not affect any previously ini‐
tialised 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_rwlock‐
attr_destroy() 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
attributes 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
object (including destruction) does not affect any previously ini‐
tialised 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_rwlock‐
attr_destroy() 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
attributes 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 ALSOpthread_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 ALSOpthread_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 ALSOpthread_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
affected 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 ALSOsched_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 ALSOpthread_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 ALSOpthread_cancel(), <pthread.h>.
08-Jun-2006 GNU Pth 2.0.7 pthread(3)
