.TH PTHREAD_JOIN 3 LinuxThreads

.SH NAME
pthread_join \- wait for termination of another thread

.SH SYNOPSIS
.B #include <pthread.h>

.BI "int pthread_join(pthread_t " th ", void **" thread_return ");"

.SH DESCRIPTION
.B "pthread_join"
suspends the execution of the calling thread until the
thread identified by 
.I "th"
terminates, either by calling 
.BR "pthread_exit" (3)
or by being cancelled.

If 
.I "thread_return"
is not 
.BR "NULL" ,
the return value of 
.I "th"
is stored
in the location pointed to by 
.IR "thread_return" .
The return value of
.I "th"
is either the argument it gave to 
.BR "pthread_exit" (3),
or
.B "PTHREAD_CANCELED"
if 
.I "th"
was cancelled.

The joined thread 
.B "th"
must be in the joinable state: it must not have
been detached using 
.BR "pthread_detach" (3)
or the
.B "PTHREAD_CREATE_DETACHED"
attribute to 
.BR "pthread_create" (3).

When a joinable thread terminates, its memory resources (thread
descriptor and stack) are not deallocated until another thread
performs 
.B "pthread_join"
on it. Therefore, 
.B "pthread_join"
must be
called once for each joinable thread created to avoid memory leaks.

At most one thread can wait for the termination of a given
thread. Calling 
.B "pthread_join"
on a thread 
.I "th"
on which another
thread is already waiting for termination returns an error.

.SH CANCELLATION

.B "pthread_join"
is a cancellation point. If a thread is canceled while
suspended in 
.BR "pthread_join" ,
the thread execution resumes immediately
and the cancellation is executed without waiting for the 
.I "th"
thread
to terminate. If cancellation occurs during 
.BR "pthread_join" ,
the 
.I "th"
thread remains not joined.

.SH "RETURN VALUE"
On success, the return value of 
.I "th"
is stored in the location pointed
to by 
.IR "thread_return" ,
and 0 is returned. On error, a non-zero error
code is returned.

.SH ERRORS
.TP
.B "ESRCH"
No thread could be found corresponding to that specified by 
.IR "th" .
.TP
.B "EINVAL"
The 
.I "th"
thread has been detached.
.TP
.B "EINVAL"
Another thread is already waiting on termination of 
.IR "th" .
.TP
.B "EDEADLK"
The 
.I "th"
argument refers to the calling thread.

.SH AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH "SEE ALSO"
.BR "pthread_exit" (3),
.BR "pthread_detach" (3),
.BR "pthread_create" (3),
.BR "pthread_attr_setdetachstate" (3),
.BR "pthread_cleanup_push" (3),
.BR "pthread_key_create" (3).