Return Values

On successful completion, pthread_mutexattr_setrobust_np() returns 0. Any other return value indicates that an error occurred.

If any of the following conditions occurs, pthread_mutexattr_setrobust_np() fails and returns the corresponding value.

ENOSYS

The option _POSIX_THREAD_PRIO__INHERIT is not defined or the implementation does not support pthread_mutexattr_setrobust_np().

ENOTSUP

The value specified by robustness is not supported.

pthread_mutexattr_setrobust_np() might fail if:

EINVAL

The value specified by attr or robustness is invalid.

Get Mutex's Robust Attribute

pthread_mutexattr_getrobust_np(3THR)

pthread_mutexattr_getrobust_np(3THR) gets the robust attribute of a mutex attribute object.

#include <pthread.h>

int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr, 
												int *robustness);

Note - pthread_mutexattr_getrobust_np() applies only if the symbol _POSIX_THREAD_PRIO_INHERIT is defined.

attr points to the mutex attribute object previously created by a call to pthread_mutexattr_init().

robustness is the value of the robust attribute of a mutex attribute object.

Return Values

On successful completion, pthread_mutexattr_getrobust_np() returns 0. Any other return value indicates that an error occurred.

If any of the following conditions occurs, pthread_mutexattr_getrobust_np() fails and returns the corresponding value.

ENOSYS

The option _POSIX_THREAD_PRIO__INHERIT is not defined or the implementation does not support pthread_mutexattr_getrobust_np().

pthread_mutexattr_getrobust_np() might fail if:

EINVAL

The value specified by attr or robustness is invalid.

Using Mutual Exclusion Locks

Table 4-3 lists the functions discussed in this chapter that manipulate mutex locks.

Table 4-3 Routines for Mutual Exclusion Locks

The default scheduling policy, SCHED_OTHER, does not specify the order in which threads can acquire a lock. When multiple threads are waiting for a mutex, the order of acquisition is undefined. When there is contention, the default behavior is to unblock threads in priority order.

Initialize a Mutex

pthread_mutex_init(3THR)

Use pthread_mutex_init(3THR) to initialize the mutex pointed at by mp to its default value (mattr is NULL), or to specify mutex attributes that have already been set with pthread_mutexattr_init(). (For Solaris threads, see "mutex_init(3THR)".)

Prototype:
int	pthread_mutex_init(pthread_mutex_t *mp,
    const pthread_mutexattr_t *mattr);

#include <pthread.h>

pthread_mutex_t mp = PTHREAD_MUTEX_INITIALIZER;
pthread_mutexattr_t mattr;
int ret;

/* initialize a mutex to its default value */
ret = pthread_mutex_init(&mp, NULL);

/* initialize a mutex */
ret = pthread_mutex_init(&mp, &mattr); 

When the mutex is initialized, it is in an unlocked state. The mutex can be in memory shared between processes or in memory private to a process.

Note - The mutex memory must be cleared to zero before initialization.

The effect of mattr being NULL is the same as passing the address of a default mutex attribute object, but without the memory overhead.

Statically defined mutexes can be initialized directly to have default attributes with the macro PTHREAD_MUTEX_INITIALIZER.

A mutex lock must not be reinitialized or destroyed while other threads might be using it. Program failure will result if either action is not done correctly. If a mutex is reinitialized or destroyed, the application must be sure the mutex is not currently in use.

Return Values

pthread_mutex_init() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EBUSY

The implementation has detected an attempt to reinitialize the object referenced by mp (a previously initialized, but not yet destroyed mutex).

EINVAL

The mattr attribute value is invalid. The mutex has not been modified.

EFAULT

The address for the mutex pointed at by mp is invalid.

Make Mutex Consistent

pthread_mutex_consistent_np(3THR)

#include <pthread.h>
int	pthread_mutex_consistent_np(pthread_mutex_t *mutex); 

Note - pthread_mutex_consistent_np() applies only if the symbol _POSIX_THREAD_PRIO_INHERIT is defined and for mutexes that are initialized with the protocol attribute value PTHREAD_PRIO_INHERIT.

If the owner of a mutex dies, the mutex can become inconsistent.

pthread_mutex_consistent_np makes the mutex object, mutex, consistent after the death of its owner.

Call pthread_mutex_lock() to acquire the inconsistent mutex. The EOWNWERDEAD return value indicates an inconsistent mutex.

Call pthread_mutex_consistent_np() while holding the mutex acquired by a previous call to pthread_mutex_lock().

Because the critical section protected by the mutex might have been left in an inconsistent state by the dead owner, make the mutex consistent only if you are able to make the critical section protected by the mutex consistent.

Calls to pthread_mutex_lock(), pthread_mutex_unlock(), and pthread_mutex_trylock() for a consistent mutex behave in the normal manner.

The behavior of pthread_mutex_consistent_np() for a mutex that is not inconsistent, or that is not held, is undefined.

Return Values

pthread_mutex_consistent_np() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

pthread_mutex_consistent_np() fails if:

ENOSYS

The option _POSIX_THREAD_PRIO_INHERIT is not defined or the implementation does not support pthread_mutex_consistent_np().

pthread_mutex_consistent_np() might fail if:

EINVAL

The value specified by mutex is invalid.

Lock a Mutex

pthread_mutex_lock(3THR)

Prototype:
int	pthread_mutex_lock(pthread_mutex_t *mutex); 

#include <pthread.h>

pthread_mutex_t mutex;
int ret;

ret = pthread_ mutex_lock(&mp); /* acquire the mutex */

Use pthread_mutex_lock(3THR) to lock the mutex pointed to by mutex. When pthread_mutex_lock() returns, the mutex is locked and the calling thread is the owner. If the mutex is already locked and owned by another thread, the calling thread blocks until the mutex becomes available. (For Solaris threads, see "mutex_lock(3THR)".)

If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection is not provided. Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it has not locked or a mutex that is unlocked, undefined behavior results.

If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking is provided. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex that it has not locked or a mutex that is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex maintains the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count is set to one. Every time a thread relocks this mutex, the lock count is incremented by one. Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock count reaches zero, the mutex becomes available for other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error will be returned.

If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in undefined behavior.