aboutsummaryrefslogtreecommitdiff
path: root/linuxthreads/man/pthread_join.man
diff options
context:
space:
mode:
Diffstat (limited to 'linuxthreads/man/pthread_join.man')
-rw-r--r--linuxthreads/man/pthread_join.man70
1 files changed, 70 insertions, 0 deletions
diff --git a/linuxthreads/man/pthread_join.man b/linuxthreads/man/pthread_join.man
new file mode 100644
index 0000000000..d587093841
--- /dev/null
+++ b/linuxthreads/man/pthread_join.man
@@ -0,0 +1,70 @@
+.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).