PTHREAD_MUTEXATTR_INIT(3) manual page

#### POSIX Threads for Windows â€“ REFERENCE - Pthreads4W

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.

PThreads4W 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

PThreads4W 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 Pthreads4W.

## See Also

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

## Notes

For speed, PThreads4W 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