1PTHREAD_JOIN(3P)           POSIX Programmer's Manual          PTHREAD_JOIN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       pthread_join — wait for thread termination
14

SYNOPSIS

16       #include <pthread.h>
17
18       int pthread_join(pthread_t thread, void **value_ptr);
19

DESCRIPTION

21       The pthread_join() function shall  suspend  execution  of  the  calling
22       thread until the target thread terminates, unless the target thread has
23       already terminated. On return from  a  successful  pthread_join()  call
24       with  a non-NULL value_ptr argument, the value passed to pthread_exit()
25       by the terminating thread shall be made available in the location  ref‐
26       erenced  by value_ptr.  When a pthread_join() returns successfully, the
27       target thread has been terminated. The results of multiple simultaneous
28       calls  to  pthread_join()  specifying  the same target thread are unde‐
29       fined. If the thread calling pthread_join() is canceled, then the  tar‐
30       get thread shall not be detached.
31
32       It is unspecified whether a thread that has exited but remains unjoined
33       counts against {PTHREAD_THREADS_MAX}.
34
35       The behavior is undefined if the value specified by the thread argument
36       to pthread_join() does not refer to a joinable thread.
37
38       The behavior is undefined if the value specified by the thread argument
39       to pthread_join() refers to the calling thread.
40

RETURN VALUE

42       If successful, the pthread_join() function shall  return  zero;  other‐
43       wise, an error number shall be returned to indicate the error.
44

ERRORS

46       The pthread_join() function may fail if:
47
48       EDEADLK
49              A deadlock was detected.
50
51       The pthread_join() function shall not return an error code of [EINTR].
52
53       The following sections are informative.
54

EXAMPLES

56       An example of thread creation and deletion follows:
57
58           typedef struct {
59               int *ar;
60               long n;
61           } subarray;
62
63           void *
64           incer(void *arg)
65           {
66               long i;
67
68               for (i = 0; i < ((subarray *)arg)->n; i++)
69                   ((subarray *)arg)->ar[i]++;
70           }
71
72           int main(void)
73           {
74               int        ar[1000000];
75               pthread_t  th1, th2;
76               subarray   sb1, sb2;
77
78               sb1.ar = &ar[0];
79               sb1.n  = 500000;
80               (void) pthread_create(&th1, NULL, incer, &sb1);
81
82               sb2.ar = &ar[500000];
83               sb2.n  = 500000;
84               (void) pthread_create(&th2, NULL, incer, &sb2);
85
86               (void) pthread_join(th1, NULL);
87               (void) pthread_join(th2, NULL);
88               return 0;
89           }
90

APPLICATION USAGE

92       None.
93

RATIONALE

95       The  pthread_join() function is a convenience that has proven useful in
96       multi-threaded applications. It is true that a programmer  could  simu‐
97       late  this  function  if it were not provided by passing extra state as
98       part of the argument to the start_routine().   The  terminating  thread
99       would set a flag to indicate termination and broadcast a condition that
100       is part of that state; a joining thread would wait  on  that  condition
101       variable.  While  such a technique would allow a thread to wait on more
102       complex conditions (for example, waiting for multiple threads to termi‐
103       nate),  waiting  on  individual thread termination is considered widely
104       useful. Also, including the pthread_join() function in no way precludes
105       a  programmer  from coding such complex waits. Thus, while not a primi‐
106       tive, including pthread_join() in this volume of POSIX.1‐2008 was  con‐
107       sidered valuable.
108
109       The  pthread_join()  function  provides  a simple mechanism allowing an
110       application to wait for a thread to terminate. After the thread  termi‐
111       nates,  the application may then choose to clean up resources that were
112       used by the thread. For instance,  after  pthread_join()  returns,  any
113       application-provided stack storage could be reclaimed.
114
115       The  pthread_join()  or  pthread_detach() function should eventually be
116       called for every thread that is created with the detachstate  attribute
117       set  to  PTHREAD_CREATE_JOINABLE  so  that  storage associated with the
118       thread may be reclaimed.
119
120       The interaction between pthread_join() and cancellation is well-defined
121       for the following reasons:
122
123        *  The  pthread_join()  function, like all other non-async-cancel-safe
124           functions, can only be called with deferred cancelability type.
125
126        *  Cancellation cannot occur in the disabled cancelability state.
127
128       Thus, only the default cancelability state need be considered. As spec‐
129       ified,  either the pthread_join() call is canceled, or it succeeds, but
130       not both. The difference is obvious to the application, since either  a
131       cancellation  handler  is  run  or pthread_join() returns. There are no
132       race conditions since pthread_join() was called in the deferred  cance‐
133       lability state.
134
135       If  an  implementation  detects  that the value specified by the thread
136       argument to pthread_join() does not refer to a joinable thread,  it  is
137       recommended that the function should fail and report an [EINVAL] error.
138
139       If  an  implementation  detects  that the value specified by the thread
140       argument to pthread_join() refers to the calling thread, it  is  recom‐
141       mended that the function should fail and report an [EDEADLK] error.
142
143       If  an  implementation  detects use of a thread ID after the end of its
144       lifetime, it is recommended that the function should fail and report an
145       [ESRCH] error.
146

FUTURE DIRECTIONS

148       None.
149

SEE ALSO

151       pthread_create(), wait()
152
153       The  Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory Syn‐
154       chronization, <pthread.h>
155
157       Portions of this text are reprinted and reproduced in  electronic  form
158       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
159       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
160       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
161       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
162       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
163       event of any discrepancy between this version and the original IEEE and
164       The  Open Group Standard, the original IEEE and The Open Group Standard
165       is the referee document. The original Standard can be  obtained  online
166       at http://www.unix.org/online.html .
167
168       Any  typographical  or  formatting  errors that appear in this page are
169       most likely to have been introduced during the conversion of the source
170       files  to  man page format. To report such errors, see https://www.ker
171       nel.org/doc/man-pages/reporting_bugs.html .
172
173
174
175IEEE/The Open Group                  2013                     PTHREAD_JOIN(3P)
Impressum