.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_JOIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_join 
.SH NAME
pthread_join \- wait for thread termination
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_join(pthread_t\fP \fIthread\fP\fB, void **\fP\fIvalue_ptr\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_join\fP() function shall suspend execution of the calling
thread until the target \fIthread\fP terminates,
unless the target \fIthread\fP has already terminated. On return from
a successful \fIpthread_join\fP() call with a non-NULL
\fIvalue_ptr\fP argument, the value passed to \fIpthread_exit\fP()
by the
terminating thread shall be made available in the location referenced
by \fIvalue_ptr\fP. When a \fIpthread_join\fP() returns
successfully, the target thread has been terminated. The results of
multiple simultaneous calls to \fIpthread_join\fP() specifying
the same target thread are undefined. If the thread calling \fIpthread_join\fP()
is canceled, then the target thread shall not be
detached.
.LP
It is unspecified whether a thread that has exited but remains unjoined
counts against {PTHREAD_THREADS_MAX}.
.SH RETURN VALUE
.LP
If successful, the \fIpthread_join\fP() function shall return zero;
otherwise, an error number shall be returned to indicate
the error.
.SH ERRORS
.LP
The \fIpthread_join\fP() function shall fail if:
.TP 7
.B EINVAL
The implementation has detected that the value specified by \fIthread\fP
does not refer to a joinable thread.
.TP 7
.B ESRCH
No thread could be found corresponding to that specified by the given
thread ID.
.sp
.LP
The \fIpthread_join\fP() function may fail if:
.TP 7
.B EDEADLK
A deadlock was detected or the value of \fIthread\fP specifies the
calling thread.
.sp
.LP
The \fIpthread_join\fP() function shall not return an error code of
[EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
An example of thread creation and deletion follows:
.sp
.RS
.nf

\fBtypedef struct {
    int *ar;
    long n;
} subarray;
.sp

void *
incer(void *arg)
{
    long i;
.sp

    for (i = 0; i < ((subarray *)arg)->n; i++)
        ((subarray *)arg)->ar[i]++;
}
.sp

int main(void)
{
    int        ar[1000000];
    pthread_t  th1, th2;
    subarray   sb1, sb2;
.sp

    sb1.ar = &ar[0];
    sb1.n  = 500000;
    (void) pthread_create(&th1, NULL, incer, &sb1);
.sp

    sb2.ar = &ar[500000];
    sb2.n  = 500000;
    (void) pthread_create(&th2, NULL, incer, &sb2);
.sp

    (void) pthread_join(th1, NULL);
    (void) pthread_join(th2, NULL);
    return 0;
}
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
The \fIpthread_join\fP() 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\fP(). 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\fP() function in
no way precludes a programmer from coding such complex waits.
Thus, while not a primitive, including \fIpthread_join\fP() in this
volume of IEEE\ Std\ 1003.1-2001 was considered
valuable.
.LP
The \fIpthread_join\fP() 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\fP() returns, any application-provided stack storage
could be reclaimed.
.LP
The \fIpthread_join\fP() or \fIpthread_detach\fP() function should
eventually
be called for every thread that is created with the \fIdetachstate\fP
attribute set to PTHREAD_CREATE_JOINABLE so that storage
associated with the thread may be reclaimed.
.LP
The interaction between \fIpthread_join\fP() and cancellation is well-defined
for the following reasons:
.IP " *" 3
The \fIpthread_join\fP() function, like all other non-async-cancel-safe
functions, can only be called with deferred
cancelability type.
.LP
.IP " *" 3
Cancellation cannot occur in the disabled cancelability state.
.LP
.LP
Thus, only the default cancelability state need be considered. As
specified, either the \fIpthread_join\fP() 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\fP() returns. There are no race conditions since \fIpthread_join\fP()
was called in the deferred cancelability
state.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_create\fP() , \fIwait\fP() , the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .