PTHREAD_MUTEX(3)

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”).

June 12, 2016 | NetBSD 10.1