Waiting for Thread Termination

The pthread_join() function blocks the calling thread until the specified thread terminates.

pthread_join Syntax

Use pthread_join(3C) to wait for a thread to terminate.

int pthread_join(pthread_t tid, void **status);

#include <pthread.h>

pthread_t tid;
int ret;
void *status;

/* waiting to join thread "tid" with status */
ret = pthread_join(tid, &status);

/* waiting to join thread "tid" without status */
ret = pthread_join(tid, NULL); 

The specified thread must be in the current process and must not be detached. For information on thread detachment, see Setting Detach State.

When status is not NULL, status points to a location that is set to the exit status of the terminated thread when pthread_join() returns successfully.

If multiple threads wait for the same thread to terminate, all the threads wait until the target thread terminates. Then one waiting thread returns successfully. The other waiting threads fail with an error of ESRCH.

After pthread_join() returns, any data storage associated with the terminated thread can be reclaimed by the application.

pthread_join Return Values

pthread_join() returns zero when the call completes successfully. Any other return value indicates that an error occurred. When any of the following conditions are detected, pthread_join() fails and returns the corresponding value.

ESRCH

Description:

No thread could be found corresponding to the given thread ID.

EDEADLK

Description:

A deadlock would exist, such as a thread waits for itself or thread A waits for thread B and thread B waits for thread A.

EINVAL

Description:

The thread corresponding to the given thread ID is a detached thread.

pthread_join() works only for target threads that are nondetached. When no reason exists to synchronize with the termination of a particular thread, then that thread should be detached.