PTHREAD_JOIN(3)            POSIX Programmer's Manual           PTHREAD_JOIN(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       pthread_join -- wait for thread termination

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_join(pthread_t _t_h_r_e_a_d, void **_v_a_l_u_e___p_t_r);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___j_o_i_n() function shall suspend execution of the calling
       thread until the target _t_h_r_e_a_d terminates, unless the target _t_h_r_e_a_d has
       already terminated. On return from a successful _p_t_h_r_e_a_d___j_o_i_n() call
       with a non-NULL _v_a_l_u_e___p_t_r argument, the value passed to _p_t_h_r_e_a_d___e_x_i_t()
       by the terminating thread shall be made available in the location
       referenced by _v_a_l_u_e___p_t_r.  When a _p_t_h_r_e_a_d___j_o_i_n() returns successfully,
       the target thread has been terminated. The results of multiple
       simultaneous calls to _p_t_h_r_e_a_d___j_o_i_n() specifying the same target thread
       are undefined. If the thread calling _p_t_h_r_e_a_d___j_o_i_n() 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 _t_h_r_e_a_d argument
       to _p_t_h_r_e_a_d___j_o_i_n() does not refer to a joinable thread.

       The behavior is undefined if the value specified by the _t_h_r_e_a_d argument
       to _p_t_h_r_e_a_d___j_o_i_n() refers to the calling thread.

RREETTUURRNN VVAALLUUEE
       If successful, the _p_t_h_r_e_a_d___j_o_i_n() function shall return zero;
       otherwise, an error number shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___j_o_i_n() function may fail if:

       EEDDEEAADDLLKK
              A deadlock was detected.

       The _p_t_h_r_e_a_d___j_o_i_n() function shall not return an error code of [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       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;
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       The _p_t_h_r_e_a_d___j_o_i_n() 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 _s_t_a_r_t___r_o_u_t_i_n_e().  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 _p_t_h_r_e_a_d___j_o_i_n() function in no way
       precludes a programmer from coding such complex waits. Thus, while not
       a primitive, including _p_t_h_r_e_a_d___j_o_i_n() in this volume of POSIX.1-2017
       was considered valuable.

       The _p_t_h_r_e_a_d___j_o_i_n() 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 _p_t_h_r_e_a_d___j_o_i_n() returns,
       any application-provided stack storage could be reclaimed.

       The _p_t_h_r_e_a_d___j_o_i_n() or _p_t_h_r_e_a_d___d_e_t_a_c_h() function should eventually be
       called for every thread that is created with the _d_e_t_a_c_h_s_t_a_t_e attribute
       set to PTHREAD_CREATE_JOINABLE so that storage associated with the
       thread may be reclaimed.

       The interaction between _p_t_h_r_e_a_d___j_o_i_n() and cancellation is well-defined
       for the following reasons:

        *  The _p_t_h_r_e_a_d___j_o_i_n() 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 _p_t_h_r_e_a_d___j_o_i_n() call is canceled, or it succeeds,
       but not both. The difference is obvious to the application, since
       either a cancellation handler is run or _p_t_h_r_e_a_d___j_o_i_n() returns. There
       are no race conditions since _p_t_h_r_e_a_d___j_o_i_n() was called in the deferred
       cancelability state.

       If an implementation detects that the value specified by the _t_h_r_e_a_d
       argument to _p_t_h_r_e_a_d___j_o_i_n() does not refer to a joinable thread, it is
       recommended that the function should fail and report an [[EEIINNVVAALL]] error.

       If an implementation detects that the value specified by the _t_h_r_e_a_d
       argument to _p_t_h_r_e_a_d___j_o_i_n() refers to the calling thread, it is
       recommended that the function should fail and report an [[EEDDEEAADDLLKK]]
       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
       [[EESSRRCCHH]] error.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_t_h_r_e_a_d___c_r_e_a_t_e(), _w_a_i_t()

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._1_2, _M_e_m_o_r_y
       _S_y_n_c_h_r_o_n_i_z_a_t_i_o_n, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       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 .



IEEE/The Open Group                  2017                      PTHREAD_JOIN(3)
