pthread_mutexattr_settype()

Updated: May 06, 2022

Set a mutex type

Synopsis:

#include <pthread.h>

int pthread_mutexattr_settype( 
                      pthread_mutexattr_t * attr, 
                      int type );

Arguments:

attr
A pointer to the pthread_mutexattr_t object that you want to set the attribute in.
type
The new type; one of:
  • PTHREAD_MUTEX_NORMAL
  • PTHREAD_MUTEX_ERRORCHECK
  • PTHREAD_MUTEX_RECURSIVE
  • PTHREAD_MUTEX_DEFAULT

In QNX Neutrino, PTHREAD_MUTEX_DEFAULT mutexes are treated in the same way as PTHREAD_MUTEX_ERRORCHECK ones.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_mutexattr_settype() function sets the mutex type in the mutex attribute object attr to the value given by type.

To make the mutext robust (PTHREAD_MUTEX_ROBUST) or nonrobust (PTHREAD_MUTEX_STALLED), call pthread_mutexattr_setrobust().

The type and the robustness govern the behavior of the mutex when you relock the mutex without first unlocking it, and when you try to unlock a mutex that you don't own or that isn't locked:

Mutex type Robustness Relock Unlock when not the owner
NORMAL STALLED Deadlock Undefined behavior
NORMAL ROBUST Deadlock pthread_mutex_unlock() returns EPERM
ERRORCHECK Either pthread_mutex_lock() and pthread_mutex_timedlock() return EDEADLK pthread_mutex_unlock() returns EPERM
RECURSIVE Either The lock count is incremented. You must unlock it the same number of times before another thread can acquire the mutex. pthread_mutex_unlock() returns EPERM
DEFAULT Either pthread_mutex_lock() and pthread_mutex_timedlock() return EDEADLK pthread_mutex_unlock() returns EPERM
Note: You can't use a robust mutex with SyncMutexEvent(). The two mechanisms achieve the same goal in different ways.

Returns:

EOK
Success.
EINVAL
The value specified by attr or type is invalid.

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

An application shouldn't 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's been locked multiple times). If this happens, no other thread can satisfy the condition of the predicate.