CLOCK_NANOSLEEP(3P)

💤 clock_nanosleep(3P) — the POSIX girlies' guide to ✨high resolution sleep✨

okay bestie, come sit with me because we're reading the POSIX Programmer's Manual page for clock_nanosleep — high resolution sleep with specifiable clock — and honestly? it's giving "nap but make it precise" 💅

---

🚨 PROLOG 🚨

real talk before we start: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so if you're on Linux, go check the corresponding Linux manual page for the deets on Linux behavior. orrr the interface might not even be implemented on Linux at all. so like, vibe check your platform first 🫶

---

🌸 NAME 🌸

clock_nanosleep — high resolution sleep with specifiable clock

(yeah. you get to pick which clock measures your nap. main character energy fr fr 👑)

---

✨ SYNOPSIS ✨

#include <time.h>

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

---

💖 DESCRIPTION 💖

okay so here's the tea. two modes, depending on whether TIMER_ABSTIME is set in the flags argument. 🫖

Mode 1: TIMER_ABSTIME is NOT set (relative sleep, the "sleep for this long" vibe)

clock_nanosleep() shall cause the current thread to be suspended from execution until either:

• the time interval specified by the rqtp argument has elapsed, or
• a signal is delivered to the calling thread and its action is to invoke a signal-catching function, or
• the process is terminated.

and the clock used to measure the time shall be the clock specified by clock_id. no cap. 🕰️

Mode 2: TIMER_ABSTIME IS set (absolute sleep, the "wake me at this exact time" vibe)

clock_nanosleep() shall cause the current thread to be suspended from execution until either:

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

and here's the lil plot twist: if, at the time of the call, the time value specified by rqtp is less than or equal to the time value of the specified clock, then clock_nanosleep() shall return immediately and the calling process shall not be suspended. like, you're already late bestie, we're not napping, we're moving on. 💀

---

now, the accuracy bit. the suspension time caused by this function may be longer than requested because:

• the argument value is rounded up to an integer multiple of the sleep resolution, or
• because of the scheduling of other activity by the system.

BUT — and this is important — except for the case of being interrupted by a signal, the suspension time for the relative clock_nanosleep() function (that is, with the TIMER_ABSTIME flag not set) shall not be less than the time interval specified by rqtp, as measured by the corresponding clock.

and the suspension for the absolute clock_nanosleep() function (that is, with the TIMER_ABSTIME flag set) shall be in effect at least until the value of the corresponding clock reaches the absolute time specified by rqtp — again, except for the case of being interrupted by a signal. 🎯

---

more lore:

• the use of the clock_nanosleep() function shall have no effect on the action or blockage of any signal. not touching your signals, not my business, iykyk.
• the clock_nanosleep() function shall fail if the clock_id argument refers to the CPU-time clock of the calling thread. and it is unspecified whether clock_id values of other CPU-time clocks are allowed. 🙈

---

🔥 RETURN VALUE 🔥

if clock_nanosleep() returns because the requested time has elapsed, its return value shall be zero. slay, you slept, we love that for you. 😴

if clock_nanosleep() returns because it has been interrupted by a signal, it shall return the corresponding error value. and here's the nuance:

• for the relative clock_nanosleep() function, if the rmtp argument is non-NULL, the timespec structure referenced by it shall be updated to contain the amount of time remaining in the interval (the requested time minus the time actually slept). the rqtp and rmtp arguments can point to the same object — yes bestie, aliasing is allowed here, go off.
• if the rmtp argument is NULL, the remaining time is not returned. no leftover time for you, sorry not sorry.
• the absolute clock_nanosleep() function has no effect on the structure referenced by rmtp. it literally does not care.

if clock_nanosleep() fails, it shall return the corresponding error value.

---

💀 ERRORS 💀

the clock_nanosleep() function shall fail if:

• EINTR — the clock_nanosleep() function was interrupted by a signal. (rude, honestly. but okay.)
• EINVAL — the rqtp argument specified a nanosecond value less than zero or greater than or equal to 1000 million; or the TIMER_ABSTIME flag was specified in flags and the rqtp argument is outside the range for the clock specified by clock_id; or the clock_id argument does not specify a known clock, or specifies the CPU-time clock of the calling thread.
• ENOTSUP — the clock_id argument specifies a clock for which clock_nanosleep() is not supported, such as a CPU-time clock. 🚫

heads up: the following sections are informative. not normative. just vibes and context. 🌈

---

🌸 EXAMPLES 🌸

None. (the standard said "no examples, figure it out bestie" and honestly? iconic.) 💅

---

🎀 APPLICATION USAGE 🎀

calling clock_nanosleep() with the value TIMER_ABSTIME not set in the flags argument and with a clock_id of CLOCK_REALTIME is equivalent to calling nanosleep() with the same rqtp and rmtp arguments. so if you've been using nanosleep(), you already know this one. it's the same girl, different font. ✨

---

🧠 RATIONALE 🧠

okay this is the "why does this even exist" section and it's actually fascinating, buckle up 🦋

the nanosleep() function specifies that the system-wide clock CLOCK_REALTIME is used to measure the elapsed time for this time service. however — with the introduction of the monotonic clock CLOCK_MONOTONIC, a new relative sleep function is needed to allow an application to take advantage of the special characteristics of this clock. ✨

there are many applications in which a process needs to be suspended and then activated multiple times in a periodic way — for example, to poll the status of a non-interrupting device or to refresh a display device. for these cases, it is known that precise periodic activation cannot be achieved with a relative sleep() or nanosleep() function call.

suppose, for example, a periodic process that is activated at time T0, executes for a while, and then wants to suspend itself until time T0+T, the period being T. if this process wants to use the nanosleep() function, it must:

1. first call clock_gettime() to get the current time,
2. then calculate the difference between the current time and T0+T, and
3. finally, call nanosleep() using the computed interval.

but 😭 — the process could be preempted by a different process between the two function calls, and in this case the interval computed would be wrong; the process would wake up later than desired. this problem would not occur with the absolute clock_nanosleep() function, since only one function call would be necessary to suspend the process until the desired time. in other cases, however, a relative sleep is needed — and that is why both functionalities are required. 💖

although it is possible to implement periodic processes using the timers interface, this implementation would require the use of signals, and the reservation of some signal numbers. in this regard, the reasons for including an absolute version of the clock_nanosleep() function in POSIX.1‐2008 are the same as for the inclusion of the relative nanosleep().

it is also possible to implement precise periodic processes using pthread_cond_timedwait(), in which an absolute timeout is specified that takes effect if the condition variable involved is never signaled. however, the use of this interface is unnatural, and involves performing other operations on mutexes and condition variables that imply an unnecessary overhead. furthermore, pthread_cond_timedwait() is not available in implementations that do not support threads. 💀

and finally, the lil detail everyone forgets: although the interface of the relative and absolute versions of the new high resolution sleep service is the same clock_nanosleep() function, the rmtp argument is only used in the relative sleep. this argument is needed in the relative clock_nanosleep() function to reissue the function call if it is interrupted by a signal — but it is not needed in the absolute clock_nanosleep() function call; if the call is interrupted by a signal, the absolute clock_nanosleep() function can be invoked again with the same rqtp argument used in the interrupted call. 🎯 like, no math needed, just call it again. obsessed.

---

🔮 FUTURE DIRECTIONS 🔮

None. (the future is bright and also empty, bestie ✨)

---

👀 SEE ALSO 👀

• clock_getres()
• nanosleep()
• pthread_cond_timedwait()
• sleep()

and from the Base Definitions volume of POSIX.1‐2017: <time.h> 🌸

---

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

🫶 and that's the whole page bestie. this one came to you courtesy of IEEE/The Open Group, 2017 — go take a nap, you earned it. clock_nanosleep out. 💖✨🦋