'\" et
.TH PTHREAD_JOIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
pthread_join
\(em wait for thread termination
.SH SYNOPSIS
.LP
.nf
#include <pthread.h>
.P
int pthread_join(pthread_t \fIthread\fP, void **\fIvalue_ptr\fP);
.fi
.SH DESCRIPTION
The
\fIpthread_join\fR()
function shall suspend execution of the calling thread until the target
.IR thread
terminates, unless the target
.IR thread
has already terminated. On return from a successful
\fIpthread_join\fR()
call with a non-NULL
.IR value_ptr
argument, the value passed to
\fIpthread_exit\fR()
by the terminating thread shall be made available in the location
referenced by
.IR value_ptr .
When a
\fIpthread_join\fR()
returns successfully, the target thread has been terminated. The
results of multiple simultaneous calls to
\fIpthread_join\fR()
specifying the same target thread are undefined. If the thread calling
\fIpthread_join\fR()
is canceled, then the target thread shall not be detached.
.P
It is unspecified whether a thread that has exited but remains unjoined
counts against
{PTHREAD_THREADS_MAX}.
.P
The behavior is undefined if the value specified by the
.IR thread
argument to
\fIpthread_join\fR()
does not refer to a joinable thread.
.P
The behavior is undefined if the value specified by the
.IR thread
argument to
\fIpthread_join\fR()
refers to the calling thread.
.SH "RETURN VALUE"
If successful, the
\fIpthread_join\fR()
function shall return zero; otherwise, an error number shall be
returned to indicate the error.
.SH ERRORS
The
\fIpthread_join\fR()
function may fail if:
.TP
.BR EDEADLK
A deadlock was detected.
.P
The
\fIpthread_join\fR()
function shall not return an error code of
.BR [EINTR] .
.LP
.IR "The following sections are informative."
.SH EXAMPLES
An example of thread creation and deletion follows:
.sp
.RS 4
.nf

typedef struct {
    int *ar;
    long n;
} subarray;
.P
void *
incer(void *arg)
{
    long i;
.P
    for (i = 0; i < ((subarray *)arg)->n; i++)
        ((subarray *)arg)->ar[i]++;
}
.P
int main(void)
{
    int        ar[1000000];
    pthread_t  th1, th2;
    subarray   sb1, sb2;
.P
    sb1.ar = &ar[0];
    sb1.n  = 500000;
    (void) pthread_create(&th1, NULL, incer, &sb1);
.P
    sb2.ar = &ar[500000];
    sb2.n  = 500000;
    (void) pthread_create(&th2, NULL, incer, &sb2);
.P
    (void) pthread_join(th1, NULL);
    (void) pthread_join(th2, NULL);
    return 0;
}
.fi
.P
.RE
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
The
\fIpthread_join\fR()
function is a convenience that has proven useful in multi-threaded
applications. It is true that a programmer could simulate this
function if it were not provided by passing extra state as part of the
argument to the
\fIstart_routine\fR().
The terminating thread would set a flag to indicate termination and
broadcast a condition that is part of that state; a joining thread
would wait on that condition variable. While such a technique would
allow a thread to wait on more complex conditions (for example, waiting
for multiple threads to terminate), waiting on individual thread
termination is considered widely useful. Also, including the
\fIpthread_join\fR()
function in no way precludes a programmer from coding such complex
waits. Thus, while not a primitive, including
\fIpthread_join\fR()
in this volume of POSIX.1\(hy2017 was considered valuable.
.P
The
\fIpthread_join\fR()
function provides a simple mechanism allowing an application to wait
for a thread to terminate. After the thread terminates, the
application may then choose to clean up resources that were used by the
thread. For instance, after
\fIpthread_join\fR()
returns, any application-provided stack storage could be reclaimed.
.P
The
\fIpthread_join\fR()
or
\fIpthread_detach\fR()
function should eventually be called for every thread that is created
with the
.IR detachstate
attribute set to PTHREAD_CREATE_JOINABLE
so that storage associated with the thread may be reclaimed.
.P
The interaction between
\fIpthread_join\fR()
and cancellation is well-defined for the following reasons:
.IP " *" 4
The
\fIpthread_join\fR()
function, like all other non-async-cancel-safe functions, can only be
called with
deferred cancelability type.
.IP " *" 4
Cancellation cannot occur in the disabled cancelability state.
.P
Thus, only the default cancelability state need be considered. As
specified, either the
\fIpthread_join\fR()
call is canceled, or it succeeds, but not both. The difference is
obvious to the application, since either a cancellation handler is run
or
\fIpthread_join\fR()
returns. There are no race conditions since
\fIpthread_join\fR()
was called in the deferred cancelability state.
.P
If an implementation detects that the value specified by the
.IR thread
argument to
\fIpthread_join\fR()
does not refer to a joinable thread, it is recommended that the
function should fail and report an
.BR [EINVAL] 
error.
.P
If an implementation detects that the value specified by the
.IR thread
argument to
\fIpthread_join\fR()
refers to the calling thread, it is recommended that the function
should fail and report an
.BR [EDEADLK] 
error.
.P
If an implementation detects use of a thread ID after the end of its
lifetime, it is recommended that the function should fail and report an
.BR [ESRCH] 
error.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIpthread_create\fR\^(\|)",
.IR "\fIwait\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.12" ", " "Memory Synchronization",
.IR "\fB<pthread.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .