MTX_INIT(3) Library Functions Manual MTX_INIT(3)

mtx_destroy mtx_init — destroy and initialize a mutex

#include <threads.h>

void mtx_destroy(mtx_t *mtx);
int mtx_init(mtx_t *mtx, int type);

[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_destroy () function shall release any resources used by the mutex pointed to by mtx. A destroyed mutex object can be reinitialized using mtx_init (); the results of otherwise referencing the object after it has been destroyed are undefined. It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex, or a mutex that another thread is attempting to lock, or a mutex that is being used in a cnd_timedwait(3) or cnd_wait(3) call by another thread, results in undefined behavior. The behavior is undefined if the value specified by the mtx argument to mtx_destroy () does not refer to an initialized mutex.

The mtx_init () function shall initialize a mutex object with properties indicated by , whose valid values include:

for a simple non-recursive mutex,
for a non-recursive mutex that supports timeout,
for a simple recursive mutex, or
for a recursive mutex that supports timeout.

If the mtx_init () function succeeds, it shall set the mutex pointed to by mtx to a value that uniquely identifies the newly initialized mutex. Upon successful initialization, the state of the mutex shall become initialized and unlocked. Attempting to initialize an already initialized mutex results in undefined behavior.

[CX] See V2_chap02(3) for further requirements.

These functions shall not be affected if the calling thread executes a signal handler during the call.

The mtx_destroy () function shall not return a value.

The mtx_init () function shall return thrd_success on success or thrd_error if the request could not be honored.

No errors are defined.

None.

A mutex can be destroyed immediately after it is unlocked. However, since attempting to destroy a locked mutex, or a mutex that another thread is attempting to lock, or a mutex that is being used in a cnd_timedwait(3) or cnd_wait(3) call by another thread results in undefined behavior, care must be taken to ensure that no other thread may be referencing the mutex.

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

None.

cnd_timedwait(3), mtx_lock(3)

XBD <threads.h>

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

June 14, 2024 posix.fail