---
name: "pthread_join"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/pthread_join"
---

# pthread\_join(3)

inspect thread termination state

## 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)](/wait/2.md), [pthread(3)](/pthread/3.md), [pthread\_create(3)](/pthread_create/3.md), [pthread\_np(3)](/pthread_np/3.md)

## 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.