Debian Codegraph @

upstream/debian-unstable/man3/pthread_join.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_join 3 2025-05-17 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_join \- join with a terminated thread
9 .SH LIBRARY
10 POSIX threads library
11 .RI ( libpthread ,\~ \-lpthread )
12 .SH SYNOPSIS
13 .nf
14 .B #include <pthread.h>
15 .P
16 .BI "int pthread_join(pthread_t " thread ", void **" retval );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR pthread_join ()
21 function waits for the thread specified by
22 .I thread
23 to terminate.
24 If that thread has already terminated, then
25 .BR pthread_join ()
26 returns immediately.
27 The thread specified by
28 .I thread
29 must be joinable.
30 .P
31 If
32 .I retval
33 is not NULL, then
34 .BR pthread_join ()
35 copies the exit status of the target thread
36 (i.e., the value that the target thread supplied to
37 .BR pthread_exit (3))
38 into the location pointed to by
39 .IR retval .
40 If the target thread was canceled, then
41 .B PTHREAD_CANCELED
42 is placed in the location pointed to by
43 .IR retval .
44 .P
45 If multiple threads simultaneously try to join with the same thread,
46 the results are undefined.
47 If the thread calling
48 .BR pthread_join ()
49 is canceled, then the target thread will remain joinable
50 (i.e., it will not be detached).
51 .SH RETURN VALUE
52 On success,
53 .BR pthread_join ()
54 returns 0;
55 on error, it returns an error number.
56 .SH ERRORS
57 .TP
58 .B EDEADLK
59 A deadlock was detected
60 .\" The following verified by testing on glibc 2.8/NPTL:
61 (e.g., two threads tried to join with each other);
62 or
63 .\" The following verified by testing on glibc 2.8/NPTL:
64 .I thread
65 specifies the calling thread.
66 .TP
67 .B EINVAL
68 .I thread
69 is not a joinable thread.
70 .TP
71 .B EINVAL
72 Another thread is already waiting to join with this thread.
73 .\" POSIX.1-2001 does not specify this error case.
74 .TP
75 .B ESRCH
76 No thread with the ID
77 .I thread
78 could be found.
79 .SH ATTRIBUTES
80 For an explanation of the terms used in this section, see
81 .BR attributes (7).
82 .TS
83 allbox;
84 lbx lb lb
85 l l l.
86 Interface Attribute Value
87 T{
88 .na
89 .nh
90 .BR pthread_join ()
91 T} Thread safety MT-Safe
92 .TE
93 .SH STANDARDS
94 POSIX.1-2008.
95 .SH HISTORY
96 POSIX.1-2001.
97 .SH NOTES
98 After a successful call to
99 .BR pthread_join (),
100 the caller is guaranteed that the target thread has terminated.
101 The caller may then choose to do any clean-up that is required
102 after termination of the thread (e.g., freeing memory or other
103 resources that were allocated to the target thread).
104 .P
105 Joining with a thread that has previously been joined results in
106 undefined behavior.
107 .P
108 Failure to join with a thread that is joinable
109 (i.e., one that is not detached),
110 produces a "zombie thread".
111 Avoid doing this,
112 since each zombie thread consumes some system resources,
113 and when enough zombie threads have accumulated,
114 it will no longer be possible to create new threads (or processes).
115 .P
116 There is no pthreads analog of
117 .IR "waitpid(\-1,\ &status,\ 0)" ,
118 that is, "join with any terminated thread".
119 If you believe you need this functionality,
120 you probably need to rethink your application design.
121 .P
122 All of the threads in a process are peers:
123 any thread can join with any other thread in the process.
124 .SH EXAMPLES
125 See
126 .BR pthread_create (3).
127 .SH SEE ALSO
128 .BR pthread_cancel (3),
129 .BR pthread_create (3),
130 .BR pthread_detach (3),
131 .BR pthread_exit (3),
132 .BR pthread_tryjoin_np (3),
133 .BR pthreads (7)