pthread_mutex_lock(3P)

NAME
     pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
     pthread_mutex_unlock, pthread_mutex_destroy - mutual exclusion locks

C SYNOPSIS
     #include <pthread.h>

     int pthread_mutex_init(pthread_mutex_t *mutex,
          const pthread_mutexattr_t *attr);

     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
     Mutual exclusion locks (mutexes) are used to serialize the execution of
     threads through critical sections of code which access shared data.  A
     successful call for a mutex lock via pthread_mutex_lock() or
     pthread_mutex_trylock() will cause another thread that tries to acquire
     the same mutex via pthread_mutex_lock() to block until the owning thread
     calls pthread_mutex_unlock().

   Initialize
     Mutexes may be initialized either dynamically, by calling
     pthread_mutex_init(), or statically, via the macro
     PTHREAD_MUTEX_INITIALIZER.

     The personality of the mutex is determined by the attribute structure
     attr passed with the call to pthread_mutex_init().  These attributes are
     set by calls to pthread_mutexattr_init() and the various pthread mutex
     attribute functions.  If attr is null (or the mutex is statically
     initialized), the default attributes are used.

   Lock and Unlock
     A mutex lock protects shared data from simultaneous access by multiple
     threads.  A thread that calls pthread_mutex_lock() will block until it
     can gain exclusive ownership of a mutex, and retains ownership until it
     calls pthread_mutex_unlock().  Only the thread that locked a mutex should
     unlock it.  When unlocked, if there are any threads waiting for the mutex
     the relative priorities of the blocked threads and the scheduling policy
     determines which thread next acquires the mutex.

     If a thread waiting for a mutex receives a signal, upon return from the
     signal handler, the thread resumes waiting for the mutex as if there was
     no interrupt.
   Destroy
     The routine pthread_mutex_destroy() uninitializes the mutex object
     referenced by mutex.

DIAGNOSTICS
     All of the mutex functions return zero if successful; otherwise, an error
     number is returned.

     pthread_mutex_lock() can return the following errors:

     [EDEADLK]      The current thread already owns the mutex. The mutex type
                    must be PTHREAD_MUTEX_ERRORCHECK.

     [EINVAL]       The mutex was initialized as type PTHREAD_PRIO_PROTECT and
                    the calling thread's priority was greater than the mutex's
                    priority ceiling.

     pthread_mutex_trylock() can return the following errors:

     [EBUSY]        The mutex is currently held by another thread.

     [EINVAL]       The mutex was initialized as type PTHREAD_PRIO_PROTECT and
                    the calling thread's priority was greater than the mutex's
                    priority ceiling.

     pthread_mutex_unlock() can return the following error:

     [EPERM]        The current thread does not own the mutex.  The mutex type
                    must be PTHREAD_MUTEX_ERRORCHECK or
                    PTHREAD_MUTEX_RECURSIVE.

     pthread_mutex_destroy() can return the following error:

     [EBUSY]        The mutex is currently held by any thread.

SEE ALSO
     pthread_cond_init(3P), pthread_mutexattr_init(3P),
     pthread_mutexattr_setprioceiling(3P), pthread_mutexattr_setprotocol(3P),
     pthread_mutexattr_setpshared(3P), pthread_mutexattr_settype(3P).