pthread_mutexattr_setrobust()

Updated: April 19, 2023

Set the robust attribute in a mutex attribute object

Synopsis:

#include <pthread.h>

int pthread_mutexattr_setrobust( pthread_mutexattr_t *attr,
                                 int robust );

Arguments:

attr
A pointer to the pthread_mutexattr_t object whose attribute you want to set.
robust
The value for the attribute; one of:
  • PTHREAD_MUTEX_STALLED
  • PTHREAD_MUTEX_ROBUST

For more information, see below.

Library:

libc

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

Description:

The pthread_mutexattr_setrobust() function sets the robust attribute in the mutex attribute object attr:

PTHREAD_MUTEX_STALLED
No special actions are taken if the owner of the mutex is terminated while holding the mutex lock. This can lead to deadlocks if no other thread can unlock the mutex. This is the default value.
PTHREAD_MUTEX_ROBUST
If the process containing the owning thread of a robust mutex terminates while holding the mutex lock, the next thread that acquires the mutex is notified about the termination by the return value EOWNERDEAD from the locking function.

The notified thread can then attempt to mark the state protected by the mutex as consistent again by a call to pthread_mutex_consistent(). After a subsequent successful call to pthread_mutex_unlock(), the mutex lock is released and can be used normally by other threads.

If the mutex is unlocked without a call to pthread_mutex_consistent(), it remains in a permanently unusable state and all attempts to lock the mutex fail with the error ENOTRECOVERABLE. The only permissible operation on such a mutex is pthread_mutex_destroy().

You can use pthread_mutexattr_getrobust() to get the value of this attribute. The behavior of a mutex also depends on its type; see pthread_mutexattr_settype().

Note:
  • You can't use a robust mutex with SyncMutexEvent(). The two mechanisms achieve the same goal in different ways.
  • Robust mutexes, mutexes with priority ceilings, and those using SyncMutexEvent() use more system resources than other mutexes.

Returns:

EOK
Success.
EINVAL
The value specified by robust is invalid.

Classification:

POSIX 1003.1

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