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