Debian Codegraph @

upstream/debian-trixie/man3/pthread_join.3

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