PTHREAD_MUTEXATTR(3)

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 kind); int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *kind);

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_destroy! does nothing in the LinuxThreads implementation. LinuxThreads supports only one mutex attribute: the mutex kind, which is either !PTHREAD_MUTEX_FAST_NP! for ``fast'' mutexes, !PTHREAD_MUTEX_RECURSIVE_NP! for ``recursive'' mutexes, or !PTHREAD_MUTEX_ERRORCHECK_NP! for ``error checking'' mutexes. As the !NP! suffix indicates, this is a non-portable extension to the POSIX standard and should not be employed in portable programs. The mutex kind 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 ``fast'' kind, !pthread_mutex_lock!(3) simply suspends the calling thread forever. If the mutex is of the ``error checking'' kind, !pthread_mutex_lock!(3) returns immediately with the error code !EDEADLK!. If the mutex is of the ``recursive'' kind, 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 kind is ``fast'', that is, !PTHREAD_MUTEX_FAST_NP!. !pthread_mutexattr_settype! sets the mutex kind attribute in |attr| to the value specified by |kind|. !pthread_mutexattr_gettype! retrieves the current value of the mutex kind attribute in |attr| and stores it in the location pointed to by |kind|.

RETURN VALUE
!pthread_mutexattr_init!, !pthread_mutexattr_destroy! and !pthread_mutexattr_gettype! always return 0. !pthread_mutexattr_settype! returns 0 on success and a non-zero error code on error.

ERRORS
On error, !pthread_mutexattr_settype! returns the following error code:

!EINVAL!
    |kind| is neither !PTHREAD_MUTEX_FAST_NP! nor !PTHREAD_MUTEX_RECURSIVE_NP! nor !PTHREAD_MUTEX_ERRORCHECK_NP!

AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>

SEE ALSO
!pthread_mutex_init!(3), !pthread_mutex_lock!(3), !pthread_mutex_unlock!(3).