PTHREAD_JOIN(3)        FreeBSD Library Functions Manual        PTHREAD_JOIN(3)

NAME

     pthread_join, pthread_peekjoin_np, pthread_timedjoin_np
     pthread_tryjoin_np - inspect thread termination state

LIBRARY

     POSIX Threads Library (libpthread, -lpthread)

SYNOPSIS

     #include <pthread.h>

     int
     pthread_join(pthread_t thread, void **value_ptr);

     #include <pthread_np.h>

     int
     pthread_peekjoin_np(pthread_t thread, void **value_ptr);

     int
     pthread_timedjoin_np(pthread_t thread, void **value_ptr,
         const struct timespec *abstime);

     int
     pthread_tryjoin_np(pthread_t thread, void **value_ptr);

DESCRIPTION

     The pthread_join() function suspends 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 is
     stored 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
     cancelled, then the target thread is not detached.

     The pthread_timedjoin_np() function is equivalent to the pthread_join()
     function except it will return ETIMEDOUT if target thread does not exit
     before specified absolute time passes.

     The pthread_peekjoin_np() only peeks into the exit status of the
     specified thread.  If the thread has not exited, the EBUSY error is
     returned.  Otherwise, zero is returned and the thread exit value is
     optionally stored into the location of *value_ptr.  The target thread is
     left unjoined and can be used as an argument for the pthread_join()
     family of functions again.

     The pthread_tryjoin_np() function joins the thread if it is already
     terminated, same as pthread_join().  If the thread has not yet
     terminated, the function returns EBUSY.

     A thread that has exited but remains unjoined counts against
     [_POSIX_THREAD_THREADS_MAX].

RETURN VALUES

     If successful, the described functions return zero.  Otherwise an error
     number is returned to indicate the error or special condition.

ERRORS

     The pthread_join(), pthread_peekjoin_np(), and pthread_timedjoin_np()
     functions will 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, thread.

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

     [EOPNOTSUPP]       The implementation detected that another caller is
                        already waiting on thread.

     Additionally, the pthread_timedjoin_np() function will fail if:

     [ETIMEDOUT]        The specified absolute time passed while
                        pthread_timedjoin_np() waited for thread exit.

     The pthread_peekjoin_np() and pthread_tryjoin_np() functions will also
     fail if:

     [EBUSY]            The specified thread has not yet exited.

SEE ALSO

     wait(2), pthread(3), pthread_create(3), pthread_np(3)

STANDARDS

     The pthread_join() function conforms to ISO/IEC 9945-1:1996 ("POSIX.1").
     The pthread_timedjoin_np() function is a FreeBSD extension which first
     appeared in FreeBSD 6.1.  The pthread_peekjoin_np() function is a FreeBSD
     extension which first appearead in FreeBSD 13.0.  The
     pthread_tryjoin_np() function is a FreeBSD extension which first
     appearead in FreeBSD 16.0.

FreeBSD 15.1-STABLE-HBSD       October 12, 2021                PTHREAD_JOIN(3)