ABCDEFGHIJKLMNOPQRSTUVWXYZ

pthread_mutex_lock

PTHREAD_MUTEX(3)                                              PTHREAD_MUTEX(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_mutex-
       attr_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  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
       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  immedi-
       ately,  recording the number of times the calling thread has locked the
       mutex. An equal number of pthread_mutex_unlock operations must be  per-
       formed 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'' 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.


CANCELLATION
       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  cancella-
       tion  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.


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 check-
                     ing'' mutexes only).

       The pthread_mutex_destroy function returns the following error code  on
       error:

              EBUSY  the mutex is currently locked.


AUTHOR
       Xavier Leroy <Xavier.Leroy@inria.fr>


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






                                 LinuxThreads                 PTHREAD_MUTEX(3)