pthread_tryjoin_np(3)

1PTHREAD_TRYJOIN_NP(3)      Linux Programmer's Manual     PTHREAD_TRYJOIN_NP(3)
2
3
4

NAME

6       pthread_tryjoin_np,  pthread_timedjoin_np  -  try to join with a termi‐
7       nated thread
8

SYNOPSIS

10       #define _GNU_SOURCE             /* See feature_test_macros(7) */
11       #include <pthread.h>
12
13       int pthread_tryjoin_np(pthread_t thread, void **retval);
14       int pthread_timedjoin_np(pthread_t thread, void **retval,
15                                const struct timespec *abstime);
16
17       Compile and link with -pthread.
18

DESCRIPTION

20       These functions operate in the same way as pthread_join(3), except  for
21       the differences described on this page.
22
23       The  pthread_tryjoin_np() function performs a nonblocking join with the
24       thread thread, returning the exit status of the thread in *retval.   If
25       thread  has not yet terminated, then instead of blocking, as is done by
26       pthread_join(3), the call returns an error.
27
28       The pthread_timedjoin_np() function performs a  join-with-timeout.   If
29       thread  has  not  yet  terminated, then the call blocks until a maximum
30       time, specified in abstime, measured against the CLOCK_REALTIME  clock.
31       If  the  timeout  expires before thread terminates, the call returns an
32       error.  The abstime argument is a  structure  of  the  following  form,
33       specifying an absolute time measured since the Epoch (see time(2)):
34
35           struct timespec {
36               time_t tv_sec;     /* seconds */
37               long   tv_nsec;    /* nanoseconds */
38           };
39

RETURN VALUE

41       On  success,  these  functions return 0; on error, they return an error
42       number.
43

ERRORS

45       These functions can fail  with  the  same  errors  as  pthread_join(3).
46       pthread_tryjoin_np() can in addition fail with the following error:
47
48       EBUSY  thread had not yet terminated at the time of the call.
49
50       pthread_timedjoin_np() can in addition fail with the following errors:
51
52       ETIMEDOUT
53              The call timed out before thread terminated.
54
55       EINVAL abstime  value  is  invalid (tv_sec is less than 0 or tv_nsec is
56              greater than 1e9).
57
58       pthread_timedjoin_np() never returns the error EINTR.
59

VERSIONS

61       These functions first appeared in glibc in version 2.3.3.
62

ATTRIBUTES

64       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
65       tributes(7).
66
67       ┌────────────────────────────────────────────┬───────────────┬─────────┐
68       │Interface                                   │ Attribute     │ Value   │
69       ├────────────────────────────────────────────┼───────────────┼─────────┤
70       │pthread_tryjoin_np(),                       │ Thread safety │ MT-Safe │
71       │pthread_timedjoin_np()                      │               │         │
72       └────────────────────────────────────────────┴───────────────┴─────────┘
73

CONFORMING TO

75       These functions are nonstandard GNU extensions; hence the suffix  "_np"
76       (nonportable) in the names.
77

EXAMPLES

79       The following code waits to join for up to 5 seconds:
80
81           struct timespec ts;
82           int s;
83
84           ...
85
86           if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
87               /* Handle error */
88           }
89
90           ts.tv_sec += 5;
91
92           s = pthread_timedjoin_np(thread, NULL, &ts);
93           if (s != 0) {
94               /* Handle error */
95           }
96

BUGS

98       The  pthread_timedjoin_np() function measures time by internally calcu‐
99       lating a relative sleep interval that  is  then  measured  against  the
100       CLOCK_MONOTONIC  clock  instead  of  the  CLOCK_REALTIME clock.  Conse‐
101       quently, the timeout is unaffected  by  discontinuous  changes  to  the
102       CLOCK_REALTIME clock.
103

COLOPHON

108       This  page  is  part of release 5.12 of the Linux man-pages project.  A
109       description of the project, information about reporting bugs,  and  the
110       latest     version     of     this    page,    can    be    found    at
111       https://www.kernel.org/doc/man-pages/.
112
113
114
115Linux                             2021-03-22             PTHREAD_TRYJOIN_NP(3)