pthread_join(3T)               DG/UX R4.11MU05              pthread_join(3T)


NAME
       pthread_join - wait for thread termination

SYNOPSIS
       #include <pthread.h>

       int pthread_join(pthread_t thread, void **status);

   where:
       thread ID of the target thread whose termination to await
       status Pointer to the location to receive the target thread's exit
              status, or NULL if the target thread's exit status is not
              desired

DESCRIPTION
       The pthread_join() function suspends execution of the calling thread
       until the target thread terminates.  If the thread has already
       terminated, the calling thread returns immediately from the call to
       pthread_join().  When a pthread_join() call with a non-NULL status
       argument returns successfully, the value the terminating thread
       passed to pthread_exit() is made available in the location pointed to
       by status.

       In any case, when a pthread_join() call returns, the target thread
       has been detached.  Running pthread_join() on a detached target
       thread results in an immediate ESRCH error.  Multiple simultaneous
       calls to pthread_join() result in success for one and an ESRCH error
       for each of the others.  Which thread will succeed is undefined.

       If the thread calling pthread_join() is canceled, the target thread
       is not detached and the join is not consumed.

       If the thread calling pthread_join() is awakened to handle a signal,
       the join is not consumed before executing the signal handler.  Upon
       return the from the signal handler, the join is implicitly retried.
       Hence this call never returns EINTR.

DIAGNOSTICS
   Returns
       If successful, pthread_join() returns 0.  Otherwise it returns -1 and
       sets errno to indicate the error.

   Errors
       For each of the following conditions, pthread_join() returns -1 and
       sets errno to the corresponding value:

       [EINVAL]  The value specified by thread is invalid or denotes a
                 nonexistent thread.

       [ESRCH]   The value specified by thread refers to a detached thread.

       [EDEADLK] A deadlock was detected; the value of thread specifies the
                 calling thread.

SEE ALSO
       wait(2), pthread_create(3T), pthread_exit(3T).  pthread_detach(3T),
       pthread_attr_setdetachstate(3T),

NOTES
       The implementation is not required to check for other types of
       deadlocks besides trying to join oneself.  DG/UX only checks for this
       type of deadlock, as other types of checks would be too costly.
       Deadlocks are generally straightforward to debug.

       Once the target thread has exited and been detached, its ID should
       not be used.  Applications need to be particularly cautious about
       this, as the system reuses thread IDs across calls to
       pthread_create().  Failure to heed thread ID lifetimes can lead to
       unpredictable results.  In particular, the wrong thread could be
       manipulated.

       Creating a thread as detached using pthread_attr_setdetachstate() on
       an attributes object is more efficient than waiting for a thread to
       terminate with a call to pthread_join().

       If it is natural for an application to use pthread_join(), it is
       advised that only one thread join a particular target thread,
       otherwise the results can be unpredictable.


Licensed material--property of copyright holder(s)