NANOSLEEP(2)

💤 NANOSLEEP(2) 💤

ok so this is the nanosleep page from the System Calls Manual — section 2, bestie, we're in syscall territory now. it's giving "put me to bed but make it precise" energy ✨

---

🌸 NAME 🌸

nanosleep — high resolution sleep 😴✨

📚 LIBRARY 📚

Standard C Library (libc, -lc) 🫶

🎀 SYNOPSIS 🎀

like, here's the whole vibe:

#include <time.h>

int
clock_nanosleep(clockid_t clock_id, int flags,
    const struct timespec *rqtp, struct timespec *rmtp);

int
nanosleep(const struct timespec *rqtp, struct timespec *rmtp);

✨ DESCRIPTION ✨

okay so first up, clock_nanosleep(). if the TIMER_ABSTIME flag is NOT set in the flags argument, then clock_nanosleep() pauses the calling thread's whole existence until either:

• the time interval given by the rqtp argument has fully elapsed, or
• a signal gets delivered to the calling process and its action is to invoke a signal-catching function or to terminate the process 💀

and which clock we're measuring all this with? that's what the clock_id argument is for, bestie 🕰️

now if TIMER_ABSTIME IS set in flags, the plot twist is that clock_nanosleep() suspends the calling thread until either:

• the value of the clock specified by clock_id reaches the absolute time specified by rqtp, or
• a signal gets delivered to the calling process and its action is to invoke a signal-catching function or to terminate the process 😭

and here's the tea: if, at the moment of the call, the time value in rqtp is less than or equal to the time value of the specified clock, then clock_nanosleep() just returns immediately and the calling thread is not suspended at all. no nap for you 🙈

the suspension time may lowkey be longer than requested, because the system is out here scheduling other activity. main character problems. also, an unmasked signal will terminate the sleep early, regardless of the SA_RESTART value on the interrupting signal. and yes, the rqtp and rmtp arguments can point to the same object — they're chill like that 🫶

these are the supported clock_id values, no cap:

CLOCK_MONOTONIC
CLOCK_MONOTONIC_FAST
CLOCK_MONOTONIC_PRECISE
CLOCK_REALTIME
CLOCK_REALTIME_FAST
CLOCK_REALTIME_PRECISE
CLOCK_SECOND
CLOCK_UPTIME
CLOCK_UPTIME_FAST
CLOCK_UPTIME_PRECISE

and nanosleep()? it behaves exactly like clock_nanosleep() with a clock_id argument of CLOCK_REALTIME and without the TIMER_ABSTIME flag in the flags argument. it's the simplified version, the basic bitch of sleep calls (affectionate) 💅

🔥 RETURN VALUES 🔥

these functions return zero when the requested time has actually elapsed. slay.

but if they return for any other reason? then clock_nanosleep() will directly return the error number, and nanosleep() will return -1 with the global variable errno set to indicate the error. periodt.

and ooh, important: if a relative sleep gets interrupted by a signal and rmtp is non-NULL, the timespec structure it references gets updated to contain the unslept amount — that's the request time minus the time actually slept. so you know exactly how much beauty sleep you got robbed of 😭

💀 ERRORS 💀

these functions can fail with the following errors. buckle up:

• [EFAULT] — either rqtp or rmtp points to memory that is not a valid part of the process address space. rude.
• [EINTR] — the function was interrupted by the delivery of a signal.
• [EINVAL] — the rqtp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. pick a real number bestie.
• [EINVAL] — the flags argument contained an invalid flag.
• [EINVAL] — the clock_id argument was CLOCK_THREAD_CPUTIME_ID or an unrecognized value.
• [ENOTSUP] — the clock_id argument was valid but not supported by this implementation of clock_nanosleep().

ngl the EINVAL trio is giving "you had one job" energy. double check your args before you come crying to the kernel 🙈

👀 SEE ALSO 👀

clock_gettime(2), sigaction(2), sleep(3)

👑 STANDARDS 👑

these functions conform to IEEE Std 1003.1-2008 ("POSIX.1"). iconic behaviour, honestly.

---

and that's the whole page, bestie 🦋 this one's from the Debian crew, dated March 17, 2017 — so yeah, a lil vintage but still absolutely serving. go forth and sleep (your threads, specifically) 💖✨🎀