The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

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] [Option Start] 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. [Option End]

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] [Option Start] 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. [Option End]

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] [Option Start] 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. [Option End]

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] [Option Start]  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. [Option End]

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.


The following sections are informative.

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.

End of informative text.

 

return to top of page

UNIX® is a registered Trademark of The Open Group.
POSIX™ is a Trademark of The IEEE.
Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]