NAME
thrd_exit — thread
termination
SYNOPSIS
#include
<threads.h>
_Noreturn void thrd_exit(int res);
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.
For every thread-specific storage key
[CX] (regardless of whether it has type
tss_t or
pthread_key_t)
which was created with a non-null destructor and for which the value is
non-null, thrd_exit () shall set the value
associated with the key to a null pointer value and then invoke the
destructor with its previous value. The order in which destructors are
invoked is unspecified.
If after this process there remain keys with both non-null destructors and values, the implementation shall repeat this process up to [CX] {PTHREAD_DESTRUCTOR_ITERATIONS} times.
Following this, the thrd_exit ()
function shall terminate execution of the calling thread and shall set its
exit status to res.
[CX] Thread termination shall not release any application
visible process resources, including, but not limited to, mutexes and file
descriptors, nor shall it perform any process-level cleanup actions,
including, but not limited to, calling any atexit(3)
routines that might exist.
An implicit call to thrd_exit () is made
when a thread that was created using thrd_create(3)
returns from the start routine that was used to create it (see
thrd_create(3)).
[CX] The behavior of
thrd_exit () is undefined if called from a
destructor function that was invoked as a result of either an implicit or
explicit call to thrd_exit ().
The process shall exit with an exit status of zero after the last thread has been terminated. The behavior shall be as if the implementation called exit(3) with a zero argument at thread termination time.
RETURN VALUE
This function shall not return a value.
ERRORS
No errors are defined.
EXAMPLES
None.
APPLICATION USAGE
Calls to thrd_exit () should not be made
from threads created using pthread_create(3) or via a
SIGEV_THREAD notification, as their exit status has a different type (
void *
instead of
int). If
thrd_exit () is called from the initial thread and
it is not the last thread to terminate, other threads should not try to
obtain its exit status using pthread_join(3).
RATIONALE
The normal mechanism by which a thread that was started using
thrd_create(3) terminates is to return from the function
that was specified in the thrd_create(3) call that started
it. The thrd_exit () function provides the
capability for such a thread to terminate without requiring a return from
the start routine of that thread, thereby providing a function analogous to
exit(3).
Regardless of the method of thread termination, the destructors for any existing thread-specific data are executed.
FUTURE DIRECTIONS
None.
SEE ALSO
exit(3), pthread_create(3), thrd_join(3)
XBD <threads.h>
CHANGE HISTORY
First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.