--- name: "pthread_mutexattr" section: "3" platform: "macos" package: "libpthread" version: "539.100.4" release: "macOS 26.5" platforms: ["freebsd", "macos"] url: "https://new.carta.tech/pthread_mutexattr" --- # pthread\_mutexattr(3) mutex attribute operations ## 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** – mutex attribute operations ## SYNOPSIS **#include \** *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*); ## 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)](/pthread_mutex_init/3.md), 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)](/pthread_mutex_unlock/3.md) 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)](/pthread_cond_wait/3.md) and [pthread\_cond\_timedwait(3)](/pthread_cond_timedwait/3.md). - 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\_mutexaddr\_init**(). **pthread\_mutexattr\_gettype**() functions copy the type value of the attribute to the location pointed to by the second parameter. The **pthread\_mutexattr\_setpolicy\_np**() function sets the mutex *policy* value of the attribute. Valid mutex policies are: - PTHREAD\_MUTEX\_POLICY\_FIRSTFIT\_NP 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. - PTHREAD\_MUTEX\_POLICY\_FAIRSHARE\_NP 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 **pthread\_mutexattr\_getpolicy\_np**() function copies the mutex *policy* value of the attribute to the location pointed to by the second parameter. The **pthread\_mutexattr\_set\***() functions set the attribute that corresponds to each function name. The **pthread\_mutexattr\_get\***() functions copy the value of the attribute that corresponds to each function name to the location pointed to by the second function parameter. ## RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. ## ENVIRONMENT The following environment variables change the behavior of the pthread mutex implementation. - PTHREAD\_MUTEX\_DEFAULT\_POLICY 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* PTHREAD\_MUTEX\_POLICY\_FAIRSHARE\_NP - *3* PTHREAD\_MUTEX\_POLICY\_FIRSTFIT\_NP ## BACKWARDS COMPATIBILITY 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 **pthread\_mutexattr\_setpolicy\_np**() 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. ## ERRORS The **pthread\_mutexattr\_init**() function shall fail if: - \[ENOMEM\] Out of memory. The **pthread\_mutexattr\_destroy**() function will fail if: - \[EINVAL\] Invalid value for *attr*. The **pthread\_mutexattr\_setprioceiling**() function will fail if: - \[EINVAL\] Invalid value for *attr*, or invalid value for *prioceiling*. The **pthread\_mutexattr\_getprioceiling**() function will fail if: - \[EINVAL\] Invalid value for *attr*. The **pthread\_mutexattr\_setprotocol**() function will fail if: - \[EINVAL\] Invalid value for *attr*, or invalid value for *protocol*. The **pthread\_mutexattr\_getprotocol**() function will fail if: - \[EINVAL\] Invalid value for *attr*. The **pthread\_mutexattr\_settype**() function shall fail if: - \[EINVAL\] The value specified either by *type* or *attr* is invalid. The **pthread\_mutexattr\_gettype**() function will fail if: - \[EINVAL\] Invalid value for *attr*. The **pthread\_mutexattr\_setpolicy\_np**() function will fail if: - \[EINVAL\] Invalid value for *attr*. The **pthread\_mutexattr\_getpolicy\_np**() function will fail if: - \[EINVAL\] The value specified either by *type* or *attr* is invalid. ## SEE ALSO [pthread\_mutex\_init(3)](/pthread_mutex_init/3.md) ## STANDARDS 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”)