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 — mutex attribute operations

#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 *attr, int *type);

int
pthread_mutexattr_setpolicy_np(pthread_mutexattr_t *attr, int policy);

int
pthread_mutexattr_getpolicy_np(pthread_mutexattr_t *attr, int *policy);

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

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

The () function sets the mutex policy value of the attribute. Valid mutex policies are:

The first-fit mutex policy allows acquisition of the mutex to occur in any order. This policy is similar in operation to os_unfair_lock, new contending acquirers may obtain ownership of the mutex ahead of existing waiters.
The fairshare mutex policy guarantees that ownership of a contended mutex will be granted to waiters on a strictly ordered first-in, first-out basis. That is, a mutex holder that unlocks the mutex and then attempts to relock will wait behind existing threads already waiting on the mutex before being granted ownership again.

The () function copies the mutex policy value of the attribute to the location pointed to by the second parameter.

The () functions set the attribute that corresponds to each function name.

The () functions copy the value of the attribute that corresponds to each function name to the location pointed to by the second function parameter.

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

The following environment variables change the behavior of the pthread mutex implementation.

Controls the process-wide policy used when initializing a pthread_mutex_t that has not had a policy set via pthread_mutexattr_setpolicy_np(). The valid values are mapped as:
1
3

Prior to macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) the only available pthread mutex policy mode was PTHREAD_MUTEX_POLICY_FAIRSHARE_NP. macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) introduces PTHREAD_MUTEX_POLICY_FIRSTFIT_NP and also makes this the default mode for mutexes initialized without a policy attribute set.

Attempting to use () to set the policy of a pthread_mutex_t to PTHREAD_MUTEX_POLICY_FIRSTFIT_NP on earlier releases will fail with EINVAL and the mutex will continue to operate in fairshare mode.

The pthread_mutexattr_init() function shall fail if:

[]
Out of memory.

The pthread_mutexattr_destroy() function will fail if:

[]
Invalid value for attr.

The pthread_mutexattr_setprioceiling() function will fail if:

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

The pthread_mutexattr_getprioceiling() function will fail if:

[]
Invalid value for attr.

The pthread_mutexattr_setprotocol() function will fail if:

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

The pthread_mutexattr_getprotocol() function will fail if:

[]
Invalid value for attr.

The pthread_mutexattr_settype() function shall fail if:

[]
The value specified either by type or attr is invalid.

The pthread_mutexattr_gettype() function will fail if:

[]
Invalid value for attr.

The pthread_mutexattr_setpolicy_np() function will fail if:

[]
Invalid value for attr.

The pthread_mutexattr_getpolicy_np() function will fail if:

[]
The value specified either by type or attr is invalid.

pthread_mutex_init(3)

The pthread_mutexattr_init() and pthread_mutexattr_destroy() functions conform to ISO/IEC 9945-1:1996 (“POSIX.1”)

The pthread_mutexattr_setprioceiling(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(), pthread_mutexattr_getprotocol(), pthread_mutexattr_settype(), and pthread_mutexattr_gettype() functions conform to Version 2 of the Single UNIX Specification (“SUSv2”)

July 9, 2010 macOS 15.0