manual/LDP_man-pages/original/man3/pthread_join.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH PTHREAD_JOIN 3 2008-11-27 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_join \- join with a terminated thread
  27 .SH SYNOPSIS
  28 .nf
  29 .B #include <pthread.h>
  30
  31 .BI "int pthread_join(pthread_t " thread ", void **" retval );
  32 .fi
  33 .sp
  34 Compile and link with \fI\-pthread\fP.
  35 .SH DESCRIPTION
  36 The
  37 .BR pthread_join ()
  38 function waits for the thread specified by
  39 .IR thread
  40 to terminate.
  41 If that thread has already terminated, then
  42 .BR pthread_join ()
  43 returns immediately.
  44 The thread specified by
  45 .I thread
  46 must be joinable.
  47
  48 If
  49 .I retval
  50 is not NULL, then
  51 .BR pthread_join ()
  52 copies the exit status of the target thread
  53 (i.e., the value that the target thread supplied to
  54 .BR pthread_exit (3))
  55 into the location pointed to by
  56 .IR *retval .
  57 If the target thread was canceled, then
  58 .B PTHREAD_CANCELED
  59 is placed in
  60 .IR *retval .
  61
  62 If multiple threads simultaneously try to join with the same thread,
  63 the results are undefined.
  64 If the thread calling
  65 .BR pthread_join ()
  66 is canceled, then the target thread will remain joinable
  67 (i.e., it will not be detached).
  68 .SH RETURN VALUE
  69 On success,
  70 .BR pthread_join ()
  71 returns 0;
  72 on error, it returns an error number.
  73 .SH ERRORS
  74 .TP
  75 .B EDEADLK
  76 A deadlock was detected
  77 .\" The following verified by testing on glibc 2.8/NPTL:
  78 (e.g., two threads tried to join with each other);
  79 or
  80 .\" The following verified by testing on glibc 2.8/NPTL:
  81 .I thread
  82 specifies the calling thread.
  83 .TP
  84 .B EINVAL
  85 .I thread
  86 is not a joinable thread.
  87 .TP
  88 .B EINVAL
  89 Another thread is already waiting to join with this thread.
  90 .\" POSIX.1-2001 does not specify this error case.
  91 .TP
  92 .B ESRCH
  93 No thread with the ID
  94 .I thread
  95 could be found.
  96 .SH CONFORMING TO
  97 POSIX.1-2001.
  98 .SH NOTES
  99 After a successful call to
 100 .BR pthread_join (),
 101 the caller is guaranteed that the target thread has terminated.
 102
 103 Joining with a thread that has previously been joined results in
 104 undefined behavior.
 105
 106 Failure to join with a thread that is joinable
 107 (i.e., one that is not detached),
 108 produces a "zombie thread".
 109 Avoid doing this,
 110 since each zombie thread consumes some system resources,
 111 and when enough zombie threads have accumulated,
 112 it will no longer be possible to create new threads (or processes).
 113
 114 There is no pthreads analog of
 115 .IR "waitpid(-1,\ &status,\ 0)" ,
 116 that is, "join with any terminated thread".
 117 If you believe you need this functionality,
 118 you probably need to rethink your application design.
 119
 120 All of the threads in a process are peers:
 121 any thread can join with any other thread in the process.
 122 .SH EXAMPLE
 123 See
 124 .BR pthread_create (3).
 125 .SH SEE ALSO
 126 .BR pthread_cancel (3),
 127 .BR pthread_create (3),
 128 .BR pthread_detach (3),
 129 .BR pthread_exit (3),
 130 .BR pthread_tryjoin_np (3),
 131 .BR pthreads (7)