Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


PTHREAD_MUTEX(3)           Library Functions Manual           PTHREAD_MUTEX(3)

NAME
     pthread_mutex, pthread_mutex_init, pthread_mutex_destroy,
     pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock,
     pthread_mutex_timedlock, pthread_mutex_getprioceiling,
     pthread_mutex_setprioceiling - mutual exclusion primitives

LIBRARY
     POSIX Threads Library (libpthread, -lpthread)

SYNOPSIS
     #include <pthread.h>

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

     pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

     int
     pthread_mutex_destroy(pthread_mutex_t *mutex);

     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_timedlock(pthread_mutex_t *__restrict mutex,
         const struct timespec *__restrict timeout);

     int
     pthread_mutex_getprioceiling(const pthread_mutex_t * __restrict mutex,
         int * __restrict prioceiling);

     int
     pthread_mutex_setprioceiling(pthread_mutex_t * __restrict mutex,
         int prioceiling, int * __restrict old_ceiling);

DESCRIPTION
     The pthread_mutex_init() function creates a new mutex, with attributes
     specified with attr.  If attr is NULL, the default attributes are used.

     The macro PTHREAD_MUTEX_INITIALIZER can be used to initialize a mutex
     when the default attributes are appropriate and the mutex can be
     statically allocated.  The behavior is similar to pthread_mutex_init()
     with attr specified as NULL, except that no error checking is done.

     The pthread_mutex_destroy() function frees the resources allocated for
     mutex.  It is possible to reinitialize a destroyed mutex, but undefined
     behavior may follow if the destroyed object is otherwise referenced.

     The pthread_mutex_lock() function locks mutex.  If the mutex is already
     locked, the calling thread will block until the mutex becomes available.
     The error conditions may vary depending on the type of the mutex; see
     pthread_mutexattr(3) for additional details.

     The pthread_mutex_trylock() function locks mutex.  If the mutex is
     already locked, pthread_mutex_trylock() will not block waiting for the
     mutex, but will return an error condition.

     The pthread_mutex_unlock() function unlocks an acquired mutex.  When
     operating with the default mutex type, undefined behavior follows if a
     thread tries to unlock a mutex that has not been locked by it, or if a
     thread tries to release a mutex that is already unlocked.

     The pthread_mutex_timedlock() function shall lock the mutex object
     referenced by mutex.  If the mutex is already locked, the calling thread
     shall block until the mutex becomes available in the pthread_mutex_lock()
     function.  If the mutex cannot be locked without waiting for another
     thread to unlock the mutex, this wait shall be terminated when the
     specified timeout expires.  The timeout shall expire when the absolute
     time specified by timeout passes, as measured by the clock on which
     timeouts are based.

     The pthread_mutex_getprioceiling() function shall return the current
     priority ceiling of the mutex.

     The pthread_mutex_setprioceiling() function shall either lock the mutex
     if it is unlocked, or block until it can successfully lock the mutex,
     then it shall change the mutex's priority ceiling and release the mutex.
     When the change is successful, the previous value of the priority ceiling
     shall be returned in old_ceiling.  The process of locking the mutex need
     not adhere to the priority protect protocol.  If
     pthread_mutex_setprioceiling() function fails, the mutex priority ceiling
     shall not be changed.

RETURN VALUES
     Upon success all described functions return zero.  Otherwise, an error
     number will be returned to indicate the error.

ERRORS
     pthread_mutex_init() may fail if:

     [EAGAIN]           The system lacks the resources to initialize another
                        mutex.

     [EINVAL]           The value specified by attr is invalid.

     [ENOMEM]           The process cannot allocate enough memory to
                        initialize another mutex.

     pthread_mutex_destroy() may fail if:

     [EBUSY]            Mutex is locked by another thread.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_lock() may fail if:

     [EDEADLK]          A deadlock would occur if the thread blocked waiting
                        for mutex.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_trylock() may fail if:

     [EBUSY]            Mutex is already locked.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_unlock() may fail if:

     [EINVAL]           The value specified by mutex is invalid.

     [EPERM]            The current thread does not hold a lock on mutex.

     pthread_mutex_timedlock() may fail if:

     [EINVAL]           The mutex was created with the protocol attribute
                        having the value PTHREAD_PRIO_PROTECT and the calling
                        thread's priority is higher than the mutex current
                        priority ceiling; or the process or thread would have
                        blocked, and the timeout parameter specified a
                        nanoseconds field value less than zero or greater than
                        or equal to 1000 million.

     [ETIMEDOUT]        The mutex could not be locked before the specified
                        timeout expired.

     The pthread_mutex_getprioceiling() and pthread_mutex_setprioceiling()
     functions may fail if:

     [EINVAL]           The priority requested by prioceiling is out of range;
                        or the value specified by mutex does not refer to a
                        currently existing mutex.

     [EPERM]            The caller does not have the privilege to perform the
                        operation.

SEE ALSO
     pthread(3), pthread_barrier(3), pthread_cond(3), pthread_mutexattr(3),
     pthread_rwlock(3), pthread_spin(3)

STANDARDS
     These functions conform to IEEE Std 1003.1-2001 ("POSIX.1").

NetBSD 10.99                     June 12, 2016                    NetBSD 10.99