PTHREAD_MUTEXATTR(3) manual page

#### POSIX Threads for Windows – REFERENCE - Pthreads-w32

Reference Index

Table of Contents

## Name

pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation attributes

## Synopsis

#include <pthread.h>

int pthread_mutexattr_init(pthread_mutexattr_t *attr);

int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type);

int pthread_mutexattr_setkind_np(pthread_mutexattr_t *attr, int type);

int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *attr, int *type);

int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr, int robust);

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

## Description

Mutex attributes can be specified at mutex creation time, by passing a mutex attribute object as second argument to pthread_mutex_init(3) . Passing NULL is equivalent to passing a mutex attribute object with all attributes set to their default values.

pthread_mutexattr_init initializes the mutex attribute object attr and fills it with default values for the attributes.

pthread_mutexattr_destroy destroys a mutex attribute object, which must not be reused until it is reinitialized.

pthread_mutexattr_settype sets the mutex type attribute in attr to the value specified by type.

pthread_mutexattr_gettype retrieves the current value of the mutex kind attribute in attr and stores it in the location pointed to by type.

Pthreads-w32 also recognises the following equivalent functions that are used in Linux:

pthread_mutexattr_setkind_np is an alias for pthread_mutexattr_settype.

pthread_mutexattr_getkind_np is an alias for pthread_mutexattr_gettype.

The following mutex types are supported:

PTHREAD_MUTEX_NORMAL - for ‘‘fast’’ mutexes.

PTHREAD_MUTEX_RECURSIVE - for ‘‘recursive’’ mutexes.

PTHREAD_MUTEX_ERRORCHECK - for ‘‘error checking’’ mutexes.

The mutex type determines what happens if a thread attempts to lock a mutex it already owns with pthread_mutex_lock(3) . If the mutex is of the “normal” or “fast” type, pthread_mutex_lock(3) simply suspends the calling thread forever. If the mutex is of the ‘‘error checking’’ type, pthread_mutex_lock(3) returns immediately with the error code EDEADLK. If the mutex is of the ‘‘recursive’’ type, the call to pthread_mutex_lock(3) returns immediately with a success return code. The number of times the thread owning the mutex has locked it is recorded in the mutex. The owning thread must call pthread_mutex_unlock(3) the same number of times before the mutex returns to the unlocked state.

The default mutex type is PTHREAD_MUTEX_NORMAL

Pthreads-w32 also recognises the following equivalent types that are used by Linux:

PTHREAD_MUTEX_FAST_NP – equivalent to PTHREAD_MUTEX_NORMAL

PTHREAD_MUTEX_RECURSIVE_NP

PTHREAD_MUTEX_ERRORCHECK_NP

pthread_mutexattr_setrobust sets the robustness attribute to the value given by robust.

pthread_mutexattr_getrobust returns the current robustness value to the location given by *robust.

The possible values for robust are:

PTHREAD_MUTEX_STALLED - when the owner of the mutex terminates without unlocking the mutex, all subsequent calls to pthread_mutex_*lock() are blocked from progress in an unspecified manner.

PTHREAD_MUTEX_ROBUST - when the owner of the mutex terminates without unlocking the mutex, the mutex is unlocked. The next owner of this mutex acquires the mutex with an error return of EOWNERDEAD.

## Return Value

On success all functions return 0, otherwise they return an error code as follows:

pthread_mutexattr_init

ENOMEM - insufficient memory for attr.

pthread_mutexattr_destroy

EINVAL - attr is invalid.

pthread_mutexattr_gettype

EINVAL - attr is invalid.

pthread_mutexattr_settype

EINVAL - attr is invalid or type is none of:

PTHREAD_MUTEX_NORMAL
PTHREAD_MUTEX_FAST_NP
PTHREAD_MUTEX_RECURSIVE
PTHREAD_MUTEX_RECURSIVE_NP
PTHREAD_MUTEX_ERRORCHECK
PTHREAD_MUTEX_ERRORCHECK_NP

pthread_mutexattr_getrobust

EINVAL – attr or robust is invalid.

pthread_mutexattr_setrobust

EINVAL – attr or robust is invalid.

## Author

Xavier Leroy <Xavier.Leroy@inria.fr>

Modified by Ross Johnson for use with Pthreads-w32.

## See Also

pthread_mutex_init(3) , pthread_mutex_lock(3) , pthread_mutex_unlock(3) .

## Notes

For speed, Pthreads-w32 never checks the thread ownership of non-robust mutexes of type PTHREAD_MUTEX_NORMAL (or PTHREAD_MUTEX_FAST_NP) when performing operations on the mutex. It is therefore possible for one thread to lock such a mutex and another to unlock it.

When developing code, it is a common precaution to substitute the error checking type, then drop in the normal type for release if the extra performance is required.

Table of Contents

- Name

- Synopsis

- Description

- Return Value

- Author

- See Also

- Notes