Provided by: manpages-posix-dev_2013a-2_all bug

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 .