PTHREAD_MUTEX_INIT(3) | Library Functions Manual | PTHREAD_MUTEX_INIT(3)

# NAME

`pthread_mutex_init`, `pthread_mutex_destroy`, `pthread_mutex_lock`, `pthread_mutex_timedlock`, `pthread_mutex_trylock`, `pthread_mutex_unlock` — operations on mutex variables

# SYNOPSIS

POSIX Threads Library (libpthread, -lpthread)
`#include <pthread.h>`

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

int
`pthread_mutex_destroy`(pthread_mutex_t *mutex);

int
`pthread_mutex_lock`(pthread_mutex_t *mutex);

int
`pthread_mutex_timedlock`(pthread_mutex_t *mutex, const struct timespec *abstime);

int
`pthread_mutex_trylock`(pthread_mutex_t *mutex);

int
`pthread_mutex_unlock`(pthread_mutex_t *mutex);

# DESCRIPTION

The `pthread_mutex_init`() function creates a new mutex, with attributes specified with attr. If attr is `NULL` the default attributes are used, otherwise attr should be initialized by calling pthread_mutexattr_init(3).

A mutex may also be initialized by assignment with the macro PTHREAD_MUTEX_INITIALIZER.

The `pthread_mutex_destroy`() function frees the resources allocated for mutex.

The `pthread_mutex_lock`() function locks mutex. If the mutex is currently locked by another thread, the calling thread will block until the mutex becomes available.

If the mutex is currently locked by the calling thread, then the behavior depends on the type of the mutex. If mutex is of type `PTHREAD_MUTEX_NORMAL`, then the calling thread will deadlock and never return from `pthread_mutex_lock`(). If mutex is of type `PTHREAD_MUTEX_ERRORCHECK`, then `EDEADLK` is immediately returned. If mutex is of type `PTHREAD_MUTEX_RECURSIVE`, then the recursion count on the mutex is incremented.

The `pthread_mutex_timedlock`() function locks mutex like `pthread_mutex_lock`() except that it will not block or deadlock past the system time specified in abstime.

The `pthread_mutex_trylock`() function locks mutex like `pthread_mutex_lock`() except that if mutex is locked by another thread, or is locked by the calling thread and is not of type `PTHREAD_MUTEX_RECURSIVE`, then it will immediately return `EBUSY`.

The `pthread_mutex_unlock`() function unlocks the previously locked mutex.

# RETURN VALUES

These functions return zero for success and positive error numbers for failure.

# ERRORS

`pthread_mutex_init`() fails if:

[`EINVAL`]
  The value specified by attr is invalid.
[`ENOMEM`]
  The process cannot allocate enough memory to create another mutex.

The other functions fail if:

[`EINVAL`]
  The value specified by mutex is invalid.

`pthread_mutex_destroy`() fails if:

[`EBUSY`]
  mutex is locked or referenced by another thread.

`pthread_mutex_lock`(), `pthread_mutex_timedlock`(), and `pthread_mutex_trylock`() fail if:

[`EAGAIN`]
  The mutex is of type `PTHREAD_MUTEX_RECURSIVE` and the maximum recursion count has been reached.

`pthread_mutex_lock`() and `pthread_mutex_timedlock`() fail if:

[`EDEADLK`]
  The mutex is of type `PTHREAD_MUTEX_ERRORCHECK` and is already locked by the calling thread.

`pthread_mutex_timedlock`() fails if:

[`ETIMEDOUT`]
  The mutex could not be locked and the specified time was reached.

`pthread_mutex_trylock`() fails if:

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

`pthread_mutex_unlock`() fails if:

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

# SEE ALSO

pthread_mutexattr_init(3), pthreads(3)

# STANDARDS

These functions conform to. Raising an error for invalid arguments is an extension.

July 25, 2025 | Debian