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.Nd inspect thread termination state 39.Sh LIBRARY 40.Lb libpthread 41.Sh SYNOPSIS 42.In pthread.h 43.Ft int 44.Fn pthread_join "pthread_t thread" "void **value_ptr" 45.In pthread_np.h 46.Ft int 47.Fo pthread_peekjoin_np 48.Fa "pthread_t thread" 49.Fa "void **value_ptr" 50.Fc 51.Ft int 52.Fo pthread_timedjoin_np 53.Fa "pthread_t thread" 54.Fa "void **value_ptr" 55.Fa "const struct timespec *abstime" 56.Fc 57.Sh DESCRIPTION 58The 59.Fn pthread_join 60function suspends execution of the calling thread until the target 61.Fa thread 62terminates unless the target 63.Fa thread 64has already terminated. 65.Pp 66On return from a successful 67.Fn pthread_join 68call with a non-NULL 69.Fa value_ptr 70argument, the value passed to 71.Fn pthread_exit 72by the terminating thread is stored in the location referenced by 73.Fa value_ptr . 74When a 75.Fn pthread_join 76returns successfully, the target thread has been terminated. 77The results 78of multiple simultaneous calls to 79.Fn pthread_join 80specifying the same target thread are undefined. 81If the thread calling 82.Fn pthread_join 83is cancelled, then the target thread is not detached. 84.Pp 85The 86.Fn pthread_timedjoin_np 87function is equivalent to the 88.Fn pthread_join 89function except it will return 90.Er ETIMEDOUT 91if target thread does not exit before specified absolute time passes. 92.Pp 93The 94.Fn pthread_peekjoin_np 95only peeks into the exit status of the specified thread. 96If the thread has not exited, the 97.Er EBUSY 98error is returned. 99Otherwise, zero is returned and the thread exit value is optionally stored 100into the location of 101.Fa *value_ptr . 102The target thread is left unjoined and can be used as an argument for 103the 104.Fn pthread_join 105family of functions again. 106.Pp 107A thread that has exited but remains unjoined counts against 108[_POSIX_THREAD_THREADS_MAX]. 109.Sh RETURN VALUES 110If successful, the described functions return zero. 111Otherwise an error number is returned to indicate the error or 112special condition. 113.Sh ERRORS 114The 115.Fn pthread_join , 116.Fn pthread_peekjoin_np , 117and 118.Fn pthread_timedjoin_np 119functions will fail if: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122The implementation has detected that the value specified by 123.Fa thread 124does not refer to a joinable thread. 125.It Bq Er ESRCH 126No thread could be found corresponding to that specified by the given 127thread ID, 128.Fa thread . 129.It Bq Er EDEADLK 130A deadlock was detected or the value of 131.Fa thread 132specifies the calling thread. 133.It Bq Er EOPNOTSUPP 134The implementation detected that another caller is already waiting on 135.Fa thread . 136.El 137.Pp 138Additionally, the 139.Fn pthread_timedjoin_np 140function will fail if: 141.Bl -tag -width Er 142.It Bq Er ETIMEDOUT 143The specified absolute time passed while 144.Fn pthread_timedjoin_np 145waited for thread exit. 146.El 147.Pp 148The 149.Fn pthread_peekjoin_np 150function will also fail if: 151.Bl -tag -width Er 152.It Bq Er EBUSY 153The specified thread has not yet exited. 154.El 155.Sh SEE ALSO 156.Xr wait 2 , 157.Xr pthread 3 , 158.Xr pthread_create 3 , 159.Xr pthread_np 3 160.Sh STANDARDS 161The 162.Fn pthread_join 163function conforms to 164.St -p1003.1-96 . 165The 166.Fn pthread_timedjoin_np 167function is a 168.Fx 169extension which first appeared in 170.Fx 6.1 . 171Another extension, the 172.Fn pthread_peekjoin_np 173function, first appearead in 174.Fx 13.0 . 175