pthread_tryjoin_np(3)

💖 pthread_tryjoin_np — bestie, let's try to join a thread 🧵✨

okay so real talk: this page is from the Library Functions Manual, section 3, and it's all about the two functions that are like pthread_join(3) but with ✨plot twists✨. One of them doesn't wait at all, and the other one has a deadline. Iconic behavior honestly.

---

🌸 NAME 🌸

pthread_tryjoin_np, pthread_timedjoin_np — try to join with a terminated thread 🫶

---

🎀 LIBRARY 🎀

POSIX threads library — you're linking libpthread, so that's -lpthread babes 💅

---

✨ SYNOPSIS ✨

#define _GNU_SOURCE             /* See feature_test_macros(7) */
#include <pthread.h>

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

not me casually dropping _GNU_SOURCE at the top like it's a personality trait 😭 you literally need it, bestie, go read feature_test_macros(7) if you wanna know why.

---

💜 DESCRIPTION 💜

So these two cuties work exactly like pthread_join(3) — same energy, same vibe — except for the differences we're about to spill on this very page. That's it. That's the whole deal. 🙈

pthread_tryjoin_np()</p> does a nonblocking join with thread, and hands you the thread's exit status in *retval. The key thing: if thread hasn't terminated yet, it does NOT sit there blocking like pthread_join(3) would. Nope. It just returns an error and moves on with its life. Main character energy, honestly. 💅

pthread_timedjoin_np()</p> is the join-with-timeout girlie. If thread hasn't terminated yet, the call blocks — but only for a maximum time, which you specify in abstime, measured against the CLOCK_REALTIME clock. If the timeout expires before thread terminates, the call returns an error. The abstime argument is a timespec(3) structure, and it specifies an absolute time measured since the Epoch (go peek at time(2) for that). ⏰

---

🌈 RETURN VALUE 🌈

On success, these functions return 0. On error, they return an error number. no cap, that's the whole story 🍓

---

🔥 ERRORS 🔥

These functions can fail with the same errors as pthread_join(3). But wait — there's more 💀

pthread_tryjoin_np() can in addition fail with:

• EBUSY — thread had not yet terminated at the time of the call. she said "not now, I'm busy" 😭

pthread_timedjoin_np() can in addition fail with:

• EINVAL — abstime value is invalid (tv_sec is less than 0 or tv_nsec is greater than 1e9). bestie that timespec is giving "illegal" ✋
• ETIMEDOUT — The call timed out before thread terminated. the clock ran out, it's over 😔

and one more lil fact for you: pthread_timedjoin_np() never returns the error EINTR. never ever. periodt. 👑

---

👑 ATTRIBUTES 👑

For an explanation of the terms used in this section, go see attributes(7) — it's giving homework but it's short, I promise 🎓

• pthread_tryjoin_np(), pthread_timedjoin_np() — Thread safety: MT-Safe 🌟

---

🦋 STANDARDS 🦋

GNU — and that's why the names have the suffix _np in them, which stands for nonportable. so like, it's cute but it does not travel ✈️💔

---

⭐ HISTORY ⭐

glibc 2.3.3. — an elder. a legend. we stan a vintage icon 👵✨

---

💀 BUGS 💀

okay listen up, this part is important, do not skip it:

The pthread_timedjoin_np() function measures time by internally calculating a relative sleep interval that is then measured against the CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock.

Consequently, the timeout is unaffected by discontinuous changes to the CLOCK_REALTIME clock. so yeah, plot twist: you asked for CLOCK_REALTIME but the timeout math is lowkey mono-time. the more you know 🌈

---

🧚 EXAMPLES 🧚

The following code waits to join for up to 5 seconds — here's the moment you've all been waiting for:

struct timespec ts;
int s;

...

if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
    /* Handle error */
}

ts.tv_sec += 5;

s = pthread_timedjoin_np(thread, NULL, &ts);
if (s != 0) {
    /* Handle error */
}

see? five seconds. grab the time, add 5, send it. slay 🔥

---

💖 SEE ALSO 💖

• clock_gettime(2)
• pthread_exit(3)
• pthread_join(3)
• timespec(3)
• pthreads(7)

---

and that's the whole page bestie!! this was brought to you by Linux man-pages 6.20, dated 2025-05-17, and the original title line was pthread_tryjoin_np(3) from the Library Functions Manual — mwah, go join some threads responsibly 🫶💅✨