pthread_join()--Wait for and Detach Thread

 #include <pthread.h>
 int pthread_join(pthread_t thread, void **status); 

The pthread_join() function waits for a thread to terminate, detaches the thread, then returns the threads exit status.

If the status parameter is NULL, the threads exit status is not returned.

The meaning of the threads exit status (value returned to the status memory location) is determined by the application, except for the following conditions:

1. When the thread has been canceled using pthread_cancel(), the exit status of PTHREAD_CANCELED is made available.
2. When the thread has been terminated as a result of an unhandled i5/OS exception, operator intervention or other proprietary i5/OS mechanism, the exit status of PTHREAD_EXCEPTION_NP is made available.

Eventually, you should call pthread_join(), pthread_detach() or pthread_extendedjoin_np() without specifying the leaveThreadAllocated option for every thread that is created joinable (with a detach state of PTHREAD_CREATE_JOINABLE) so that the system can reclaim all resources associated with the thread. Failure to join to or detach joinable threads causes memory and other resource leaks until the process ends.

Authorities and Locks

None.

Parameters

thread

(Input) Pthread handle to the target thread

status

(Output) Address of the variable to receive the thread's exit status

Return Value

0

pthread_join() was successful.

value

pthread_join() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_join() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[ESRCH]

The thread specified could not be found.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_detach()--Detach Thread
  
  
• pthread_exit()--Terminate Calling Thread
  
  
• pthread_extendedjoin_np()--Wait for Thread with Extended Options
  
  
• pthread_join_np()--Wait for Thread to End

Example

See Code disclaimer information for information pertaining to code examples.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

int  okStatus        = 34;

void *threadfunc(void *parm)
{
  printf("Inside secondary thread\n");
  return __VOID(okStatus);
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;
  void                 *status;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Create thread using attributes that allow join\n");
  rc = pthread_create(&thread, NULL, threadfunc, NULL);
  checkResults("pthread_create()\n", rc);

  printf("Wait for the thread to exit\n");
  rc = pthread_join(thread, &status);
  checkResults("pthread_join()\n", rc);
  if (__INT(status) != okStatus) {
    printf("Secondary thread failed\n");
    exit(1);
  }

  printf("Got secondary thread status as expected\n");
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPJOIN0
Create thread using attributes that allow join
Wait for the thread to exit
Inside secondary thread
Got secondary thread status as expected
Main completed