pthread_join or pthread_detach Subroutine

Purpose

Blocks or detaches the calling thread until the specified thread terminates.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

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

int pthread_detach (thread)
pthread_t thread;

Description

The pthread_join subroutine blocks the calling thread until the thread thread terminates. The target thread's termination status is returned in the status parameter.

If the target thread is already terminated, but not yet detached, the subroutine returns immediately. It is impossible to join a detached thread, even if it is not yet terminated. The target thread is automatically detached after all joined threads have been woken up.

This subroutine does not itself cause a thread to be terminated. It acts like the pthread_cond_wait subroutine to wait for a special condition.

Note: The pthread.h header file must be the first included file of each source file using the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

The pthread_detach subroutine is used to indicate to the implementation that storage for the thread whose thread ID is in the location thread can be reclaimed when that thread terminates. This storage shall be reclaimed on process exit, regardless of whether the thread has been detached or not, and may include storage for thread return value. If thread has not yet terminated, pthread_detach shall not cause it to terminate. Multiple pthread_detach calls on the same target thread causes an error.

Parameters

Item	Description
thread	Specifies the target thread.
status	Points to where the termination status of the target thread will be stored. If the value is NULL, the termination status is not returned.

Return Values

If successful, the pthread_join function returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_join and pthread_detach functions will fail if:

Item	Description
EINVAL	The implementation has detected that the value specified by thread does not refer to a joinable thread.
ESRCH	No thread could be found corresponding to that specified by the given thread ID.

The pthread_join function will fail if:

Item	Description
EDEADLK	The value of thread specifies the calling thread.

The pthread_join function will not return an error code of EINTR.