pthread_mutex_lock(3T)         DG/UX R4.11MU05        pthread_mutex_lock(3T)


NAME
       pthread_mutex_lock, pthread_mutex_unlock, pthread_mutex_trylock -
       lock or unlock a mutex

SYNOPSIS
       #include <pthread.h>

       int pthread_mutex_lock(pthread_mutex_t *mutex);

       int pthread_mutex_trylock(pthread_mutex_t *mutex);

       int pthread_mutex_unlock(pthread_mutex_t *mutex);

   where:
       mutex  A pointer to a mutex

DESCRIPTION
       The pthread_mutex_lock() function locks the mutex pointed to by
       mutex.  If the mutex is already locked, the calling thread blocks
       until the mutex becomes available.  This operation returns with the
       mutex pointed to by mutex in the locked state with the calling thread
       as its owner.  An attempt by the current owner of a mutex to relock
       the mutex results in undefined behavior; on a DG/UX system, it
       results in a deadlock.

       The pthread_mutex_trylock() function is identical to
       pthread_mutex_lock() except that if the mutex is currently locked by
       any thread, including itself, the call returns immediately with
       EBUSY.

       The pthread_mutex_unlock() function is called by the owner of the
       mutex to release it.  A pthread_mutex_unlock() call by a thread that
       is not the owner of the mutex or when the mutex is unlocked results
       in undefined behavior; DG/UX attempts to detect these problems and
       causes the call to fail with EINVAL.

       If there are threads blocked on the mutex object referenced by mutex
       when pthread_mutex_unlock() is called, the scheduling policy is used
       to determine which thread shall acquire the mutex.  In general, the
       highest priority thread will be scheduled first to acquire the mutex.
       However, on a multiprocessor system, guarantees cannot be made as to
       which thread will acquire the mutex first.

DIAGNOSTICS
   Returns
       If successful, these functions return 0.  Otherwise they return -1
       and set errno to indicate the error.

   Errors
       For each of the following conditions, pthread_mutex_lock(),
       pthread_mutex_trylock(), and pthread_mutex_unlock() return -1 and set
       errno to the corresponding value:

       [EINVAL]  The value pointed to by mutex does not refer to an properly
                 initialized mutex object.

       For each of the following conditions, pthread_mutex_trylock() returns
       -1 and sets errno to the corresponding value:

       [EBUSY]   The mutex could not be acquired because it was already
                 locked.

       For each of the following conditions, pthread_mutex_unlock() returns
       -1 and sets errno to the corresponding value:

       [EINVAL]  The mutex is not currently locked by any thread.

       [EINVAL]  The current thread is not the owner of the mutex.

SEE ALSO
       pthread_mutex_init(3T), pthread_mutex_destroy(3T),
       pthread_mutexattr_init(3T), pthread_mutexattr_setpshared(3T),
       pthread_cond_wait(3T), threads(5).

NOTES
       Mutexes can be used as the basis of higher-level locking primitives,
       such as recursive locks, reader/writer locks, and ordered locks.
       Typically, mutexes are used in conjunction with condition variables
       to implement these and other synchronization primitives.

       There have been many bugs hidden by the failure to check for error
       returns from these functions.  It is recommended that applications
       check the return statuses of all pthread calls, but particularly of
       these.  Consider the use of icing macros around such calls as a means
       of facilitating the checking of return codes, while keeping the code
       easy to read.

       There are very few cases where mutexes are not needed to guard
       shared, writable data.  For maximum portability, always guard shared,
       writable data with a mutex.

       The above functions are not cancellation (interruption) points.  If
       they were, then any function that uses mutexes would be a
       cancellation point.  Because so many functions use mutexes, the
       concept of the cancellation point would be rendered useless.

       Whenever possible, DG/UX attempts to defer a timeslice preemption
       that occurs while holding a mutex until either the mutex is released
       or an overtime period expires.  This helps cut down on contention for
       the mutexes that occurs due to inopportune preemption.

       Calls to pthread_mutex_trylock() are async-safe, that is, they can be
       safely called out of signal handlers executed asynchronously by the
       calling thread.  The only other standard Pthread functions that are
       async-safe are pthread_cond_signal() and pthread_cond_broadcast().


Licensed material--property of copyright holder(s)