pthread_mutexattr_getrobust

, pthread_mutexattr_setrobust

- get and set the mutex robust attribute

Synopsis

cc –mt [ flag... ] file... [ library... ]
#include <pthread.h>

int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr,
     int *robust);

int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,
     int robust);

Description

The pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() functions, respectively, get and set the mutex robust attribute. This attribute is set in the robust parameter. Valid values for robust include:

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 because no other thread can unlock the mutex. This is the default value.

PTHREAD_MUTEX_ROBUST

If the owning thread of a robust mutex terminates while holding the mutex lock, or if the process containing the owning thread of a robust mutex terminates, either normally or abnormally, or if the process containing the owner of the mutex unmaps the memory containing the mutex or performs one of the exec(2) functions, the next thread that acquires the mutex will be notified by the return value EOWNERDEAD from the locking function.

The notified thread can then attempt to recover the state protected by the mutex and, if successful, mark the state as consistent again by a call to pthread_mutex_consistent(). After a subsequent successful call to pthread_mutex_unlock(3C), the mutex lock will be released and can be used normally by other threads. If the mutex is unlocked without a call to pthread_mutex_consistent(), it will be in a permanently unusable state and all attempts to lock the mutex will fail with the error ENOTRECOVERABLE. The only permissible operation on such a mutex is pthread_mutex_destroy(3C).

The actions required to make the state protected by the mutex consistent are solely dependent on the application. Calling pthread_mutex_consistent(3C) does not, by itself, make the state protected by the mutex consistent.

The behavior is undefined if the value specified by the attr argument to pthread_mutexattr_getrobust() or pthread_mutexattr_setrobust() does not refer to an initialized mutex attributes object.

Return Values

Upon successful completion, the pthread_mutexattr_getrobust() function returns 0 and stores the value of the robust attribute of attr into the object referenced by the robust parameter. Otherwise, an error value is returned to indicate the error.

Upon successful completion, the pthread_mutexattr_setrobust() function returns 0. Otherwise, an error value is returned to indicate the error.

Errors

The pthread_mutexattr_setrobust() function will fail if:

EINVAL

The value of robust is invalid.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

exec(2), pthread_mutex_consistent(3C), pthread_mutex_destroy(3C), pthread_mutex_init(3C), pthread_mutex_lock(3C), pthread_mutex_unlock(3C), pthread_mutexattr_getpshared(3C), pthread_mutexattr_init(3C), attributes(5), mutex(5), standards(5)

Notes

The mutex memory must be zeroed before first initialization of a mutex with the PTHREAD_MUTEX_ROBUST attribute. Any thread in any process interested in the robust lock can call pthread_mutex_init() to potentially initialize it, provided that all such callers of pthread_mutex_init() specify the same set of attributes in their attribute structures. In this situation, if pthread_mutex_init() is called on a previously initialized robust mutex, it will not reinitialize the mutex and will return the error value EBUSY. If pthread_mutex_init() is called on a previously initialized robust mutex, and if the caller specifies a different set of attributes from those already in effect for the mutex, it will not reinitialize the mutex and will return the error value EINVAL.