Debian Codegraph @

upstream/debian-unstable/man3/pthread_tryjoin_np.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_tryjoin_np 3 2025-05-17 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_tryjoin_np, pthread_timedjoin_np \- try to join with a
9 terminated thread
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <pthread.h>
17 .P
18 .BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval );
19 .BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval ,
20 .BI " const struct timespec *" abstime );
21 .fi
22 .SH DESCRIPTION
23 These functions operate in the same way as
24 .BR pthread_join (3),
25 except for the differences described on this page.
26 .P
27 The
28 .BR pthread_tryjoin_np ()
29 function performs a nonblocking join with the thread
30 .IR thread ,
31 returning the exit status of the thread in
32 .IR *retval .
33 If
34 .I thread
35 has not yet terminated, then instead of blocking, as is done by
36 .BR pthread_join (3),
37 the call returns an error.
38 .P
39 The
40 .BR pthread_timedjoin_np ()
41 function performs a join-with-timeout.
42 If
43 .I thread
44 has not yet terminated,
45 then the call blocks until a maximum time, specified in
46 .IR abstime ,
47 measured against the
48 .B CLOCK_REALTIME
49 clock.
50 If the timeout expires before
51 .I thread
52 terminates,
53 the call returns an error.
54 The
55 .I abstime
56 argument is a
57 .BR timespec (3)
58 structure,
59 specifying an absolute time measured since the Epoch (see
60 .BR time (2)).
61 .SH RETURN VALUE
62 On success,
63 these functions return 0;
64 on error, they return an error number.
65 .SH ERRORS
66 These functions can fail with the same errors as
67 .BR pthread_join (3).
68 .BR pthread_tryjoin_np ()
69 can in addition fail with the following error:
70 .TP
71 .B EBUSY
72 .I thread
73 had not yet terminated at the time of the call.
74 .P
75 .BR pthread_timedjoin_np ()
76 can in addition fail with the following errors:
77 .TP
78 .B EINVAL
79 .I abstime
80 value is invalid
81 .RI ( tv_sec
82 is less than 0 or
83 .I tv_nsec
84 is greater than 1e9).
85 .TP
86 .B ETIMEDOUT
87 The call timed out before
88 .I thread
89 terminated.
90 .P
91 .BR pthread_timedjoin_np ()
92 never returns the error
93 .BR EINTR .
94 .SH ATTRIBUTES
95 For an explanation of the terms used in this section, see
96 .BR attributes (7).
97 .TS
98 allbox;
99 lbx lb lb
100 l l l.
101 Interface Attribute Value
102 T{
103 .na
104 .nh
105 .BR pthread_tryjoin_np (),
106 .BR pthread_timedjoin_np ()
107 T} Thread safety MT-Safe
108 .TE
109 .SH STANDARDS
110 GNU;
111 hence the suffix "_np" (nonportable) in the names.
112 .SH HISTORY
113 glibc 2.3.3.
114 .SH BUGS
115 The
116 .BR pthread_timedjoin_np ()
117 function measures time by internally calculating a relative sleep interval
118 that is then measured against the
119 .B CLOCK_MONOTONIC
120 clock instead of the
121 .B CLOCK_REALTIME
122 clock.
123 Consequently, the timeout is unaffected by discontinuous changes to the
124 .B CLOCK_REALTIME
125 clock.
126 .SH EXAMPLES
127 The following code waits to join for up to 5 seconds:
128 .P
129 .in +4n
130 .EX
131 struct timespec ts;
132 int s;
133 \&
134 \&...
135 \&
136 if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) {
137 /* Handle error */
138 }
139 \&
140 ts.tv_sec += 5;
141 \&
142 s = pthread_timedjoin_np(thread, NULL, &ts);
143 if (s != 0) {
144 /* Handle error */
145 }
146 .EE
147 .in
148 .SH SEE ALSO
149 .BR clock_gettime (2),
150 .BR pthread_exit (3),
151 .BR pthread_join (3),
152 .BR timespec (3),
153 .BR pthreads (7)