pthread(3) POSIX Threading API of GNU Pth pthread(3)NAMEpthread - POSIX.1c Threading API of GNU Pth
VERSION
GNU Pth 1.3.7 (29-Jul-2000)
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
applications. 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
GNU Pth 1.3.7 29-Jul-2000 1
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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.opengroup.org/onlinepubs/007908799/xsh/threads.html.
This is a very complete publically available description
of the Pthread API. For convinience reasons, a translated
copy of these freely available HTML pages are appended to
this manpage below. These are 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, standard.
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
GNU Pth 1.3.7 29-Jul-2000 2
pthread(3) POSIX Threading API of GNU Pth pthread(3)
## ## The Single UNIX Specification, Version 2 - Threads
##
http://www.opengroup.org/onlinepubs/007908799/xsh/threads.html
## Copyright (C) 1997 The Open Group, All Rights
Reserved. ##
______________________________________________________________________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 compiler.
GNU Pth 1.3.7 29-Jul-2000 3
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 *);
GNU Pth 1.3.7 29-Jul-2000 4
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_setspecific(), pthread_rwlock_init(),
pthread_rwlock_rdlock(), pthread_rwlock_unlock(),
pthread_rwlock_wrlock(), pthread_rwlockattr_init(),
<sched.h>, <time.h>.
GNU Pth 1.3.7 29-Jul-2000 5
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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 established 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.
GNU Pth 1.3.7 29-Jul-2000 6
pthread(3) POSIX Threading API of GNU Pth pthread(3)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.
GNU Pth 1.3.7 29-Jul-2000 7
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
GNU Pth 1.3.7 29-Jul-2000 8
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_setstacksize(), 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
GNU Pth 1.3.7 29-Jul-2000 9
pthread(3) POSIX Threading API of GNU Pth pthread(3)
guardsize attribute in the attr object. This attribute is
returned in the guardsize parameter.
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 contained 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_getguardsize() specifying attr will store in
the guardsize parameter the guard size specified by the
previous pthread_attr_setguardsize() function 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 allocating 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_setguardsize() functions return zero.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_attr_getguardsize() and
pthread_attr_setguardsize() functions 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.
GNU Pth 1.3.7 29-Jul-2000 10
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
inheritsched); int pthread_attr_getinheritsched(const
pthread_attr_t *attr, int *inheritsched);
DESCRIPTION
The functions pthread_attr_setinheritsched() and
pthread_attr_getinheritsched(), respectively, set and get
the inheritsched attribute in the attr argument.
When the attribute objects are used by pthread_create(),
the inheritsched 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_getinheritsched() 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:
GNU Pth 1.3.7 29-Jul-2000 11
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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_setschedpolicy(),
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_getschedparam(), 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.
GNU Pth 1.3.7 29-Jul-2000 12
pthread(3) POSIX Threading API of GNU Pth pthread(3)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() functions 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_setinheritsched(),
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_getschedpolicy(), respectively, set and get
the schedpolicy attribute in the attr argument.
GNU Pth 1.3.7 29-Jul-2000 13
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_setinheritsched(),
pthread_attr_setschedparam(), pthread_create(),
<pthread.h>, pthread_setschedparam(), <sched.h>.
______________________________________________________________________NAME
pthread_attr_setscope, pthread_attr_getscope - set and get
contentionscope attribute (REALTIME THREADS)
GNU Pth 1.3.7 29-Jul-2000 14
pthread(3) POSIX Threading API of GNU Pth pthread(3)SYNOPSIS
#include <pthread.h>
int pthread_attr_setscope(pthread_attr_t *attr, int
contentionscope); int pthread_attr_getscope(const
pthread_attr_t *attr, int *contentionscope);
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 indicate 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.
GNU Pth 1.3.7 29-Jul-2000 15
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 **stackaddr);
DESCRIPTION
The functions pthread_attr_setstackaddr() and
pthread_attr_getstackaddr(), 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(),
GNU Pth 1.3.7 29-Jul-2000 16
pthread(3) POSIX Threading API of GNU Pth pthread(3)pthread_attr_setstacksize(), 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_getstacksize(), respectively, set and get the
thread creation stacksize attribute in the attr object.
The stacksize attribute defines the minimum stack size (in
bytes) allocated 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_getstacksize() 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_setdetachstate(), pthread_create(),
<limits.h>, <pthread.h>.
GNU Pth 1.3.7 29-Jul-2000 17
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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(),
GNU Pth 1.3.7 29-Jul-2000 18
pthread(3) POSIX Threading API of GNU Pth pthread(3)
<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.
GNU Pth 1.3.7 29-Jul-2000 19
pthread(3) POSIX Threading API of GNU Pth pthread(3)APPLICATION USAGE
None.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_attr_init(), pthread_attr_setstackaddr(),
pthread_attr_setstacksize(), 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 parameter.
The pthread_attr_setguardsize() function sets the
guardsize attribute in the attr object. The new value of
GNU Pth 1.3.7 29-Jul-2000 20
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 contained 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_getguardsize() specifying attr will store in
the guardsize parameter the guard size specified by the
previous pthread_attr_setguardsize() function 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 allocating 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_setguardsize() functions return zero.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_attr_getguardsize() and
pthread_attr_setguardsize() functions 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.
GNU Pth 1.3.7 29-Jul-2000 21
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
inheritsched); int pthread_attr_getinheritsched(const
pthread_attr_t *attr, int *inheritsched);
DESCRIPTION
The functions pthread_attr_setinheritsched() and
pthread_attr_getinheritsched(), respectively, set and get
the inheritsched attribute in the attr argument.
When the attribute objects are used by pthread_create(),
the inheritsched 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_getinheritsched() 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.
GNU Pth 1.3.7 29-Jul-2000 22
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_setschedpolicy(),
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_getschedparam(), 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.
GNU Pth 1.3.7 29-Jul-2000 23
pthread(3) POSIX Threading API of GNU Pth pthread(3)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() functions 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_setinheritsched(),
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_getschedpolicy(), 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
GNU Pth 1.3.7 29-Jul-2000 24
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_setinheritsched(),
pthread_attr_setschedparam(), pthread_create(),
<pthread.h>, pthread_setschedparam(), <sched.h>.
______________________________________________________________________NAME
pthread_attr_setscope, pthread_attr_getscope - set and get
contentionscope attribute (REALTIME THREADS)
SYNOPSIS
#include <pthread.h>
int pthread_attr_setscope(pthread_attr_t *attr, int
contentionscope); int pthread_attr_getscope(const
GNU Pth 1.3.7 29-Jul-2000 25
pthread(3) POSIX Threading API of GNU Pth pthread(3)
pthread_attr_t *attr, int *contentionscope);
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 indicate 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>.
GNU Pth 1.3.7 29-Jul-2000 26
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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 **stackaddr);
DESCRIPTION
The functions pthread_attr_setstackaddr() and
pthread_attr_getstackaddr(), 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_setstacksize(), pthread_create(), <limits.h>,
<pthread.h>.
______________________________________________________________________NAME
pthread_attr_setstacksize, pthread_attr_getstacksize - set
and get stacksize attribute
GNU Pth 1.3.7 29-Jul-2000 27
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_getstacksize(), respectively, set and get the
thread creation stacksize attribute in the attr object.
The stacksize attribute defines the minimum stack size (in
bytes) allocated 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_getstacksize() 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_setdetachstate(), pthread_create(),
<limits.h>, <pthread.h>.
______________________________________________________________________NAME
pthread_cancel - cancel execution of a thread
SYNOPSIS
#include <pthread.h>
int pthread_cancel(pthread_t thread);
GNU Pth 1.3.7 29-Jul-2000 28
pthread(3) POSIX Threading API of GNU Pth pthread(3)DESCRIPTION
The pthread_cancel() function requests that thread be
canceled. The target threads cancelability state and type
determines when the cancellation takes effect. When the
cancellation is acted on, the cancellation cleanup
handlers for thread are called. When the last
cancellation cleanup handler returns, the thread-specific
data destructor functions 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 handlers
SYNOPSIS
#include <pthread.h>
void pthread_cleanup_push(void (*routine)(void*), void
*arg); void pthread_cleanup_pop(int execute);
GNU Pth 1.3.7 29-Jul-2000 29
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 cancellation 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 statements 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>.
______________________________________________________________________GNU Pth 1.3.7 29-Jul-2000 30
pthread(3) POSIX Threading API of GNU Pth pthread(3)NAME
pthread_cleanup_push, pthread_cleanup_pop - establish
cancellation handlers
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 cancellation 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 statements 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.
GNU Pth 1.3.7 29-Jul-2000 31
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_broadcast(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 scheduling 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_broadcast().
The pthread_cond_signal() and pthread_cond_broadcast()GNU Pth 1.3.7 29-Jul-2000 32
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 indicate 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 condition 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.
GNU Pth 1.3.7 29-Jul-2000 33
pthread(3) POSIX Threading API of GNU Pth pthread(3)
Attempting to initialise an already initialised condition
variable results in undefined behaviour.
The function pthread_cond_destroy() destroys the given
condition variable 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 undefined.
It is safe to destroy an initialised condition variable
upon which no threads are currently blocked. Attempting
to destroy a condition variable upon which other threads
are currently blocked results in undefined behaviour.
In cases where default condition variable attributes are
appropriate, the macro PTHREAD_COND_INITIALIZER can be
used to initialise condition variables that are statically
allocated. The effect is equivalent to dynamic
initialisation by a call to 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() functions return zero. Otherwise,
an error number is returned to indicate the error. The
[EBUSY] and [EINVAL] error checks, if implemented, act as
if they were performed immediately at the beginning of
processing for the function and caused an error return
prior to modifying the state of the condition variable
specified by 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.
GNU Pth 1.3.7 29-Jul-2000 34
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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 condition 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
GNU Pth 1.3.7 29-Jul-2000 35
pthread(3) POSIX Threading API of GNU Pth pthread(3)
variable results in undefined behaviour.
The function pthread_cond_destroy() destroys the given
condition variable 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 undefined.
It is safe to destroy an initialised condition variable
upon which no threads are currently blocked. Attempting
to destroy a condition variable upon which other threads
are currently blocked results in undefined behaviour.
In cases where default condition variable attributes are
appropriate, the macro PTHREAD_COND_INITIALIZER can be
used to initialise condition variables that are statically
allocated. The effect is equivalent to dynamic
initialisation by a call to 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() functions return zero. Otherwise,
an error number is returned to indicate the error. The
[EBUSY] and [EINVAL] error checks, if implemented, act as
if they were performed immediately at the beginning of
processing for the function and caused an error return
prior to modifying the state of the condition variable
specified by 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.
GNU Pth 1.3.7 29-Jul-2000 36
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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_broadcast(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.
GNU Pth 1.3.7 29-Jul-2000 37
pthread(3) POSIX Threading API of GNU Pth pthread(3)
If more than one thread is blocked on a condition
variable, the scheduling policy determines the order in
which threads are unblocked. When each thread unblocked
as a result of a 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_broadcast().
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 indicate 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>.
GNU Pth 1.3.7 29-Jul-2000 38
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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 predicate should be re-
evaluated upon such return.
The effect of using more than one mutex for concurrent
pthread_cond_wait() or pthread_cond_timedwait() operations
on the same condition variable is undefined; that is, a
condition variable becomes bound to a unique mutex when a
thread waits on the condition variable, and this (dynamic)
binding ends when the wait returns.
A condition wait (whether timed or not) is a cancellation
point. When the cancelability enable state of a thread is
set to PTHREAD_CANCEL_DEFERRED, a side effect of acting
upon a cancellation request while in a condition wait is
GNU Pth 1.3.7 29-Jul-2000 39
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_timedwait(), 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_timedwait() 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 specified 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()GNU Pth 1.3.7 29-Jul-2000 40
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 variable.
[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
GNU Pth 1.3.7 29-Jul-2000 41
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 predicate should be re-
evaluated upon such return.
The effect of using more than one mutex for concurrent
pthread_cond_wait() or pthread_cond_timedwait() operations
on the same condition variable is undefined; that is, a
condition variable becomes bound to a unique mutex when a
thread waits on the condition variable, and this (dynamic)
binding ends when the wait returns.
A condition wait (whether timed or not) is a cancellation
point. When the cancelability enable state of a thread is
set to PTHREAD_CANCEL_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_timedwait(), 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,
GNU Pth 1.3.7 29-Jul-2000 42
pthread(3) POSIX Threading API of GNU Pth pthread(3)pthread_cond_timedwait() 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 specified 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 variable.
[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.
GNU Pth 1.3.7 29-Jul-2000 43
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_condattr_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 initialise one or more condition variables, any
function affecting the attributes object (including
destruction) does not affect any previously initialised
condition variables.
The pthread_condattr_destroy() function destroys a
condition variable attributes object; the object becomes,
in effect, uninitialised. An implementation may cause
pthread_condattr_destroy() to set the object referenced by
attr to an invalid value. A destroyed condition variable
attributes object can be re-initialised using
pthread_condattr_init(); the results of otherwise
referencing the object after it has been destroyed are
undefined.
Additional attributes, their default values, and the names
of the associated functions to get and set those attribute
values are implementation-dependent.
RETURN VALUE
If successful, the pthread_condattr_init() and
pthread_condattr_destroy() functions return zero.
Otherwise, an error number is returned to indicate the
error.
GNU Pth 1.3.7 29-Jul-2000 44
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
GNU Pth 1.3.7 29-Jul-2000 45
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 associated functions to get and set those attribute
values are implementation-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>.
______________________________________________________________________GNU Pth 1.3.7 29-Jul-2000 46
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_condattr_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 initialise one or more condition variables, any
function affecting the attributes object (including
destruction) does not affect any previously initialised
condition variables.
The pthread_condattr_destroy() function destroys a
condition variable attributes object; the object becomes,
in effect, uninitialised. An implementation may cause
pthread_condattr_destroy() to set the object referenced by
attr to an invalid value. A destroyed condition variable
attributes object can be re-initialised using
pthread_condattr_init(); the results of otherwise
referencing the object after it has been destroyed are
undefined.
Additional attributes, their default values, and the names
of the associated functions to get and set those attribute
values are implementation-dependent.
RETURN VALUE
If successful, the pthread_condattr_init() and
pthread_condattr_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:
GNU Pth 1.3.7 29-Jul-2000 47
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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.
GNU Pth 1.3.7 29-Jul-2000 48
pthread(3) POSIX Threading API of GNU Pth pthread(3)
Additional attributes, their default values, and the names
of the associated functions to get and set those attribute
values are implementation-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);
GNU Pth 1.3.7 29-Jul-2000 49
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
successful 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_routine 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
GNU Pth 1.3.7 29-Jul-2000 50
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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.
GNU Pth 1.3.7 29-Jul-2000 51
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 undefined.
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);
GNU Pth 1.3.7 29-Jul-2000 52
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 limited 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 cancellation 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 variables 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.
GNU Pth 1.3.7 29-Jul-2000 53
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 simultaneously active. By default, the threads
implementation ensures that a sufficient number of threads
are active so that the process can continue to make
progress. While this conserves system resources, it may
not produce the most effective level of concurrency.
The 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 concurrency level at its discretion as if
pthread_setconcurrency() was never called.
The pthread_getconcurrency() function returns the value
set by a previous call to the pthread_setconcurrency()
function. If the pthread_setconcurrency() 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
GNU Pth 1.3.7 29-Jul-2000 54
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_getconcurrency()
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()
functions 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 scheduling 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);
GNU Pth 1.3.7 29-Jul-2000 55
pthread(3) POSIX Threading API of GNU Pth pthread(3)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
specified by the most recent pthread_setschedparam() or
pthread_create() call affecting the target thread, and
reflects any temporary adjustments to its priority as a
result of any priority inheritance or ceiling functions.
The pthread_setschedparam() function sets the scheduling
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 implementation-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 indicate 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:
GNU Pth 1.3.7 29-Jul-2000 56
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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 management
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(). Different threads may bind
different values to the same key. These values are
typically pointers to blocks of dynamically allocated
memory that have been reserved for use by the calling
thread.
GNU Pth 1.3.7 29-Jul-2000 57
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Otherwise, 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>.
GNU Pth 1.3.7 29-Jul-2000 58
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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 calling thread.
The pthread_join() function will not return an error code
of [EINTR].
EXAMPLES
None.
GNU Pth 1.3.7 29-Jul-2000 59
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 destructors, or they may
continue calling destructors until no non-NULL values with
associated destructors exist, even though this might
result in an infinite loop.
GNU Pth 1.3.7 29-Jul-2000 60
pthread(3) POSIX Threading API of GNU Pth pthread(3)RETURN VALUE
If successful, the pthread_key_create() function stores
the newly created 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
GNU Pth 1.3.7 29-Jul-2000 61
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 associated with key will no longer be
called upon thread exit.
RETURN VALUE
If successful, the pthread_key_delete() function returns
zero. Otherwise, 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 delivered 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. Otherwise the function returns an error number.
If the pthread_kill() function fails, no signal is sent.
GNU Pth 1.3.7 29-Jul-2000 62
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_mutexattr_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 initialisation,
the state of the mutex becomes initialised and unlocked.
Attempting to initialise an already initialised mutex
results in undefined behaviour.
The pthread_mutex_destroy() function destroys the mutex
object referenced by mutex; the mutex object becomes, in
effect, uninitialised. An implementation may cause
pthread_mutex_destroy() to set the object referenced by
GNU Pth 1.3.7 29-Jul-2000 63
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Attempting to destroy a locked mutex results in
undefined behaviour.
In cases where default mutex attributes are appropriate,
the macro PTHREAD_MUTEX_INITIALIZER can be used to
initialise mutexes that are statically allocated. The
effect is equivalent to dynamic initialisation by a call
to 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 indicate the error. The
[EBUSY] and [EINVAL] error checks, if implemented, act as
if they were performed immediately at the beginning of
processing for the function and cause an error return
prior to modifying the state of the mutex specified by
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
GNU Pth 1.3.7 29-Jul-2000 64
pthread(3) POSIX Threading API of GNU Pth pthread(3)
the object referenced by mutex while it is locked or
referenced (for example, while being used in a
pthread_cond_wait() or pthread_cond_timedwait()) 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_mutexattr_setpshared(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutex_setprioceiling, pthread_mutex_getprioceiling
- change the priority ceiling of a mutex (REALTIME
THREADS)
SYNOPSIS
#include <pthread.h>
int pthread_mutex_setprioceiling(pthread_mutex_t *mutex,
int prioceiling, int *old_ceiling);
int pthread_mutex_getprioceiling(const pthread_mutex_t
*mutex, int *prioceiling);
DESCRIPTION
The pthread_mutex_getprioceiling() function returns the
current priority 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 ceiling
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 priority ceiling is not changed.
GNU Pth 1.3.7 29-Jul-2000 65
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 implementation 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>
GNU Pth 1.3.7 29-Jul-2000 66
pthread(3) POSIX Threading API of GNU Pth pthread(3)
int pthread_mutex_init(pthread_mutex_t *mutex, const
pthread_mutexattr_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 initialisation,
the state of the mutex becomes initialised and unlocked.
Attempting to initialise an already initialised mutex
results in undefined behaviour.
The pthread_mutex_destroy() function destroys the mutex
object referenced by mutex; the mutex object becomes, in
effect, uninitialised. An implementation may cause
pthread_mutex_destroy() to set the object referenced 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. Attempting to destroy a locked mutex results in
undefined behaviour.
In cases where default mutex attributes are appropriate,
the macro PTHREAD_MUTEX_INITIALIZER can be used to
initialise mutexes that are statically allocated. The
effect is equivalent to dynamic initialisation by a call
to 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 indicate the error. The
[EBUSY] and [EINVAL] error checks, if implemented, act as
if they were performed immediately at the beginning of
processing for the function and cause an error return
prior to modifying the state of the mutex specified by
mutex.
ERRORS
The pthread_mutex_init() function will fail if:
[EAGAIN]
The system lacked the necessary resources (other than
memory) to initialise another mutex.
GNU Pth 1.3.7 29-Jul-2000 67
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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_timedwait()) 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_mutexattr_setpshared(), <pthread.h>.
______________________________________________________________________NAME
pthread_mutex_lock, pthread_mutex_trylock,
pthread_mutex_unlock - lock and unlock a mutex
SYNOPSIS
#include <pthread.h>
GNU Pth 1.3.7 29-Jul-2000 68
pthread(3) POSIX Threading API of GNU Pth pthread(3)
int pthread_mutex_lock(pthread_mutex_t *mutex); int
pthread_mutex_trylock(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 referenced 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,
GNU Pth 1.3.7 29-Jul-2000 69
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 indicate the error.
The function pthread_mutex_trylock() returns zero if a
lock on the mutex object referenced by mutex is acquired.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_mutex_lock() and pthread_mutex_trylock()
functions will fail if:
[EINVAL]
The mutex was created with the protocol attribute
having the value PTHREAD_PRIO_PROTECT and the calling
thread's priority is higher than the mutex's current
priority ceiling.
The pthread_mutex_trylock() function will fail if:
[EBUSY]
The mutex could not be acquired because it was already
locked.
The pthread_mutex_lock(), pthread_mutex_trylock() and
pthread_mutex_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:
GNU Pth 1.3.7 29-Jul-2000 70
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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 prioceiling, int *old_ceiling);
int pthread_mutex_getprioceiling(const pthread_mutex_t
*mutex, int *prioceiling);
DESCRIPTION
The pthread_mutex_getprioceiling() function returns the
current priority 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 ceiling
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 priority 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.
GNU Pth 1.3.7 29-Jul-2000 71
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 implementation 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_trylock(pthread_mutex_t *mutex); int
pthread_mutex_unlock(pthread_mutex_t *mutex);
DESCRIPTION
The mutex object referenced by mutex is locked by calling
GNU Pth 1.3.7 29-Jul-2000 72
pthread(3) POSIX Threading API of GNU Pth pthread(3)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 referenced 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).
GNU Pth 1.3.7 29-Jul-2000 73
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 indicate the error.
The function pthread_mutex_trylock() returns zero if a
lock on the mutex object referenced by mutex is acquired.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_mutex_lock() and pthread_mutex_trylock()
functions will fail if:
[EINVAL]
The mutex was created with the protocol attribute
having the value PTHREAD_PRIO_PROTECT and the calling
thread's priority is higher than the mutex's current
priority ceiling.
The pthread_mutex_trylock() function will fail if:
[EBUSY]
The mutex could not be acquired because it was already
locked.
The pthread_mutex_lock(), pthread_mutex_trylock() and
pthread_mutex_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].
GNU Pth 1.3.7 29-Jul-2000 74
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_trylock(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
GNU Pth 1.3.7 29-Jul-2000 75
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 referenced 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 indicate the error.
The function pthread_mutex_trylock() returns zero if a
lock on the mutex object referenced by mutex is acquired.
Otherwise, an error number is returned to indicate the
error.
ERRORS
The pthread_mutex_lock() and pthread_mutex_trylock()
functions will fail if:
[EINVAL]
The mutex was created with the protocol attribute
having the value PTHREAD_PRIO_PROTECT and the calling
thread's priority is higher than the mutex's current
priority ceiling.
The pthread_mutex_trylock() function will fail if:
GNU Pth 1.3.7 29-Jul-2000 76
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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
GNU Pth 1.3.7 29-Jul-2000 77
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 implementation 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 otherwise
referencing the object after it has been destroyed are
undefined.
RETURN VALUE
Upon successful completion, pthread_mutexattr_init() and
pthread_mutexattr_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>.
GNU Pth 1.3.7 29-Jul-2000 78
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________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_mutexattr_t
*attr, int *prioceiling);
DESCRIPTION
The pthread_mutexattr_setprioceiling() and
pthread_mutexattr_getprioceiling() functions,
respectively, set and get the priority ceiling attribute
of a mutex attribute object pointed to by attr which was
previously 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 section guarded by the mutex is
executed. In order to avoid priority inversion, the
priority ceiling of the mutex will be set to a priority
higher than or equal to the highest priority of all the
threads that may lock that mutex. The values of
prioceiling will be within the maximum range of priorities
defined under the SCHED_FIFO scheduling policy.
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_getprioceiling() functions will fail if:
[ENOSYS]
The option _POSIX_THREAD_PRIO_PROTECT is not defined
and the implementation does not support the function.
The pthread_mutexattr_setprioceiling() and
pthread_mutexattr_getprioceiling() functions may fail if:
GNU Pth 1.3.7 29-Jul-2000 79
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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 protocol); 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
GNU Pth 1.3.7 29-Jul-2000 80
pthread(3) POSIX Threading API of GNU Pth pthread(3)
the higher of its priority or the priority of the highest
priority thread waiting on any of the mutexes owned by
this thread and initialised with this protocol.
When a thread owns one or more mutexes initialised with
the PTHREAD_PRIO_PROTECT protocol, it executes at the
higher of its priority or the highest of the priority
ceilings of all the mutexes owned by this thread and
initialised with this attribute, regardless of whether
other threads are blocked on any of these mutexes or not.
While a thread is holding a mutex which has been
initialised with the PRIO_INHERIT or PRIO_PROTECT protocol
attributes, it will not be subject to being moved to the
tail of the scheduling queue at its priority in the event
that its original priority is changed, such as by a call
to 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 priority is
changed.
If a thread simultaneously owns several mutexes
initialised with different protocols, it will execute at
the highest of the priorities that it would have obtained
by each of these protocols.
When a thread makes a call to 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
calling thread as long as it continues to own the mutex.
The implementation updates its execution priority to the
maximum of its assigned priority and all its inherited
priorities. Furthermore, if this owner thread itself
becomes blocked on another mutex, the same priority
inheritance effect will be propagated to this other owner
thread, in a recursive manner.
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:
GNU Pth 1.3.7 29-Jul-2000 81
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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
GNU Pth 1.3.7 29-Jul-2000 82
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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
GNU Pth 1.3.7 29-Jul-2000 83
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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() functions 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 behaviour. Attempting to
unlock a mutex of this type which is not locked
GNU Pth 1.3.7 29-Jul-2000 84
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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() functions will fail if:
[EINVAL]
The value type is invalid.
The pthread_mutexattr_gettype() and
pthread_mutexattr_settype() functions 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_RECURSIVE mutex with condition variables
because the implicit unlock performed 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 predicate.
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>
GNU Pth 1.3.7 29-Jul-2000 85
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 implementation 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 otherwise
referencing the object after it has been destroyed are
undefined.
RETURN VALUE
Upon successful completion, pthread_mutexattr_init() and
pthread_mutexattr_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.
GNU Pth 1.3.7 29-Jul-2000 86
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_mutexattr_t
*attr, int *prioceiling);
DESCRIPTION
The pthread_mutexattr_setprioceiling() and
pthread_mutexattr_getprioceiling() functions,
respectively, set and get the priority ceiling attribute
of a mutex attribute object pointed to by attr which was
previously 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 section guarded by the mutex is
executed. In order to avoid priority inversion, the
priority ceiling of the mutex will be set to a priority
higher than or equal to the highest priority of all the
threads that may lock that mutex. The values of
prioceiling will be within the maximum range of priorities
defined under the SCHED_FIFO scheduling policy.
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_getprioceiling() functions will fail if:
GNU Pth 1.3.7 29-Jul-2000 87
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[ENOSYS]
The option _POSIX_THREAD_PRIO_PROTECT is not defined
and the implementation does not support the function.
The pthread_mutexattr_setprioceiling() and
pthread_mutexattr_getprioceiling() 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 protocol); 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>.
GNU Pth 1.3.7 29-Jul-2000 88
pthread(3) POSIX Threading API of GNU Pth pthread(3)
When a thread owns a mutex with the PTHREAD_PRIO_NONE
protocol attribute, its priority and scheduling are not
affected by its mutex ownership.
When a thread is blocking higher priority threads because
of owning one or more mutexes with the
PTHREAD_PRIO_INHERIT protocol attribute, it executes at
the higher of its priority or the priority of the highest
priority thread waiting on any of the mutexes owned by
this thread and initialised with this protocol.
When a thread owns one or more mutexes initialised with
the PTHREAD_PRIO_PROTECT protocol, it executes at the
higher of its priority or the highest of the priority
ceilings of all the mutexes owned by this thread and
initialised with this attribute, regardless of whether
other threads are blocked on any of these mutexes or not.
While a thread is holding a mutex which has been
initialised with the PRIO_INHERIT or PRIO_PROTECT protocol
attributes, it will not be subject to being moved to the
tail of the scheduling queue at its priority in the event
that its original priority is changed, such as by a call
to 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 priority is
changed.
If a thread simultaneously owns several mutexes
initialised with different protocols, it will execute at
the highest of the priorities that it would have obtained
by each of these protocols.
When a thread makes a call to 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
calling thread as long as it continues to own the mutex.
The implementation updates its execution priority to the
maximum of its assigned priority and all its inherited
priorities. Furthermore, if this owner thread itself
becomes blocked on another mutex, the same priority
inheritance effect will be propagated to this other owner
thread, in a recursive manner.
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
GNU Pth 1.3.7 29-Jul-2000 89
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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
GNU Pth 1.3.7 29-Jul-2000 90
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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(),
GNU Pth 1.3.7 29-Jul-2000 91
pthread(3) POSIX Threading API of GNU Pth pthread(3)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() functions 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.
GNU Pth 1.3.7 29-Jul-2000 92
pthread(3) POSIX Threading API of GNU Pth pthread(3)
PTHREAD_MUTEX_DEFAULT
Attempting to recursively lock a mutex of this type
results in undefined behaviour. Attempting to unlock a
mutex of this type which was not locked by the calling
thread results in undefined behaviour. Attempting to
unlock a mutex of this type which is not locked
results in undefined behaviour. An implementation is
allowed to map this mutex to one of the other mutex
types.
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() functions will fail if:
[EINVAL]
The value type is invalid.
The pthread_mutexattr_gettype() and
pthread_mutexattr_settype() functions 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_RECURSIVE mutex with condition variables
because the implicit unlock performed 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 predicate.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_cond_wait(), pthread_cond_timedwait(),
<pthread.h>.
GNU Pth 1.3.7 29-Jul-2000 93
pthread(3) POSIX Threading API of GNU Pth pthread(3)______________________________________________________________________NAME
pthread_once - dynamic package initialisation
SYNOPSIS
#include <pthread.h>
int pthread_once(pthread_once_t *once_control, void
(*init_routine)(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
guaranteed 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 automatic 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.
GNU Pth 1.3.7 29-Jul-2000 94
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_rwlockattr_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 referenced 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
undefined behaviour. A destroyed read-write lock object
can be re-initialised using pthread_rwlock_init(); the
results of otherwise referencing the read-write lock
object after it has been destroyed are undefined.
In cases where default read-write lock attributes are
appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be
used to initialise read-write locks that are statically
allocated. The effect is equivalent to dynamic
initialisation by a call to pthread_rwlock_init() with the
GNU Pth 1.3.7 29-Jul-2000 95
pthread(3) POSIX Threading API of GNU Pth pthread(3)
parameter attr specified as NULL, except that no error
checks are performed.
RETURN VALUE
If successful, the pthread_rwlock_init() and
pthread_rwlock_destroy() functions return zero.
Otherwise, an error number is returned to indicate the
error. The [EBUSY] and [EINVAL] error checks, if
implemented, will act as if they were performed
immediately at the beginning of processing for the
function and caused an error return prior to modifying the
state of the read-write lock specified by 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
GNU Pth 1.3.7 29-Jul-2000 96
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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_rwlockattr_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 referenced 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
undefined behaviour. A destroyed read-write lock object
GNU Pth 1.3.7 29-Jul-2000 97
pthread(3) POSIX Threading API of GNU Pth pthread(3)
can be re-initialised using pthread_rwlock_init(); the
results of otherwise referencing the read-write lock
object after it has been destroyed are undefined.
In cases where default read-write lock attributes are
appropriate, the macro PTHREAD_RWLOCK_INITIALIZER can be
used to initialise read-write locks that are statically
allocated. The effect is equivalent to dynamic
initialisation by a call to pthread_rwlock_init() with the
parameter attr specified as NULL, except that no error
checks are performed.
RETURN VALUE
If successful, the pthread_rwlock_init() and
pthread_rwlock_destroy() functions return zero.
Otherwise, an error number is returned to indicate the
error. The [EBUSY] and [EINVAL] error checks, if
implemented, will act as if they were performed
immediately at the beginning of processing for the
function and caused an error return prior to modifying the
state of the read-write lock specified by 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.
GNU Pth 1.3.7 29-Jul-2000 98
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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()GNU Pth 1.3.7 29-Jul-2000 99
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Otherwise, 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
GNU Pth 1.3.7 29-Jul-2000 100
pthread(3) POSIX Threading API of GNU Pth pthread(3)
keeping with its objective of ensuring that CAE
Specifications are fully aligned with formal standards,
The Open Group intends to add any new interfaces adopted
by an official IEEE standard in this area.
Realtime applications may encounter priority inversion
when using read-write locks. The problem occurs when a
high priority thread "locks" a read-write lock
that is about to be "unlocked" by a low priority
thread, but the low priority thread is preempted by a
medium priority thread. This scenario leads to priority
inversion; a high priority thread is blocked by lower
priority threads for an unlimited period of time. During
system design, realtime programmers must take into account
the possibility of this kind of priority inversion. They
can deal with it in a number of ways, such as by having
critical sections that are guarded by read-write locks
execute at a high priority, so that a thread cannot be
preempted while executing in its critical section.
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.
GNU Pth 1.3.7 29-Jul-2000 101
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Otherwise, 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
GNU Pth 1.3.7 29-Jul-2000 102
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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
priority threads for an unlimited period of time. During
system design, realtime programmers must take into account
the possibility of this kind of priority inversion. They
can deal with it in a number of ways, such as by having
critical sections that are guarded by read-write locks
execute at a high priority, so that a thread cannot be
preempted while executing in its critical section.
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
GNU Pth 1.3.7 29-Jul-2000 103
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Otherwise, 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,
GNU Pth 1.3.7 29-Jul-2000 104
pthread(3) POSIX Threading API of GNU Pth pthread(3)
The Open Group intends to add any new interfaces adopted
by an official IEEE standard in this area.
Realtime applications may encounter priority inversion
when using read-write locks. The problem occurs when a
high priority thread "locks" a read-write lock
that is about to be "unlocked" by a low priority
thread, but the low priority thread is preempted by a
medium priority thread. This scenario leads to priority
inversion; a high priority thread is blocked by lower
priority threads for an unlimited period of time. During
system design, realtime programmers must take into account
the possibility of this kind of priority inversion. They
can deal with it in a number of ways, such as by having
critical sections that are guarded by read-write locks
execute at a high priority, so that a thread cannot be
preempted while executing in its critical section.
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 undefined 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
GNU Pth 1.3.7 29-Jul-2000 105
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 scheduling policy
is used to determine which thread acquires the read-write
lock object for writing. If there are multiple threads
waiting to acquire the read-write lock object for reading,
the scheduling policy is used to determine the order in
which the waiting threads acquire the read-write lock
object for reading. If there are multiple threads blocked
on rwlock for both read locks and write locks, it is
unspecified whether the readers acquire the lock first or
whether a writer acquires the lock first.
Results are undefined if any of these functions are called
with an uninitialised read-write lock.
RETURN VALUE
If successful, the pthread_rwlock_unlock() function
returns zero. Otherwise, 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().
______________________________________________________________________GNU Pth 1.3.7 29-Jul-2000 106
pthread(3) POSIX Threading API of GNU Pth pthread(3)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. Otherwise, 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.
GNU Pth 1.3.7 29-Jul-2000 107
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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
priority threads for an unlimited period of time. During
system design, realtime programmers must take into account
the possibility of this kind of priority inversion. They
can deal with it in a number of ways, such as by having
critical sections that are guarded by read-write locks
execute at a high priority, so that a thread cannot be
preempted while executing in its critical section.
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
GNU Pth 1.3.7 29-Jul-2000 108
pthread(3) POSIX Threading API of GNU Pth pthread(3)
*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 initialised read-write
locks.
The pthread_rwlockattr_destroy() function destroys a read-
write lock attributes object. The effect of subsequent use
of the object is undefined until the object is re-
initialised by another call to pthread_rwlockattr_init().
An implementation may cause pthread_rwlockattr_destroy()
to set the object referenced by attr to an invalid value.
RETURN VALUE
If successful, the pthread_rwlockattr_init() and
pthread_rwlockattr_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.
GNU Pth 1.3.7 29-Jul-2000 109
pthread(3) POSIX Threading API of GNU Pth pthread(3)SEE ALSO
<pthread.h>, pthread_rwlock_init(),
pthread_rwlock_unlock(), pthread_rwlock_wrlock(),
pthread_rwlock_rdlock(), pthread_rwlockattr_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 referenced 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 number is returned to indicate the error.
ERRORS
The pthread_rwlockattr_getpshared() and
GNU Pth 1.3.7 29-Jul-2000 110
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_rwlockattr_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 initialised read-write
GNU Pth 1.3.7 29-Jul-2000 111
pthread(3) POSIX Threading API of GNU Pth pthread(3)
locks.
The pthread_rwlockattr_destroy() function destroys a read-
write lock attributes object. The effect of subsequent use
of the object is undefined until the object is re-
initialised by another call to pthread_rwlockattr_init().
An implementation may cause pthread_rwlockattr_destroy()
to set the object referenced by attr to an invalid value.
RETURN VALUE
If successful, the pthread_rwlockattr_init() and
pthread_rwlockattr_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_rwlockattr_getpshared().
______________________________________________________________________NAME
pthread_rwlockattr_getpshared,
pthread_rwlockattr_setpshared - get and set process-shared
attribute of read-write lock attributes object
SYNOPSIS
#include <pthread.h>
GNU Pth 1.3.7 29-Jul-2000 112
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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 referenced 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 number 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.
GNU Pth 1.3.7 29-Jul-2000 113
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_rwlockattr_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
GNU Pth 1.3.7 29-Jul-2000 114
pthread(3) POSIX Threading API of GNU Pth pthread(3)SYNOPSIS
#include <pthread.h>
int pthread_setcancelstate(int state, int *oldstate); int
pthread_setcanceltype(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_CANCEL_DISABLE.
The pthread_setcanceltype() function atomically both sets
the calling thread's cancelability type to the indicated
type and returns the previous cancelability type at the
location referenced by oldtype. Legal values for type are
PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
The cancelability state and type of any newly created
threads, including the thread in which main() was first
invoked, are PTHREAD_CANCEL_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 indicate the error.
ERRORS
The pthread_setcancelstate() function may fail if:
[EINVAL]
The specified state is not PTHREAD_CANCEL_ENABLE or
PTHREAD_CANCEL_DISABLE.
The pthread_setcanceltype() function may fail if:
[EINVAL]
The specified type is not PTHREAD_CANCEL_DEFERRED or
PTHREAD_CANCEL_ASYNCHRONOUS.
These functions will not return an error code of [EINTR].
EXAMPLES
None.
APPLICATION USAGE
None.
GNU Pth 1.3.7 29-Jul-2000 115
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_setcanceltype(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_CANCEL_DISABLE.
The pthread_setcanceltype() function atomically both sets
the calling thread's cancelability type to the indicated
type and returns the previous cancelability type at the
location referenced by oldtype. Legal values for type are
PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
The cancelability state and type of any newly created
threads, including the thread in which main() was first
invoked, are PTHREAD_CANCEL_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 indicate the error.
ERRORS
The pthread_setcancelstate() function may fail if:
[EINVAL]
The specified state is not PTHREAD_CANCEL_ENABLE or
PTHREAD_CANCEL_DISABLE.
The pthread_setcanceltype() function may fail if:
GNU Pth 1.3.7 29-Jul-2000 116
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[EINVAL]
The specified type is not PTHREAD_CANCEL_DEFERRED or
PTHREAD_CANCEL_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 scheduling 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
GNU Pth 1.3.7 29-Jul-2000 117
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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
specified by the most recent pthread_setschedparam() or
pthread_create() call affecting the target thread, and
reflects any temporary adjustments to its priority as a
result of any priority inheritance or ceiling functions.
The pthread_setschedparam() function sets the scheduling
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 implementation-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 indicate 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.
GNU Pth 1.3.7 29-Jul-2000 118
pthread(3) POSIX Threading API of GNU Pth pthread(3)
[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 management
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(). Different threads may bind
different values to the same key. These values are
typically pointers to blocks of dynamically allocated
memory that have been reserved for use by the calling
thread.
The 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.
GNU Pth 1.3.7 29-Jul-2000 119
pthread(3) POSIX Threading API of GNU Pth pthread(3)
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. Otherwise, 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);
GNU Pth 1.3.7 29-Jul-2000 120
pthread(3) POSIX Threading API of GNU Pth pthread(3)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_setcanceltype(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_CANCEL_DISABLE.
The pthread_setcanceltype() function atomically both sets
the calling thread's cancelability type to the indicated
type and returns the previous cancelability type at the
location referenced by oldtype. Legal values for type are
PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
The cancelability state and type of any newly created
threads, including the thread in which main() was first
invoked, are PTHREAD_CANCEL_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 indicate the error.
ERRORS
The pthread_setcancelstate() function may fail if:
[EINVAL]
The specified state is not PTHREAD_CANCEL_ENABLE or
PTHREAD_CANCEL_DISABLE.
The pthread_setcanceltype() function may fail if:
[EINVAL]
The specified type is not PTHREAD_CANCEL_DEFERRED or
PTHREAD_CANCEL_ASYNCHRONOUS.
GNU Pth 1.3.7 29-Jul-2000 121
pthread(3) POSIX Threading API of GNU Pth pthread(3)
These functions will not return an error code of [EINTR].
EXAMPLES
None.
APPLICATION USAGE
None.
FUTURE DIRECTIONS
None.
SEE ALSOpthread_cancel(), <pthread.h>.
GNU Pth 1.3.7 29-Jul-2000 122
pthread(3) POSIX Threading API of GNU Pth pthread(3)GNU Pth 1.3.7 29-Jul-2000 123
