man3/pthread_tryjoin_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_TRYJOIN_NP 3 2021-08-27 "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  91 .BR pthread_timedjoin_np ()
  92 never returns the error
  93 .BR EINTR .
  94 .SH VERSIONS
  95 These functions first appeared in glibc in version 2.3.3.
  96 .SH ATTRIBUTES
  97 For an explanation of the terms used in this section, see
  98 .BR attributes (7).
  99 .ad l
 100 .nh
 101 .TS
 102 allbox;
 103 lbx lb lb
 104 l l l.
 105 Interface       Attribute       Value
 106 T{
 107 .BR pthread_tryjoin_np (),
 108 .BR pthread_timedjoin_np ()
 109 T}      Thread safety   MT-Safe
 110 .TE
 111 .hy
 112 .ad
 113 .sp 1
 114 .SH STANDARDS
 115 These functions are nonstandard GNU extensions;
 116 hence the suffix "_np" (nonportable) in the names.
 117 .SH BUGS
 118 The
 119 .BR pthread_timedjoin_np ()
 120 function measures time by internally calculating a relative sleep interval
 121 that is then measured against the
 122 .B CLOCK_MONOTONIC
 123 clock instead of the
 124 .B CLOCK_REALTIME
 125 clock.
 126 Consequently, the timeout is unaffected by discontinuous changes to the
 127 .B CLOCK_REALTIME
 128 clock.
 129 .SH EXAMPLES
 130 The following code waits to join for up to 5 seconds:
 131 .PP
 132 .in +4n
 133 .EX
 134 struct timespec ts;
 135 int s;
 136
 137 \&...
 138
 139 if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) {
 140     /* Handle error */
 141 }
 142
 143 ts.tv_sec += 5;
 144
 145 s = pthread_timedjoin_np(thread, NULL, &ts);
 146 if (s != 0) {
 147     /* Handle error */
 148 }
 149 .EE
 150 .in
 151 .SH SEE ALSO
 152 .BR clock_gettime (2),
 153 .BR pthread_exit (3),
 154 .BR pthread_join (3),
 155 .BR timespec (3),
 156 .BR pthreads (7)