|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | CANCELLATION | ASYNC-SIGNAL SAFETY | RETURN VALUE | ERRORS | SEE ALSO | EXAMPLE | COLOPHON |
|
|
|
pthread_mutex_init(3) Library Functions Manual pthread_mutex_init(3)
pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
pthread_mutex_unlock, pthread_mutex_destroy - operations on
mutexes
#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);
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 different 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 according 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 checking". 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 unlocked, 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 "recursive" 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 before 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 error 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_mutex_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_mutex_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 LinuxThreads implementation, no resources are associated
with mutex objects, thus pthread_mutex_destroy() actually does
nothing except checking that the mutex is unlocked.
None of the mutex functions is a cancelation point, not even
pthread_mutex_lock(), in spite of the fact that it can suspend a
thread for arbitrary 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 mutex for extended
periods of time.
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.
pthread_mutex_init() always returns 0. The other mutex functions
return 0 on success and a non-zero error code on error.
The pthread_mutex_lock() function returns the following error code
on error:
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
checking" mutexes only).
The pthread_mutex_destroy() function returns the following error
code on error:
EBUSY The mutex is currently locked.
pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3),
pthread_cancel(3).
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);
This page is part of the man-pages (Linux kernel and C library
user-space interface documentation) project. Information about
the project can be found at
⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report
for this manual page, see
⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
This page was obtained from the tarball man-pages-6.15.tar.gz
fetched from
⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
2025-08-11. If you discover any rendering problems in this HTML
version of the page, or you believe there is a better or more up-
to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not
part of the original manual page), send a mail to
[email protected]
Linux man-pages 6.15 2025-05-17 pthread_mutex_init(3)
Pages that refer to this page: pthread_cond_init(3), pthread_mutexattr_init(3), pthread_mutexattr_setrobust(3), pthread_mutex_consistent(3), pthread_spin_init(3), pthreads(7), signal-safety(7)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|