PTHREAD_JOIN(3)

💅 PTHREAD_JOIN(3) — the "so what happened to my thread" page

okay bestie, this one lives in section 3 of the Library Functions Manual (that's the libpthread, linked with -lpthread), and it's literally all about checking whether your thread is done yet. group-chat energy only, but the facts are sacred, so let's go 🫶

---

✨ 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 💖

pthread_join()

so pthread_join() literally suspends the calling thread until the target thread terminates — unless the target thread already terminated, in which case it's not gonna make you wait for nothing 💅

when a pthread_join() call returns successfully and you passed a non-NULL value_ptr, the value that the terminating thread passed to pthread_exit() gets stored in the location value_ptr points at. so that's where the exit goodies live 🍓

when pthread_join() returns successfully, the target thread has been terminated. periodt.

⚠️ but bestie, heads up: the results of multiple simultaneous calls to pthread_join() that specify the same target thread are undefined. not "probably fine". undefined. don't do it 🙈

and if the thread calling pthread_join() gets cancelled, then the target thread is not detached. important detail, don't forget it.

pthread_timedjoin_np()

this one is equivalent to pthread_join() except it'll return ETIMEDOUT if the target thread doesn't exit before the specified absolute time passes ⏰ (yes, absolute. not a relative timeout. iykyk)

pthread_peekjoin_np()

the lowkey nosy one — it only peeks into the exit status of the specified thread 🔍

• if the thread hasn't exited, you get the EBUSY error back
• otherwise, zero is returned and the thread exit value is optionally stored into the location of *value_ptr

and the cute part: the target thread is left unjoined, so you can totally use it as an argument for the pthread_join() family of functions again 👑

pthread_tryjoin_np()

joins the thread if it's already terminated, same as pthread_join(). if the thread hasn't terminated yet, the function returns EBUSY ✨ (no waiting, no drama)

the one that'll bite you 🧚

a thread that has exited but remains unjoined counts against [_POSIX_THREAD_THREADS_MAX]. yes, counts. so like, clean up after yourself bestie, those zombie-ish unjoined threads are not the vibe 💀

🌈 RETURN VALUES 🌈

if successful, the described functions return zero. otherwise an error number gets returned to indicate the error or special condition. simple as that 🎀

🔥 ERRORS 🔥

pthread_join(), pthread_peekjoin_np(), and pthread_timedjoin_np() will fail if:

• [EINVAL] — the implementation detected that the value specified by thread does not refer to a joinable thread 🙃
• [ESRCH] — no thread could be found corresponding to the one specified by the given thread ID, thread 👻
• [EDEADLK] — a deadlock was detected, or the value of thread specifies the calling thread 😭 (yes, joining yourself. don't.)
• [EOPNOTSUPP] — the implementation detected that another caller is already waiting on thread 🙈

additionally, pthread_timedjoin_np() will fail if:

• [ETIMEDOUT] — the specified absolute time passed while pthread_timedjoin_np() waited for thread exit ⏰

and pthread_peekjoin_np() and pthread_tryjoin_np() 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 👑

• pthread_join() conforms to ISO/IEC 9945-1:1996 (“POSIX.1”) ⭐
• pthread_timedjoin_np() is a FreeBSD extension which first appeared in FreeBSD 6.1 🌸
• pthread_peekjoin_np() is a FreeBSD extension which first appeared in FreeBSD 13.0 🦋
• pthread_tryjoin_np() is a FreeBSD extension which first appeared in FreeBSD 16.0 🔥

---

okay that's the whole page, no notes 💅 this Debian build of the page is dated October 12, 2021, and honestly? iconic. go join your threads responsibly bestie, mwah 🎀✨