xref: /freebsd/share/man/man3/pthread_join.3 (revision 41466b50c1d5bfd1cf6adaae547a579a75d7c04e)
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.\" $FreeBSD$
32.\"
33.Dd April 4, 1996
34.Dt PTHREAD_JOIN 3
35.Os
36.Sh NAME
37.Nm pthread_join
38.Nd wait for thread termination
39.Sh LIBRARY
40.Lb libc_r
41.Sh SYNOPSIS
42.In pthread.h
43.Ft int
44.Fn pthread_join "pthread_t thread" "void **value_ptr"
45.Sh DESCRIPTION
46The
47.Fn pthread_join
48function suspends execution of the calling thread until the target
49.Fa thread
50terminates unless the target
51.Fa thread
52has already terminated.
53.Pp
54On return from a successful
55.Fn pthread_join
56call with a non-NULL
57.Fa value_ptr
58argument, the value passed to
59.Fn pthread_exit
60by the terminating thread is stored in the location referenced by
61.Fa value_ptr .
62When a
63.Fn pthread_join
64returns successfully, the target thread has been terminated.
65The results
66of multiple simultaneous calls to
67.Fn pthread_join
68specifying the same target thread are undefined.
69If the thread calling
70.Fn pthread_join
71is cancelled, then the target thread is not detached.
72.Pp
73A thread that has exited but remains unjoined counts against
74[_POSIX_THREAD_THREADS_MAX].
75.Sh RETURN VALUES
76If successful,  the
77.Fn pthread_join
78function will return zero.
79Otherwise an error number will be returned to
80indicate the error.
81.Sh ERRORS
82.Fn pthread_join
83will fail if:
84.Bl -tag -width Er
85.It Bq Er EINVAL
86The implementation has detected that the value specified by
87.Fa thread
88does not refer to a joinable thread.
89.It Bq Er ESRCH
90No thread could be found corresponding to that specified by the given
91thread ID,
92.Fa thread .
93.It Bq Er EDEADLK
94A deadlock was detected or the value of
95.Fa thread
96specifies the calling thread.
97.El
98.Sh SEE ALSO
99.Xr wait 2 ,
100.Xr pthread_create 3
101.Sh STANDARDS
102.Fn pthread_join
103conforms to
104.St -p1003.1-96 .
105