pthread_mutex_init(3) — Linux manual page

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)

NAME         top

       pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
       pthread_mutex_unlock, pthread_mutex_destroy - operations on
       mutexes

SYNOPSIS         top

       #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         top

       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.

CANCELLATION         top

       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.

ASYNC-SIGNAL SAFETY         top

       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         top

       pthread_mutex_init always returns 0.  The other mutex functions
       return 0 on success and a non-zero error code on error.

ERRORS         top

       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.

SEE ALSO         top

       pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3),
       pthread_cancel(3).

EXAMPLE         top

       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);

COLOPHON         top

       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.9.1.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2024-06-26.  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.9.1          2024-06-16          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(7)signal-safety(7)