PTHREAD_JOIN(3C) Standard C Library Functions PTHREAD_JOIN(3C)
NAME
pthread_join - wait for thread termination
SYNOPSIS
cc -mt [
flag... ]
file... -lpthread [
library... ]
#include <pthread.h>
int pthread_join(
pthread_t thread,
void **status);
DESCRIPTION
The
pthread_join() function suspends processing of the calling thread
until the target
thread completes.
thread must be a member of the
current process and it cannot be a detached thread. See
pthread_create(3C).
If two or more threads wait for the same thread to complete, all will
suspend processing until the thread has terminated, and then one
thread will return successfully and the others will return with an
error of
ESRCH. The
pthread_join() function will not block processing
of the calling thread if the target
thread has already terminated.
If a
pthread_join() call returns successfully with a non-null
status argument, the value passed to
pthread_exit(3C) by the terminating
thread will be placed in the location referenced by
status.
If the
pthread_join() calling thread is cancelled, then the target
thread will remain joinable by
pthread_join(). However, the calling
thread may set up a cancellation cleanup handler on
thread prior to
the join call, which may detach the target
thread by calling
pthread_detach(3C). See
pthread_detach(3C) and
pthread_cancel(3C).
RETURN VALUES
If successful,
pthread_join() returns
0. Otherwise, an error number
is returned to indicate the error.
ERRORS
EDEADLK A joining deadlock would occur, such as when a thread
attempts to wait for itself.
EINVAL The thread corresponding to the given thread ID is a
detached thread.
ESRCH No thread could be found corresponding to the given thread
ID.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
pthread_cancel(3C),
pthread_create(3C),
pthread_detach(3C),
pthread_exit(3C),
wait(3C),
attributes(7),
standards(7)NOTES
The
pthread_join(3C) function must specify the
thread ID for whose
termination it will wait.
Calling
pthread_join() also "detaches" the thread; that is,
pthread_join() includes the effect of the
pthread_detach() function.
If a thread were to be cancelled when blocked in
pthread_join(), an
explicit detach would have to be performed in the cancellation
cleanup handler. The
pthread_detach() function exists primarily for
this purpose.
March 23, 2005 PTHREAD_JOIN(3C)
