NAME
pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), pthread_mutexattr_gettype(), pthread_mutexattr_settype() — get and set the process-shared attribute and type attribute
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
int pshared);
int pthread_mutexattr_getpshared(const pthread_mutexattr_t
*__restrict attr, int *__restrict pshared);
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
int pthread_mutexattr_gettype(const pthread_mutexattr_t
*__restrict attr, int *__restrict type);
PARAMETERS
- attr
Pointer to the mutex attributes object whose attributes are to be set/retrieved.
- pshared
This parameter either specifies the new value of the
process-shared
attribute (set function) or
points to the memory location where the
process-shared
attribute of
attr
is to be returned (get function).
- type
This parameter either specifies the new value of the
type
attribute (set function) or
points to the memory location where the
type
attribute of
attr
is to be returned (get function).
DESCRIPTION
The attributes object
attr
must have been previously initialized with the
function
pthread_mutexattr_init()
before these functions are called.
ATTRIBUTE: pshared
Mutexes can be used by threads only within a process or shared by
threads in multiple processes. The
process-shared
attribute in a mutex attributes object describes who may use the mutex.
The legal values for the
process-shared
attribute are:
- PTHREAD_PROCESS_SHARED
This option permits a mutex to be operated upon by any thread that has access
to the memory where the mutex is allocated.
The application is responsible for allocating the mutex in
memory that multiple processes can access.
- PTHREAD_PROCESS_PRIVATE
The mutex can be operated upon only by threads created within the same process
as the thread that initialized the mutex. If threads of differing processes
attempt to operate on such mutex, the behavior is undefined.
The default value of
process-shared
is
PTHREAD_PROCESS_PRIVATE.
pthread_mutexattr_setpshared()
is used to set the
process-shared
attribute in
attr.
The new value of the
process-shared
attribute of
attr
is set to the value specified in the
pshared
parameter.
pthread_mutexattr_getpshared()
retrieves the value of the
process-shared
attribute from
attr.
The value of the
process-shared
attribute of
attr
is returned in the
pshared
parameter.
ATTRIBUTE: type
Mutexes can be created with four different types.
The type of a mutex is contained in the
type
attribute of the mutex attributes object.
Valid values for the
type
attribute are:
- PTHREAD_MUTEX_NORMAL
This type of mutex does not provide deadlock detection.
A thread attempting to relock this mutex without first unlocking it
shall deadlock. An error is not returned to the caller.
Attempting to unlock a mutex locked by a different thread results in
undefined behavior. Attempting to unlock an unlocked mutex results in
undefined behavior.
- PTHREAD_MUTEX_ERRORCHECK
This type of mutex provides error checking. An owner
field is maintained. Only the mutex lock owner shall
successfully unlock this mutex. A thread attempting to
relock this mutex shall return with an error.
A thread attempting to unlock a mutex locked by a different thread
shall return with an error.
A thread attempting to unlock an unlocked mutex shall return with an error.
This type of mutex is useful for debugging.
- PTHREAD_MUTEX_RECURSIVE
Deadlock cannot occur with this type of mutex. An owner
field is maintained. A thread attempting to relock this
mutex shall successfully lock the mutex.
Multiple locks of this mutex shall require the same
number of unlocks to release the mutex before another
thread can lock the mutex.
A thread attempting to unlock a mutex locked by a different thread
shall return with an error.
A thread attempting to unlock an unlocked mutex shall return with an error.
- PTHREAD_MUTEX_NO_OWNER_NP
This type of mutex does not provide deadlock detection.
A thread attempting to relock this mutex without first unlocking it
shall deadlock. An error is not returned to the caller.
This type of mutex can be unlocked by a thread other than the owner.
Attempting to unlock an unlocked mutex results in
undefined behavior.
- PTHREAD_MUTEX_DEFAULT
Attempting to recursively lock a mutex of this type results in
undefined behavior.
Attempting to unlock a mutex locked by a different thread results in
undefined behavior. Attempting to unlock an unlocked mutex results in
undefined behavior.
An implementation shall be allowed to map this mutex to one of the other
mutex types.
The default value of the
type
attribute is
PTHREAD_MUTEX_DEAFULT.
pthread_mutexattr_settype()
is used to set the
type
attribute in
attr.
The new value of the
type
attribute of
attr
is set to the value specified in the
type
parameter.
pthread_mutexattr_gettype()
retrieves the value of the
type
attribute from
attr.
The value of the
type
attribute of
attr
is returned in the
type
parameter.
Never 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 situation happens,
no other thread can satisfy the condition of the predicate.
RETURN VALUE
Upon successful completion,
pthread_mutexattr_getpshared(),
pthread_mutexattr_setpshared(),
pthread_mutexattr_gettype(),
and
pthread_mutexattr_settype()
return zero. Otherwise, an error number is returned to indicate the error
(the
errno
variable is not set).
ERRORS
If any of the following occur, the
pthread_mutexattr_getpshared()
and
pthread_mutexattr_setpshared()
functions return the corresponding error number:
- ENOSYS
_POSIX_THREAD_PROCESS_SHARED
is not defined and these functions are not supported.
For each of the following conditions, if the condition is detected, the
pthread_mutexattr_getpshared(),
pthread_mutexattr_setpshared(),
pthread_mutexattr_gettype(),
and
pthread_mutexattr_settype()
functions return the corresponding error number:
- EINVAL
attr
is not a valid mutex attributes object.
- EINVAL
The value specified by
pshared
or
type
is not a legal value.
EINVAL
The value
pshared
or
type
points to an illegal address.
WARNINGS
If a mutex is created with the
process-shared
attribute defined as
PTHREAD_PROCESS_SHARED,
the cooperating processes should have access to the memory in which the
mutex is allocated.
AUTHOR
pthread_mutexattr_setpshared()
and
pthread_mutexattr_getpshared()
were derived from the IEEE POSIX P1003.1c standard.
pthread_mutexattr_settype(),
and
pthread_mutexattr_gettype()
were developed by X/Open.
STANDARDS CONFORMANCE
pthread_mutexattr_setpshared(): POSIX 1003.1c.
pthread_mutexattr_getpshared(): POSIX 1003.1c.
pthread_mutexattr_settype(): X/Open.
pthread_mutexattr_gettype(): X/Open.
Printable version
