NAME

mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock — lock and unlock a mutex

SYNOPSIS

#include <threads.h>

int mtx_lock(mtx_t *mtx);
int mtx_timedlock(mtx_t *restrict mtx,
       const struct timespec *restrict ts);
int mtx_trylock(mtx_t *mtx);
int mtx_unlock(mtx_t *mtx);


DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The mtx_lock() function shall block until it locks the mutex pointed to by mtx. If the mutex is non-recursive, the application shall ensure that it is not already locked by the calling thread.

The mtx_timedlock() function shall block until it locks the mutex pointed to by mtx or until after the TIME_UTC-based calendar time pointed to by ts. The application shall ensure that the specified mutex supports timeout. ^[CX] Under no circumstance shall the function fail with a timeout if the mutex can be locked immediately. The validity of the ts parameter need not be checked if the mutex can be locked immediately.

The mtx_trylock() function shall endeavor to lock the mutex pointed to by mtx. If the mutex is already locked (by any thread, including the current thread), the function shall return without blocking. If the mutex is recursive and the mutex is currently owned by the calling thread, the mutex lock count (see below) shall be incremented by one and the mtx_trylock() function shall immediately return success.

^[CX] These functions shall not be affected if the calling thread executes a signal handler during the call; if a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the thread shall resume waiting for the mutex as if it was not interrupted.

If a call to mtx_lock(), mtx_timedlock() or mtx_trylock() locks the mutex, prior calls to mtx_unlock() on the same mutex shall synchronize with this lock operation.

The mtx_unlock() function shall unlock the mutex pointed to by mtx. The application shall ensure that the mutex pointed to by mtx is locked by the calling thread. ^[CX]  If there are threads blocked on the mutex object referenced by mtx when mtx_unlock() is called, resulting in the mutex becoming available, the scheduling policy shall determine which thread shall acquire the mutex.

A recursive mutex shall maintain the concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock count shall be set to one. Every time a thread relocks this mutex, the lock count shall be incremented by one. Each time the thread unlocks the mutex, the lock count shall be decremented by one. When the lock count reaches zero, the mutex shall become available for other threads to acquire.

For purposes of determining the existence of a data race, mutex lock and unlock operations on mutexes of type mtx_t behave as atomic operations. All lock and unlock operations on a particular mutex occur in some particular total order.

If mtx does not refer to an initialized mutex object, the behavior of these functions is undefined.

RETURN VALUE

The mtx_lock() and mtx_unlock() functions shall return thrd_success on success, or thrd_error if the request could not be honored.

The mtx_timedlock() function shall return thrd_success on success, or thrd_timedout if the time specified was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

The mtx_trylock() function shall return thrd_success on success, or thrd_busy if the resource requested is already in use, or thrd_error if the request could not be honored. The mtx_trylock() function can spuriously fail to lock an unused resource, in which case it shall return thrd_busy.

ERRORS

See RETURN VALUE.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

These functions are not affected by signal handlers for the reasons stated in XRAT B.2.3 Error Numbers.

Since <pthread.h> has no equivalent of the mtx_timed mutex property, if the <threads.h> interfaces are implemented as a thin wrapper around <pthread.h> interfaces (meaning mtx_t and pthread_mutex_t are the same type), all mutexes support timeout and mtx_timedlock() will not fail for a mutex that was not initialized with mtx_timed. Alternatively, implementations can use a less thin wrapper where mtx_t contains additional properties that are not held in pthread_mutex_t in order to be able to return a failure indication from mtx_timedlock() calls where the mutex was not initialized with mtx_timed.

FUTURE DIRECTIONS

None.

SEE ALSO

mtx_destroy, timespec_get

XBD <threads.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.