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

       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

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

       pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3), pthread_cancel(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)