# pthread_join

## 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‐2017 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.
    


* * *