1.\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by John Birrell. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd October 12, 2021 32.Dt PTHREAD_JOIN 3 33.Os 34.Sh NAME 35.Nm pthread_join , 36.Nm pthread_peekjoin_np , 37.Nm pthread_timedjoin_np 38.Nm pthread_tryjoin_np 39.Nd inspect thread termination state 40.Sh LIBRARY 41.Lb libpthread 42.Sh SYNOPSIS 43.In pthread.h 44.Ft int 45.Fn pthread_join "pthread_t thread" "void **value_ptr" 46.In pthread_np.h 47.Ft int 48.Fo pthread_peekjoin_np 49.Fa "pthread_t thread" 50.Fa "void **value_ptr" 51.Fc 52.Ft int 53.Fo pthread_timedjoin_np 54.Fa "pthread_t thread" 55.Fa "void **value_ptr" 56.Fa "const struct timespec *abstime" 57.Fc 58.Ft int 59.Fn pthread_tryjoin_np "pthread_t thread" "void **value_ptr" 60.Sh DESCRIPTION 61The 62.Fn pthread_join 63function suspends execution of the calling thread until the target 64.Fa thread 65terminates unless the target 66.Fa thread 67has already terminated. 68.Pp 69On return from a successful 70.Fn pthread_join 71call with a non-NULL 72.Fa value_ptr 73argument, the value passed to 74.Fn pthread_exit 75by the terminating thread is stored in the location referenced by 76.Fa value_ptr . 77When a 78.Fn pthread_join 79returns successfully, the target thread has been terminated. 80The results 81of multiple simultaneous calls to 82.Fn pthread_join 83specifying the same target thread are undefined. 84If the thread calling 85.Fn pthread_join 86is cancelled, then the target thread is not detached. 87.Pp 88The 89.Fn pthread_timedjoin_np 90function is equivalent to the 91.Fn pthread_join 92function except it will return 93.Er ETIMEDOUT 94if target thread does not exit before specified absolute time passes. 95.Pp 96The 97.Fn pthread_peekjoin_np 98only peeks into the exit status of the specified thread. 99If the thread has not exited, the 100.Er EBUSY 101error is returned. 102Otherwise, zero is returned and the thread exit value is optionally stored 103into the location of 104.Fa *value_ptr . 105The target thread is left unjoined and can be used as an argument for 106the 107.Fn pthread_join 108family of functions again. 109.Pp 110The 111.Fn pthread_tryjoin_np 112function joins the thread if it is already terminated, same as 113.Fn pthread_join . 114If the thread has not yet terminated, the function returns 115.Er EBUSY . 116.Pp 117A thread that has exited but remains unjoined counts against 118[_POSIX_THREAD_THREADS_MAX]. 119.Sh RETURN VALUES 120If successful, the described functions return zero. 121Otherwise an error number is returned to indicate the error or 122special condition. 123.Sh ERRORS 124The 125.Fn pthread_join , 126.Fn pthread_peekjoin_np , 127and 128.Fn pthread_timedjoin_np 129functions will fail if: 130.Bl -tag -width Er 131.It Bq Er EINVAL 132The implementation has detected that the value specified by 133.Fa thread 134does not refer to a joinable thread. 135.It Bq Er ESRCH 136No thread could be found corresponding to that specified by the given 137thread ID, 138.Fa thread . 139.It Bq Er EDEADLK 140A deadlock was detected or the value of 141.Fa thread 142specifies the calling thread. 143.It Bq Er EOPNOTSUPP 144The implementation detected that another caller is already waiting on 145.Fa thread . 146.El 147.Pp 148Additionally, the 149.Fn pthread_timedjoin_np 150function will fail if: 151.Bl -tag -width Er 152.It Bq Er ETIMEDOUT 153The specified absolute time passed while 154.Fn pthread_timedjoin_np 155waited for thread exit. 156.El 157.Pp 158The 159.Fn pthread_peekjoin_np 160and 161.Fn pthread_tryjoin_np 162functions will also fail if: 163.Bl -tag -width Er 164.It Bq Er EBUSY 165The specified thread has not yet exited. 166.El 167.Sh SEE ALSO 168.Xr wait 2 , 169.Xr pthread 3 , 170.Xr pthread_create 3 , 171.Xr pthread_np 3 172.Sh STANDARDS 173The 174.Fn pthread_join 175function conforms to 176.St -p1003.1-96 . 177The 178.Fn pthread_timedjoin_np 179function is a 180.Fx 181extension which first appeared in 182.Fx 6.1 . 183The 184.Fn pthread_peekjoin_np 185function is a 186.Fx 187extension which first appearead in 188.Fx 13.0 . 189The 190.Fn pthread_tryjoin_np 191function is a 192.Fx 193extension which first appearead in 194.Fx 16.0 . 195