linuxthreads/man/pthread_join.man

   1 .TH PTHREAD_JOIN 3 LinuxThreads
   2
   3 .SH NAME
   4 pthread_join \- wait for termination of another thread
   5
   6 .SH SYNOPSIS
   7 #include <pthread.h>
   8
   9 int pthread_join(pthread_t th, void **thread_return);
  10
  11 .SH DESCRIPTION
  12 !pthread_join! suspends the execution of the calling thread until the
  13 thread identified by |th| terminates, either by calling !pthread_exit!(3)
  14 or by being cancelled.
  15
  16 If |thread_return| is not !NULL!, the return value of |th| is stored
  17 in the location pointed to by |thread_return|.  The return value of
  18 |th| is either the argument it gave to !pthread_exit!(3), or
  19 !PTHREAD_CANCELED! if |th| was cancelled.
  20
  21 The joined thread !th! must be in the joinable state: it must not have
  22 been detached using !pthread_detach!(3) or the
  23 !PTHREAD_CREATE_DETACHED! attribute to !pthread_create!(3).
  24
  25 When a joinable thread terminates, its memory resources (thread
  26 descriptor and stack) are not deallocated until another thread
  27 performs !pthread_join! on it. Therefore, !pthread_join! must be
  28 called once for each joinable thread created to avoid memory leaks.
  29
  30 At most one thread can wait for the termination of a given
  31 thread. Calling !pthread_join! on a thread |th| on which another
  32 thread is already waiting for termination returns an error.
  33
  34 .SH CANCELLATION
  35
  36 !pthread_join! is a cancellation point. If a thread is canceled while
  37 suspended in !pthread_join!, the thread execution resumes immediately
  38 and the cancellation is executed without waiting for the |th| thread
  39 to terminate. If cancellation occurs during !pthread_join!, the |th|
  40 thread remains not joined.
  41
  42 .SH "RETURN VALUE"
  43 On success, the return value of |th| is stored in the location pointed
  44 to by |thread_return|, and 0 is returned. On error, a non-zero error
  45 code is returned.
  46
  47 .SH ERRORS
  48 .TP
  49 !ESRCH!
  50 No thread could be found corresponding to that specified by |th|.
  51 .TP
  52 !EINVAL!
  53 The |th| thread has been detached.
  54 .TP
  55 !EINVAL!
  56 Another thread is already waiting on termination of |th|.
  57 .TP
  58 !EDEADLK!
  59 The |th| argument refers to the calling thread.
  60
  61 .SH AUTHOR
  62 Xavier Leroy <Xavier.Leroy@inria.fr>
  63
  64 .SH "SEE ALSO"
  65 !pthread_exit!(3),
  66 !pthread_detach!(3),
  67 !pthread_create!(3),
  68 !pthread_attr_setdetachstate!(3),
  69 !pthread_cleanup_push!(3),
  70 !pthread_key_create!(3).