pthread_tryjoin_np(3)

1pthread_tryjoin_np(3)      Library Functions 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

LIBRARY

10       POSIX threads library (libpthread, -lpthread)
11

SYNOPSIS

13       #define _GNU_SOURCE             /* See feature_test_macros(7) */
14       #include <pthread.h>
15
16       int pthread_tryjoin_np(pthread_t thread, void **retval);
17       int pthread_timedjoin_np(pthread_t thread, void **retval,
18                                const struct timespec *abstime);
19

DESCRIPTION

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

RETURN VALUE

37       On  success,  these  functions return 0; on error, they return an error
38       number.
39

ERRORS

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

ATTRIBUTES

57       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
58       tributes(7).
59
60       ┌────────────────────────────────────────────┬───────────────┬─────────┐
61       │Interface                                   │ Attribute     │ Value   │
62       ├────────────────────────────────────────────┼───────────────┼─────────┤
63       │pthread_tryjoin_np(),                       │ Thread safety │ MT-Safe │
64       │pthread_timedjoin_np()                      │               │         │
65       └────────────────────────────────────────────┴───────────────┴─────────┘
66

STANDARDS

68       GNU; hence the suffix "_np" (nonportable) in the names.
69

HISTORY

71       glibc 2.3.3.
72

BUGS

74       The pthread_timedjoin_np() function measures time by internally  calcu‐
75       lating  a  relative  sleep  interval  that is then measured against the
76       CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock.  Consequent‐
77       ly, the timeout is unaffected by discontinuous changes to the CLOCK_RE‐
78       ALTIME clock.
79

EXAMPLES

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