Debian Codegraph @

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