THRD_JOIN(3) Library Functions Manual THRD_JOIN(3)

thrd_join — wait for thread termination

#include <threads.h>

int thrd_join(thrd_t thr, int *res);

[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 thrd_join () function shall join the thread identified by thr with the current thread by blocking until the other thread has terminated. If the parameter res is not a null pointer, thrd_join () shall store the thread's exit status in the integer pointed to by res. The termination of the other thread shall synchronize with the completion of the thrd_join () function. The application shall ensure that the thread identified by thr has not been previously detached or joined with another thread.

The results of multiple simultaneous calls to thrd_join () specifying the same target thread are undefined.

The behavior is undefined if the value specified by the thr argument to thrd_join () refers to the calling thread.

[CX] It is unspecified whether a zombie thread counts against {PTHREAD_THREADS_MAX}.

If thr refers to a thread that was created using pthread_create(3) or via a SIGEV_THREAD notification and the thread terminates, or has already terminated, by returning from its start routine, the behavior of thrd_join () is undefined. If thr refers to a thread that terminates, or has already terminated, by calling pthread_exit(3) or by being cancelled, the behavior of thrd_join () is undefined.

The thrd_join () function shall not be affected if the calling thread executes a signal handler during the call.

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

[CX] It is implementation-defined whether thrd_join () detects deadlock situations; if it does detect them, it shall return thrd_error when one is detected.

See RETURN VALUE.

None.

None.

The thrd_join () function provides a simple mechanism allowing an application to wait for a thread to terminate. After the thread terminates, the application may then choose to clean up resources that were used by the thread. For instance, after thrd_join () returns, any application-provided stack storage could be reclaimed.

The thrd_join () or thrd_detach(3) function should eventually be called for every thread that is created using thrd_create(3) so that storage associated with the thread may be reclaimed.

The thrd_join () function cannot be used to obtain the exit status of a thread that was created using pthread_create(3) or via a SIGEV_THREAD notification and which terminates by returning from its start routine, or of a thread that terminates by calling pthread_exit(3), because such threads have a void * exit status, instead of the int that thrd_join () returns via its res argument.

The thrd_join () function cannot be used to obtain the exit status of a thread that terminates by being cancelled because it has no way to indicate that a thread was cancelled. (The pthread_join(3) function does this by returning a reserved void * exit status; it is not possible to reserve an int value for this purpose without introducing a conflict with the ISO C standard.) The standard developers considered adding a thrd_canceled enumeration constant that thrd_join () would return in this case. However, this return would be unexpected in code that is written to conform to the ISO C standard, and it would also not solve the problem that threads which use only ISO C <threads.h> interfaces (such as ones created by third party libraries written to conform to the ISO C standard) have no way to handle being cancelled, as the ISO C standard does not provide cancellation cleanup handlers.

The thrd_join () function is not affected by signal handlers for the reasons stated in XRAT B.2.3 Error Numbers.

None.

pthread_create(3), pthread_exit(3), pthread_join(3), thrd_create(3), thrd_exit(3)

XBD V1_chap04(7), <threads.h>

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

June 14, 2024 posix.fail