pthread_mutexattr_settype(3P)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
Page 1
pthread_mutexattr_settype(3P)pthread_mutexattr_settype(3P)
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 ALSOpthread_mutex_lock(3P), pthread_mutexattr_init(3P),
pthread_mutexattr_setprotocol(3P).
Page 2
