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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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}.

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 shall fail if:

       EINVAL The implementation has detected that the value specified by thread does not refer to a joinable thread.

       ESRCH  No thread could be found corresponding to that specified by the given thread ID.


       The pthread_join() function may fail if:

       EDEADLK
              A deadlock was detected or the value of thread specifies the calling thread.


       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
       IEEE Std 1003.1-2001 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 cancela-
          bility 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread_create(), wait(), the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                              PTHREAD_JOIN(3P)