NAME
pthread_mutexattr_init,
pthread_mutexattr_destroy,
pthread_mutexattr_setprioceiling,
pthread_mutexattr_getprioceiling,
pthread_mutexattr_setprotocol,
pthread_mutexattr_getprotocol,
pthread_mutexattr_settype,
pthread_mutexattr_gettype,
pthread_mutexattr_getpshared,
pthread_mutexattr_setpshared —
mutex
attribute operations
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_mutexattr_init(
pthread_mutexattr_t
*attr);
int
pthread_mutexattr_destroy(
pthread_mutexattr_t
*attr);
int
pthread_mutexattr_setprioceiling(
pthread_mutexattr_t
*attr,
int
prioceiling);
int
pthread_mutexattr_getprioceiling(
pthread_mutexattr_t
*attr,
int
*prioceiling);
int
pthread_mutexattr_setprotocol(
pthread_mutexattr_t
*attr,
int protocol);
int
pthread_mutexattr_getprotocol(
pthread_mutexattr_t
*attr,
int
*protocol);
int
pthread_mutexattr_settype(
pthread_mutexattr_t
*attr,
int type);
int
pthread_mutexattr_gettype(
pthread_mutexattr_t
* restrict attr,
int *
restrict type);
int
pthread_mutexattr_getpshared(
const
pthread_mutexattr_t * __restrict attr,
int * __restrict pshared);
int
pthread_mutexattr_setpshared(
pthread_mutexattr_t
* attr,
int pshared);
DESCRIPTION
Mutex attributes are used to specify parameters to
pthread_mutex_init(). Like with thread attributes, one
attribute object can be used in multiple calls to
pthread_mutex_init(3),
with or without modifications between calls.
The
pthread_mutexattr_init() function initializes
attr with all the default mutex attributes.
The
pthread_mutexattr_destroy() function destroys
attr.
The
pthread_mutexattr_settype() functions set the mutex
type value of the attribute. Valid mutex types are:
-
-
PTHREAD_MUTEX_NORMAL
- This type of mutex does not check for usage errors. It will
deadlock if reentered, and result in undefined behavior if a locked mutex
is unlocked by another thread. Attempts to unlock an already unlocked
PTHREAD_MUTEX_NORMAL
mutex will result in
undefined behavior.
-
-
PTHREAD_MUTEX_ERRORCHECK
- These mutexes do check for usage errors. If an attempt is
made to relock a
PTHREAD_MUTEX_ERRORCHECK
mutex
without first dropping the lock, an error will be returned. If a thread
attempts to unlock a PTHREAD_MUTEX_ERRORCHECK
mutex that is locked by another thread, an error will be returned. If a
thread attempts to unlock a
PTHREAD_MUTEX_ERRORCHECK
thread that is unlocked,
an error will be returned.
-
-
PTHREAD_MUTEX_RECURSIVE
- These mutexes allow recursive locking. An attempt to relock
a
PTHREAD_MUTEX_RECURSIVE
mutex that is already
locked by the same thread succeeds. An equivalent number of
pthread_mutex_unlock(3)
calls are needed before the mutex will wake another thread waiting on this
lock. If a thread attempts to unlock a
PTHREAD_MUTEX_RECURSIVE
mutex that is locked by
another thread, an error will be returned. If a thread attempts to unlock
a PTHREAD_MUTEX_RECURSIVE
thread that is unlocked,
an error will be returned.
It is advised that PTHREAD_MUTEX_RECURSIVE
mutexes
are not used with condition variables. This is because of the implicit
unlocking done by
pthread_cond_wait(3)
and
pthread_cond_timedwait(3).
-
-
PTHREAD_MUTEX_DEFAULT
- Also this type of mutex will cause undefined behavior if
reentered. Unlocking a
PTHREAD_MUTEX_DEFAULT
mutex
locked by another thread will result in undefined behavior. Attempts to
unlock an already unlocked PTHREAD_MUTEX_DEFAULT
mutex will result in undefined behavior.
This is the default mutex type for
pthread_mutexattr_init().
The
pthread_mutexattr_gettype() functions copy the type value
of the attribute to the location pointed to by the second parameter.
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
pthread_mutexattr_getprotocol() and
pthread_mutexattr_setprotocol() functions shall get and set
the protocol attribute of a mutex attributes object pointed to by
attr which was previously created by the function
pthread_mutexattr_init().
The
pthread_mutexattr_getprioceiling() and
pthread_mutexattr_setprioceiling() functions, shall get and
set the priority ceiling attribute of a mutex attributes object pointed to by
attr which was previously created by the function
pthread_mutexattr_init().
RETURN VALUES
If successful, these functions return 0. Otherwise, an error number is returned
to indicate the error.
ERRORS
The
pthread_mutexattr_init() function shall fail if:
-
-
- [
ENOMEM
]
- Insufficient memory exists to initialize the mutex
attributes object.
The
pthread_mutexattr_settype() function shall fail if:
-
-
- [
EINVAL
]
- The value specified either by type or
attr is invalid.
No error numbers are defined for the
pthread_mutexattr_destroy() and
pthread_mutexattr_gettype() functions.
pthread_mutexattr_setprioceiling() may fail if:
-
-
- [
EINVAL
]
- Invalid value for attr, or invalid
value for prioceiling.
pthread_mutexattr_getprioceiling() may fail if:
-
-
- [
EINVAL
]
- Invalid value for attr.
pthread_mutexattr_setprotocol() may fail if:
-
-
- [
EINVAL
]
- Invalid value for attr, or invalid
value for protocol.
pthread_mutexattr_getprotocol() may fail if:
-
-
- [
EINVAL
]
- Invalid value for attr.
pthread_mutexattr_getpshared() and
pthread_mutexattr_setpshared() may fail if:
-
-
- [
EINVAL
]
- the value specified by attr is
invalid.
SEE ALSO
pthread_mutex_init(3)
STANDARDS
These functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”).
BUGS
The
pthread_mutexattr_getpshared() and
pthread_mutexattr_setpshared() functions are hidden by
default since only thread shared attributes are supported.