OpenBSD manual page server

NAME

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

SYNOPSIS

/* -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 IEEE Std 1003.1-2024 (“POSIX.1”). Raising an error for invalid arguments is an extension.