pthread_join(PTHREAD)

pthread_join -- join control paths with another thread

Synopsis

cc [options] -Kthread file

#include <thread.h>

int pthread_join(thread_t thread, void **status);

Description

pthread_join waits for termination of the undetached sibling thread designated by thread and retrieves the exit status of the terminated thread (see pthread_exit(PTHREAD)).

When the thread being waited for (thread) terminates, and pthread_join returns, it can be viewed that the terminated thread has ``joined control paths'' with the thread that called pthread_join.

If thread is set to the thread ID of an undetached sibling thread, pthread_join waits for that thread to terminate. If thread is equal to (thread_t)0, pthread_join waits for termination of any undetached sibling thread, and returns when the first one completes pthread_exit.

Threads created with the THR_DETACHED flag cannot be joined.

If status is not NULL, the location pointed to by status is set to the exit status from the terminated sibling thread.

Only one thread can successfully return from a pthread_join for a given target thread. If more than one thread is waiting for a specific thread to terminate, one is successful and the others fail with error indication ESRCH. This allows exactly one thread to join with and obtain status from a given thread.

If thread has already been pthread_joined, or otherwise is not known by the implementation, ESRCH is returned.

The wait in pthread_join is not broken by a signal. If a thread waiting in pthread_join receives a signal that is not masked, if will execute the signal handler, and then return to waiting in pthread_join. Note that this behavior differs from that of pthread_cond_wait.

Return values

pthread_join returns zero for success and an error number on failure.

Diagnostics

If any of the following conditions occurs, pthread_join returns the corresponding value:

ESRCH: there is no joinable (undetached) thread in the current process with thread ID thread.
EDEADLK: thread is the calling thread's thread ID.
EINVAL: thread is (thread_t) 0, and there are no undetached sibling threads to wait for.

References

Intro(PTHREAD), pthread_cond_wait(PTHREAD), pthread_create(PTHREAD), pthread_exit(PTHREAD), wait(S)

Standards compliance

The Single UNIX Specification, Version 2; The Open Group.