NAME

mtx_destroy, mtx_init — destroy and initialize a mutex

SYNOPSIS

#include <threads.h>

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


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_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() or cnd_wait() 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 type, whose valid values include:

mtx_plain

for a simple non-recursive mutex,

mtx_timed

for a non-recursive mutex that supports timeout,

mtx_plain|mtx_recursive

for a simple recursive mutex, or

mtx_timed|mtx_recursive

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 2.9.9 Synchronization Object Copies and Alternative Mappings for further requirements.

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

RETURN VALUE

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.

ERRORS

No errors are defined.

EXAMPLES

None.

APPLICATION USAGE

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() or cnd_wait() call by another thread results in undefined behavior, care must be taken to ensure that no other thread may be referencing the mutex.

RATIONALE

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

FUTURE DIRECTIONS

None.

SEE ALSO

cnd_timedwait, mtx_lock

XBD <threads.h>

CHANGE HISTORY

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