71 lines
2.2 KiB
Groff
71 lines
2.2 KiB
Groff
.TH PTHREAD_JOIN 3 LinuxThreads
|
|
|
|
.SH NAME
|
|
pthread_join \- wait for termination of another thread
|
|
|
|
.SH SYNOPSIS
|
|
#include <pthread.h>
|
|
|
|
int pthread_join(pthread_t th, void **thread_return);
|
|
|
|
.SH DESCRIPTION
|
|
!pthread_join! suspends the execution of the calling thread until the
|
|
thread identified by |th| terminates, either by calling !pthread_exit!(3)
|
|
or by being cancelled.
|
|
|
|
If |thread_return| is not !NULL!, the return value of |th| is stored
|
|
in the location pointed to by |thread_return|. The return value of
|
|
|th| is either the argument it gave to !pthread_exit!(3), or
|
|
!PTHREAD_CANCELED! if |th| was cancelled.
|
|
|
|
The joined thread !th! must be in the joinable state: it must not have
|
|
been detached using !pthread_detach!(3) or the
|
|
!PTHREAD_CREATE_DETACHED! attribute to !pthread_create!(3).
|
|
|
|
When a joinable thread terminates, its memory resources (thread
|
|
descriptor and stack) are not deallocated until another thread
|
|
performs !pthread_join! on it. Therefore, !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 !pthread_join! on a thread |th| on which another
|
|
thread is already waiting for termination returns an error.
|
|
|
|
.SH CANCELLATION
|
|
|
|
!pthread_join! is a cancellation point. If a thread is canceled while
|
|
suspended in !pthread_join!, the thread execution resumes immediately
|
|
and the cancellation is executed without waiting for the |th| thread
|
|
to terminate. If cancellation occurs during !pthread_join!, the |th|
|
|
thread remains not joined.
|
|
|
|
.SH "RETURN VALUE"
|
|
On success, the return value of |th| is stored in the location pointed
|
|
to by |thread_return|, and 0 is returned. On error, a non-zero error
|
|
code is returned.
|
|
|
|
.SH ERRORS
|
|
.TP
|
|
!ESRCH!
|
|
No thread could be found corresponding to that specified by |th|.
|
|
.TP
|
|
!EINVAL!
|
|
The |th| thread has been detached.
|
|
.TP
|
|
!EINVAL!
|
|
Another thread is already waiting on termination of |th|.
|
|
.TP
|
|
!EDEADLK!
|
|
The |th| argument refers to the calling thread.
|
|
|
|
.SH AUTHOR
|
|
Xavier Leroy <Xavier.Leroy@inria.fr>
|
|
|
|
.SH "SEE ALSO"
|
|
!pthread_exit!(3),
|
|
!pthread_detach!(3),
|
|
!pthread_create!(3),
|
|
!pthread_attr_setdetachstate!(3),
|
|
!pthread_cleanup_push!(3),
|
|
!pthread_key_create!(3).
|