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

NAME

12       pthread_join — wait for thread termination
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

55       An example of thread creation and deletion follows:
56
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‐2017 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‐2017, Section 4.12, 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-2017, Standard for Information Technology -- Por‐
159       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
160       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
161       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
162       event of any discrepancy between this version and the original IEEE and
163       The Open Group Standard, the original IEEE and The Open Group  Standard
164       is  the  referee document. The original Standard can be obtained online
165       at http://www.opengroup.org/unix/online.html .
166
167       Any typographical or formatting errors that appear  in  this  page  are
168       most likely to have been introduced during the conversion of the source
169       files to man page format. To report such errors,  see  https://www.ker
170       nel.org/doc/man-pages/reporting_bugs.html .
171
172
173
174IEEE/The Open Group                  2017                     PTHREAD_JOIN(3P)
Impressum