THR_SUSPEND(2)

💤 THR_SUSPEND — the THR_SUSPEND(2) page, but make it make sense ✨

okay bestie, we're in the System Calls Manual section, section 2, and this one's called thr_suspend. it's giving "put yourself to sleep and hope somebody wakes you up." let's get into it 💅

---

🌸 NAME 🌸

thr_suspend — suspend the calling thread

like. literally the thread that calls this is the one that goes night-night. no passing it off to somebody else. main character only 🫶

---

🎀 LIBRARY 🎀

Standard C Library (libc, -lc)

so you link it with -lc, standard stuff, no cap.

---

✨ SYNOPSIS ✨

#include <sys/thr.h>

int
thr_suspend(struct timespec *timeout);

one include, one function, one pointer argument. clean. iconic. 🌈

---

💖 DESCRIPTION 💖

okay so first things first, and this is important: this function is intended for implementing threading. that's the whole vibe. it's a building block, not a hangout spot for your regular app code.

Normal applications should use pthread_cond_timedwait(3) together with pthread_cond_broadcast(3) for typical safe suspension — with the cooperation of the thread being suspended, bestie, that's the key part — or pthread_suspend_np(3) and pthread_resume_np(3) in some specific situations, instead. so like, if you're just some app: those are your girls. not this. 🙈

so what does thr_suspend() actually do? it puts the calling thread in a suspended state, where it is not eligible for CPU time. the scheduler literally stops looking at it. it's off the grid. 💀

and this state is exited by any one of these three things:

1. another thread calling thr_wake(2) 🫶
2. the time interval specified by timeout elapsing ⏰
3. the delivery of a signal to the suspended thread 📬

now, if the timeout argument is NULL, then the suspended state can be only terminated by an explicit thr_wake() or a signal. no timer. no automatic rescue. you're waiting on a friend or a signal, periodt.

here's a cute little edge case for you: if a wake from thr_wake(2) was delivered before the thr_suspend call, the thread is not put into a suspended state. instead, the call returns immediately without an error. so the wake doesn't get lost, it just gets used up early. considerate tbh ✨

and another one, okay, stay with me: if a thread previously called thr_wake(2) with its own thread identifier, which resulted in setting the internal kernel flag to immediately abort interruptible sleeps with an EINTR error (see thr_wake(2) — go read it, iykyk), then that flag is cleared. and just like with thr_wake(2) called from another thread, the next thr_suspend call does not result in suspension. so your first suspend after that? it's a no-op, bestie. it's giving "just checking in." 😭

---

🦋 RETURN VALUES 🦋

thr_suspend() returns the value 0 if successful. slay. otherwise the value -1 is returned and the global variable errno is set to indicate the error. so always check your errno, she's the one with the tea ☕

---

🔥 ERRORS 🔥

the thr_suspend() operation returns the following errors:

• [EFAULT] — the memory pointed to by the timeout argument is not valid. like, that pointer is pointing at vibes, not memory. 💀
• [ETIMEDOUT] — the specified timeout expired.
• [ETIMEDOUT] — the timeout argument specified a zero time interval. yep, same error name, different cause, and honestly? iconic of it. don't @ me.
• [EINTR] — the sleep was interrupted by a signal. 📬 rude but legal.

---

🌈 SEE ALSO 🌈

ps(1), thr_wake(2), pthread_resume_np(3), pthread_suspend_np(3)

go read thr_wake(2) next, fr fr, it's the other half of this whole situationship.

---

👑 STANDARDS 👑

the thr_suspend() system call is non-standard. so don't go expecting this on every system, bestie. it's a niche queen. 💅

---

and that's the whole page!! this little beauty comes to you from Debian, dated September 23, 2016 — yes she's a 2016 girlie and she's still serving 🎀 sleep well, don't forget to get woken up 🫶✨