PTHREAD_MUTEXATTR(3) Library Functions Manual PTHREAD_MUTEXATTR(3)

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

POSIX Threads Library (libpthread, -lpthread)

#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);

Mutex attributes are used to specify parameters to (). 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 () function initializes attr with all the default mutex attributes.

The () function destroys attr.

The () functions set the mutex type value of the attribute. Valid mutex types are:

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.
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.
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).

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 ().

The () functions copy the type value of the attribute to the location pointed to by the second parameter.

The () function obtains the value of the process-shared attribute from the attributes object referenced by attr.

The () function is used to set the process-shared attribute in an initialised attributes object referenced by attr.

The () and () 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 () and () 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().

If successful, these functions return 0. Otherwise, an error number is returned to indicate the error.

The pthread_mutexattr_init() function shall fail if:

[]
Insufficient memory exists to initialize the mutex attributes object.

The pthread_mutexattr_settype() function shall fail if:

[]
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:

[]
Invalid value for attr, or invalid value for prioceiling.

pthread_mutexattr_getprioceiling() may fail if:

[]
Invalid value for attr.

pthread_mutexattr_setprotocol() may fail if:

[]
Invalid value for attr, or invalid value for protocol.

pthread_mutexattr_getprotocol() may fail if:

[]
Invalid value for attr.

pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() may fail if:

[]
the value specified by attr is invalid.

pthread_mutex_init(3)

These functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).

The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() functions are hidden by default since only thread shared attributes are supported.

June 12, 2016 NetBSD 11.0