Provided by: manpages-posix-dev_2013a-2_all 
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.
NAME
pthread_join — wait for thread termination
SYNOPSIS
#include <pthread.h>
int pthread_join(pthread_t thread, void **value_ptr);
DESCRIPTION
The pthread_join() function shall suspend execution of the calling thread until the target
thread terminates, unless the target thread has already terminated. On return from a
successful pthread_join() call with a non-NULL value_ptr argument, the value passed to
pthread_exit() by the terminating thread shall be made available in the location
referenced by value_ptr. When a pthread_join() returns successfully, the target thread
has been terminated. The results of multiple simultaneous calls to pthread_join()
specifying the same target thread are undefined. If the thread calling pthread_join() is
canceled, then the target thread shall not be detached.
It is unspecified whether a thread that has exited but remains unjoined counts against
{PTHREAD_THREADS_MAX}.
The behavior is undefined if the value specified by the thread argument to pthread_join()
does not refer to a joinable thread.
The behavior is undefined if the value specified by the thread argument to pthread_join()
refers to the calling thread.
RETURN VALUE
If successful, the pthread_join() function shall return zero; otherwise, an error number
shall be returned to indicate the error.
ERRORS
The pthread_join() function may fail if:
EDEADLK
A deadlock was detected.
The pthread_join() function shall not return an error code of [EINTR].
The following sections are informative.
EXAMPLES
An example of thread creation and deletion follows:
typedef struct {
int *ar;
long n;
} subarray;
void *
incer(void *arg)
{
long i;
for (i = 0; i < ((subarray *)arg)->n; i++)
((subarray *)arg)->ar[i]++;
}
int main(void)
{
int ar[1000000];
pthread_t th1, th2;
subarray sb1, sb2;
sb1.ar = &ar[0];
sb1.n = 500000;
(void) pthread_create(&th1, NULL, incer, &sb1);
sb2.ar = &ar[500000];
sb2.n = 500000;
(void) pthread_create(&th2, NULL, incer, &sb2);
(void) pthread_join(th1, NULL);
(void) pthread_join(th2, NULL);
return 0;
}
APPLICATION USAGE
None.
RATIONALE
The pthread_join() 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 start_routine(). 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 pthread_join() function in no way precludes a
programmer from coding such complex waits. Thus, while not a primitive, including
pthread_join() in this volume of POSIX.1‐2008 was considered valuable.
The pthread_join() 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 pthread_join()
returns, any application-provided stack storage could be reclaimed.
The pthread_join() or pthread_detach() function should eventually be called for every
thread that is created with the detachstate attribute set to PTHREAD_CREATE_JOINABLE so
that storage associated with the thread may be reclaimed.
The interaction between pthread_join() and cancellation is well-defined for the following
reasons:
* The pthread_join() function, like all other non-async-cancel-safe functions, can only
be called with deferred cancelability type.
* Cancellation cannot occur in the disabled cancelability state.
Thus, only the default cancelability state need be considered. As specified, either the
pthread_join() call is canceled, or it succeeds, but not both. The difference is obvious
to the application, since either a cancellation handler is run or pthread_join() returns.
There are no race conditions since pthread_join() was called in the deferred cancelability
state.
If an implementation detects that the value specified by the thread argument to
pthread_join() does not refer to a joinable thread, it is recommended that the function
should fail and report an [EINVAL] error.
If an implementation detects that the value specified by the thread argument to
pthread_join() refers to the calling thread, it is recommended that the function should
fail and report an [EDEADLK] error.
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 [ESRCH] error.
FUTURE DIRECTIONS
None.
SEE ALSO
pthread_create(), wait()
The Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory Synchronization,
<pthread.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .
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 .