pthread_mutex_init(3) Library Functions Manual pthread_mutex_init(3)
NAME
pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
pthread_mutex_unlock, pthread_mutex_destroy - operations on mutexes
SYNOPSIS
#include <pthread.h>
pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;
pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;
int pthread_mutex_init(pthread_mutex_t *mutex,
const pthread_mutexattr_t *mutexattr);
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
A mutex is a MUTual EXclusion device, and is useful for protecting
shared data structures from concurrent modifications, and implementing
critical sections and monitors.
A mutex has two possible states: unlocked (not owned by any thread), and
locked (owned by one thread). A mutex can never be owned by two differ-
ent threads simultaneously. A thread attempting to lock a mutex that is
already locked by another thread is suspended until the owning thread
unlocks the mutex first.
pthread_mutex_init initializes the mutex object pointed to by mutex ac-
cording to the mutex attributes specified in mutexattr. If mutexattr is
NULL, default attributes are used instead.
The LinuxThreads implementation supports only one mutex attributes, the
mutex kind, which is either ``fast'', ``recursive'', or ``error check-
ing''. The kind of a mutex determines whether it can be locked again by
a thread that already owns it. The default kind is ``fast''. See
pthread_mutexattr_init(3) for more information on mutex attributes.
Variables of type pthread_mutex_t can also be initialized statically,
using the constants PTHREAD_MUTEX_INITIALIZER (for fast mutexes),
PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP (for recursive mutexes), and
PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP (for error checking mutexes).
pthread_mutex_lock locks the given mutex. If the mutex is currently un-
locked, it becomes locked and owned by the calling thread, and
pthread_mutex_lock returns immediately. If the mutex is already locked
by another thread, pthread_mutex_lock suspends the calling thread until
the mutex is unlocked.
If the mutex is already locked by the calling thread, the behavior of
pthread_mutex_lock depends on the kind of the mutex. If the mutex is of
the ``fast'' kind, the calling thread is suspended until the mutex is
unlocked, thus effectively causing the calling thread to deadlock. If
the mutex is of the ``error checking'' kind, pthread_mutex_lock returns
immediately with the error code EDEADLK. If the mutex is of the ``re-
cursive'' kind, pthread_mutex_lock succeeds and returns immediately,
recording the number of times the calling thread has locked the mutex.
An equal number of pthread_mutex_unlock operations must be performed be-
fore the mutex returns to the unlocked state.
pthread_mutex_trylock behaves identically to pthread_mutex_lock, except
that it does not block the calling thread if the mutex is already locked
by another thread (or by the calling thread in the case of a ``fast''
mutex). Instead, pthread_mutex_trylock returns immediately with the er-
ror code EBUSY.
pthread_mutex_unlock unlocks the given mutex. The mutex is assumed to
be locked and owned by the calling thread on entrance to pthread_mu-
tex_unlock. If the mutex is of the ``fast'' kind, pthread_mutex_unlock
always returns it to the unlocked state. If it is of the ``recursive''
kind, it decrements the locking count of the mutex (number of
pthread_mutex_lock operations performed on it by the calling thread),
and only when this count reaches zero is the mutex actually unlocked.
On ``error checking'' and ``recursive'' mutexes, pthread_mutex_unlock
actually checks at run-time that the mutex is locked on entrance, and
that it was locked by the same thread that is now calling pthread_mu-
tex_unlock. If these conditions are not met, an error code is returned
and the mutex remains unchanged. ``Fast'' mutexes perform no such
checks, thus allowing a locked mutex to be unlocked by a thread other
than its owner. This is non-portable behavior and must not be relied
upon.
pthread_mutex_destroy destroys a mutex object, freeing the resources it
might hold. The mutex must be unlocked on entrance. In the Linux-
Threads implementation, no resources are associated with mutex objects,
thus pthread_mutex_destroy actually does nothing except checking that
the mutex is unlocked.
CANCELLATION
None of the mutex functions is a cancelation point, not even pthread_mu-
tex_lock, in spite of the fact that it can suspend a thread for arbi-
trary durations. This way, the status of mutexes at cancelation points
is predictable, allowing cancelation handlers to unlock precisely those
mutexes that need to be unlocked before the thread stops executing.
Consequently, threads using deferred cancelation should never hold a mu-
tex for extended periods of time.
ASYNC-SIGNAL SAFETY
The mutex functions are not async-signal safe. What this means is that
they should not be called from a signal handler. In particular, calling
pthread_mutex_lock or pthread_mutex_unlock from a signal handler may
deadlock the calling thread.
RETURN VALUE
pthread_mutex_init always returns 0. The other mutex functions return 0
on success and a non-zero error code on error.
ERRORS
The pthread_mutex_lock function returns the following error code on er-
ror:
EINVAL The mutex has not been properly initialized.
EDEADLK
The mutex is already locked by the calling thread (``error
checking'' mutexes only).
The pthread_mutex_trylock function returns the following error codes on
error:
EBUSY The mutex could not be acquired because it was currently
locked.
EINVAL The mutex has not been properly initialized.
The pthread_mutex_unlock function returns the following error code on
error:
EINVAL The mutex has not been properly initialized.
EPERM The calling thread does not own the mutex (``error check-
ing'' mutexes only).
The pthread_mutex_destroy function returns the following error code on
error:
EBUSY The mutex is currently locked.
SEE ALSO
pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3), pthread_can-
cel(3).
EXAMPLE
A shared global variable x can be protected by a mutex as follows:
int x;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
All accesses and modifications to x should be bracketed by calls to
pthread_mutex_lock and pthread_mutex_unlock as follows:
pthread_mutex_lock(&mut);
/* operate on x */
pthread_mutex_unlock(&mut);
Linux man-pages 6.9.1 2024-06-16 pthread_mutex_init(3)
Generated by dwww version 1.16 on Tue Dec 16 03:57:42 CET 2025.