KPAUSE(9)

💤 KPAUSE(9) — the kernel dev manual, bestie edition 💤

okay so real talk: this is a page from the Kernel Developer's Manual (KPAUSE(9), section 9, kernel-land only, no userland girlies allowed) and it's literally just about making the calling LWP take a lil nap 😴✨

---

✨ NAME ✨

kpause — make the calling LWP sleep 🛌💤

---

🌸 SYNOPSIS 🌸

#include <sys/proc.h>

int
kpause(const char *wmesg, bool intr, int timeo, kmutex_t *mtx);

---

🦋 DESCRIPTION 🦋

kpause() makes the calling LWP sleep. no cap, that's the whole vibe. it's similar to cv_timedwait_sig(9) but without the matching cv_signal(9) — so like, there's nobody out here sending you a wake-up text, you just gotta wake up on your own 💅

heads up bestie: kpause() can wake up spontaneously. so callers, please prepare to handle that. it's giving unpredictable friend who shows up unannounced 🫶

• wmesg — a string, no more than 8 characters, describing the resource or condition this call of kpause() is about. the kernel doesn't actually use this argument directly, it just makes it available so utilities like ps(1) can display it. it's basically the little status message in your bio, iykyk 🎀
• intr — if true, sleep interruptably. if the LWP receives a signal, or gets interrupted by another condition — like its containing process exiting — the wait ends early and an error code gets returned. so like, the nap can be cancelled 😭
• timeo — specify a timeout. this is an architecture and system dependent value related to the number of clock interrupts per second. see hz(9) for the tea ☕ the mstohz(9) macro can convert a timeout expressed in milliseconds into one that's actually suitable for kpause(). very slay of it.

Zero means no timeout. literally forever nap energy 🌙

• mtx — convenience and symmetry with other synchronization operations 🎀 if it's not NULL, mtx will be released once the LWP has prepared to sleep, and will be reacquired before kpause() returns. so it lets go and then picks it back up. iconic mutual exclusion behaviour, no notes 👑

---

⭐ RETURN VALUES ⭐

kpause() returns 0 when it wakes up spontaneously. otherwise, it returns an error number. that's it, that's the contract 💖

---

💀 ERRORS 💀

• [EINTR] — kpause() returned due to other reasons. typically as a result of a signal without the SA_RESTART property. the nap got interrupted fr fr 🙈
• [ERESTART] — kpause() returned as a result of a signal with the SA_RESTART property. so it's coming right back around 🔁
• [EWOULDBLOCK] — the timeout expired. time's up babe ⏰

---

🌈 SEE ALSO 🌈

sigaction(2), condvar(9), delay(9), errno(9), hz(9), mstohz(9)

go read those too, they're all besties with this one 🫶✨

---

and that's the whole page, bestie 🎀💜 this Debian edition was dated July 20, 2011, so like, it's been serving these facts since before some of us could even read — respect the elders 👑💅