Provided by: glibc-doc_2.10.1-0ubuntu15_all bug


       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

       On  ‘‘error checking’’ 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’’ and ‘‘recursive’’ 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  cancellation  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
       cancellation points is predictable, allowing cancellation  handlers  to
       unlock  precisely  those  mutexes  that  need to be unlocked before the
       thread  stops   executing.   Consequently,   threads   using   deferred
       cancellation 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

              EINVAL the mutex has not been properly initialized.

                     the  mutex  is  already  locked  by  the  calling  thread
                     (‘‘error checking’’ mutexes only).

       The pthread_mutex_trylock function returns the following error codes on

              EBUSY  the mutex could not be acquired because it was  currently

              EINVAL the mutex has not been properly initialized.

       The  pthread_mutex_unlock  function returns the following error code on

              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

              EBUSY  the mutex is currently locked.


       Xavier Leroy <>


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

              /* operate on x */

                                 LinuxThreads                 PTHREAD_MUTEX(3)