OpenBSD manual page server

NAME

pthread_mutex_lock, pthread_mutex_timedlock, pthread_mutex_trylock — lock a mutex

SYNOPSIS

#include <pthread.h>

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);

DESCRIPTION

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. If that time is reached without being able to lock mutex, then it returns ETIMEDOUT.

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.

RETURN VALUES

If successful, pthread_mutex_lock(), pthread_mutex_timedlock(), and pthread_mutex_trylock() will return zero, otherwise an error number will be returned to indicate the error.

ERRORS

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

[EINVAL]

The value specified by mutex is invalid.

[EAGAIN]

The mutex is of type PTHREAD_MUTEX_RECURSIVE and the maximum recursion count has been reached.

In addition, pthread_mutex_lock() and pthread_mutex_timedlock() may return the following error:

[EDEADLK]

The mutex is of type PTHREAD_MUTEX_ERRORCHECK and is already locked by the calling thread.

pthread_mutex_timedlock() may return the following error:

[ETIMEDOUT]

The mutex could not be locked and the specified time was reached.

pthread_mutex_trylock() may return the following error:

[EBUSY]

The mutex could not be locked because it was already locked.

SEE ALSO

pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_unlock(3), pthread_mutexattr_settype(3)

STANDARDS

pthread_mutex_lock(), pthread_mutex_timedlock(), and pthread_mutex_trylock() conform to IEEE Std 1003.1-2008 (“POSIX.1”).