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() routines that might exist.

An implicit call to thrd_exit() is made when a thread that was created using thrd_create() returns from the start routine that was used to create it (see thrd_create).

^[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() 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() 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().

RATIONALE

The normal mechanism by which a thread that was started using thrd_create() terminates is to return from the function that was specified in the thrd_create() 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().

Regardless of the method of thread termination, the destructors for any existing thread-specific data are executed.

FUTURE DIRECTIONS

None.

SEE ALSO

exit, pthread_create, thrd_join

XBD <threads.h>

CHANGE HISTORY

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