pthread_join

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 ref-
       erenced 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  unde-
       fined.  If the thread calling pthread_join() is canceled, then the tar-
       get 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; other-
       wise, 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;


              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  simu-
       late  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 termi-
       nate),  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 primi-
       tive, 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  termi-
       nates,  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
       lability 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,  Copyright  (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.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                      PTHREAD_JOIN(P)