pthread_mutexattr_settype(3P)

NAME
     pthread_mutexattr_settype, pthread_mutexattr_gettype - set/get a mutex
     attribute object's type

C SYNOPSIS
     #include <pthread.h>

     int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

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

DESCRIPTION
     These functions manipulate a mutex attribute object referenced by attr
     which has been previously created by pthread_mutexattr_init().

     The function pthread_mutexattr_settype() defines the type of mutex.  The
     type value may be one of PTHREAD_MUTEX_NORMAL, PTHREAD_MUTEX_ERRORCHECK,
     PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_SPINBLOCK_NP, or
     PTHREAD_MUTEX_DEFAULT.

     The function pthread_mutexattr_gettype() stores into the memory
     referenced by type the mutex type associated with the named mutex
     attribute object.  The default type is PTHREAD_MUTEX_DEFAULT.

     A mutex with a type attribute of PTHREAD_MUTEX_DEFAULT or
     PTHREAD_MUTEX_NORMAL works as a simple mutual exclusion lock with no
     error checking.  A thread attempting to relock a mutex of this type will
     deadlock.

     A mutex with a type attribute of PTHREAD_MUTEX_ERRORCHECK is a simple
     mutual exclusion lock with error checking.  A thread attempting to relock
     a mutex of this type will return an error.  A thread attempting to unlock
     a mutex that another thread has locked will return an error.  A thread
     attempting to unlock a mutex that has not been locked will return an
     error.

     A mutex with a type attribute of PTHREAD_MUTEX_RECURSIVE is a simple
     mutual exclusion lock with error checking that also allows a single
     thread to recursively lock the mutex.  In this case there must be a
     matching number of unlocks by the thread before the mutex can be
     released.  A thread attempting to unlock a mutex that another thread has
     locked will return an error.  A thread attempting to unlock a mutex that
     has not been locked will return an error.

     A mutex with a type attribute of PTHREAD_MUTEX_SPINBLOCK_NP is a mutual
     exclusion lock which spins for a configurable amount of time then blocks.
     The mutex continues to spin then block until the lock is obtained.  An
     environment variable is provided to tune this type of mutex. The
     environment variable MTX_SPINS is used to control the number of times the
     lock is tried before blocking.  The default value is set to 600. When a
     thread unlocks a spinblock mutex, it clears the lock word then issues an
     unblock if there are waiters for the lock. Once a blocked thread is
     awakened, it still needs to try to acquire the lock. Thread priority is
     therefore not preserved with this type of mutex. Also,
     pthread_mutexattr_setprioceiling() cannot be used with this type of
     mutex.

DIAGNOSTICS
     The mutex attribute type functions return zero on success; otherwise, an
     error number is returned:

     [EINVAL]       The value specified by type is invalid.

     [EINVAL]       The value specified by type is PTHREAD_MUTEX_SPINBLOCK_NP
                    and pthread_mutexattr_setprioceiling() has already been
                    called for the mutex.

SEE ALSO
     pthread_mutex_lock(3P), pthread_mutexattr_init(3P),
     pthread_mutexattr_setprotocol(3P).