pthread_mutex_lock(3P)pthread_mutex_lock(3P)NAME
pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
pthread_mutex_unlock, pthread_mutex_destroy - mutual exclusion locks
C SYNOPSIS
#include <pthread.h>
int pthread_mutex_init(pthread_mutex_t *mutex,
const pthread_mutexattr_t *attr);
int pthread_mutex_lock(pthread_mutex_t *mutex);
int pthread_mutex_trylock(pthread_mutex_t *mutex);
int pthread_mutex_unlock(pthread_mutex_t *mutex);
int pthread_mutex_destroy(pthread_mutex_t *mutex);
DESCRIPTION
Mutual exclusion locks (mutexes) are used to serialize the execution of
threads through critical sections of code which access shared data. A
successful call for a mutex lock via pthread_mutex_lock() or
pthread_mutex_trylock() will cause another thread that tries to acquire
the same mutex via pthread_mutex_lock() to wait until the owning thread
calls pthread_mutex_unlock(). The wait could mean that the thread is
blocked immediately or if the mutex type is PTHREAD_MUTEX_SPINBLOCK_NP,
the thread will spin first then block.
Initialize
Mutexes may be initialized either dynamically, by calling
pthread_mutex_init(), or statically, via the macro
PTHREAD_MUTEX_INITIALIZER.
The personality of the mutex is determined by the attribute structure
attr passed with the call to pthread_mutex_init(). These attributes are
set by calls to pthread_mutexattr_init() and the various pthread mutex
attribute functions. If attr is null (or the mutex is statically
initialized), the default attributes are used.
Lock and Unlock
A mutex lock protects shared data from simultaneous access by multiple
threads. A thread that calls pthread_mutex_lock() will wait until it can
gain exclusive ownership of a mutex, and retains ownership until it calls
pthread_mutex_unlock(). Only the thread that locked a mutex should
unlock it. When the mutex is unlocked, if there are any threads waiting
for the mutex the relative priorities of the blocked threads and the
scheduling policy determines which thread next acquires the mutex. When
a thread unlocks a PTHREAD_MUTEX_SPINBLOCK_NP type of mutex, it issues an
unblock if there are waiters for the lock. However, 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.
Page 1
pthread_mutex_lock(3P)pthread_mutex_lock(3P)
If a thread waiting for a mutex receives a signal, upon return from the
signal handler, the thread resumes waiting for the mutex as if there was
no interrupt.
Destroy
The routine pthread_mutex_destroy() uninitializes the mutex object
referenced by mutex.
DIAGNOSTICS
All of the mutex functions return zero if successful; otherwise, an error
number is returned.
pthread_mutex_lock() can return the following errors:
[EDEADLK] The current thread already owns the mutex. The mutex type
must be PTHREAD_MUTEX_ERRORCHECK.
[EINVAL] The mutex was initialized as type PTHREAD_PRIO_PROTECT and
the calling thread's priority was greater than the mutex's
priority ceiling.
[EOVERFLOW] The mutex was initialized as type PTHREAD_PRIO_THREAD_NP
or PTHREAD_PRIO_SYSTEM_NP and 255 of that type of mutex
were already locked by the calling pthread.
pthread_mutex_trylock() can return the following errors:
[EBUSY] The mutex is currently held by another thread.
[EINVAL] The mutex was initialized as type PTHREAD_PRIO_PROTECT and
the calling thread's priority was greater than the mutex's
priority ceiling.
[EOVERFLOW] The mutex was initialized as type PTHREAD_PRIO_THREAD_NP
or PTHREAD_PRIO_SYSTEM_NP and 255 of that type of mutex
were already locked by the calling pthread.
pthread_mutex_unlock() can return the following error:
[EPERM] The current thread does not own the mutex. The mutex type
must be PTHREAD_MUTEX_ERRORCHECK or
PTHREAD_MUTEX_RECURSIVE.
pthread_mutex_destroy() can return the following error:
[EBUSY] The mutex is currently held by any thread.
SEE ALSOpthread_cond_init(3P), pthread_mutexattr_init(3P),
pthread_mutexattr_setprioceiling(3P), pthread_mutexattr_setprotocol(3P),
pthread_mutexattr_setpshared(3P), pthread_mutexattr_settype(3P).
Page 2
