> Date: Mon, 8 Jun 2026 16:59:36 +1000 > From: x85729201kza <[email protected]> > > Of course it doesn't, but this is not the issue. However, unlike > NetBSD, Linux does document its bizarre behaviour, though, and > offers what should be CLOCK_MONOTONIC as CLOCK_BOOTTIME (FreeBSD > also offers this as a synonym of CLOCK_MONOTONIC). > > So, while I can (and will) experiment with CLOCK_MONOTONIC on > NetBSD, it would be nice for it to be clarified and documented in > the correct places.
I filed PR kern/60315: monotonic clock with or without time suspended <https://gnats.NetBSD.org/60315> to track this. I reviewed the landscape and found that it is inconsistent: - FreeBSD, OpenBSD, and macOS include time suspended in CLOCK_MONOTONIC, but Linux does not. - FreeBSD>=15, OpenBSD, and Linux provide CLOCK_BOOTTIME for time since boot, incl. suspend, but macOS does not. (FreeBSD 14 defined CLOCK_BOOTTIME as time running, excl. suspend, by mistake.) - FreeBSD and OpenBSD provide CLOCK_UPTIME for time running, excl. suspend, but on Linux that's called CLOCK_MONOTONIC and on macOS that's called CLOCK_MONOTONIC_RAW. Full listing and references below. I suggest we match the current definitions in FreeBSD and OpenBSD for CLOCK_BOOTTIME and CLOCK_UPTIME: - CLOCK_BOOTTIME counts time since boot, incl. suspend - CLOCK_UPTIME counts time running since boot, excl. supsend I think it is arguable whether CLOCK_MONOTONIC _should_ include or exclude time suspended. I'm not sure NetBSD is currently consistent across ports about this. Either way, I'm tempted to suggest that for CLOCK_MONOTONIC we add a uniform random nanosecond-resolution offset in [0, 2^62 sec) some time at boot, maybe before userland starts or after /etc/rc.d/entropy runs. It'll still meet the POSIX.1-2024 requirements this way, and it will really emphasize the unspecified nature of the reference point, and help shake out bugs with 32-bit time_t truncation. The interval of possible offsets is limited to guarantee that it won't overflow a signed 64-bit number of seconds for hosts with an uptime shorter than 146 billion years, which I think is a safe assumption. * POSIX.1-2024 - CLOCK_MONOTONIC counts time since unspecified epoch, without a clear reference to time suspended. Only requirements are [POSIXTIMEH] [POSIXCLOCKGETRES]: . cannot be set via clock_settime() . cannot have backward clock jumps . maximum possible clock jump shall be implementation-defined and must be documented . measured in seconds and nanoseconds . reference point does not change after system start-up time Not changing the reference point after system start-up time could be construed to require including time suspended. But it's arguable; the language is certainly not explicit about the point. History: 1. CLOCK_MONOTONIC was added as optional in Issue 6 (POSIX.1-2001), based on IEEE Std 1003.1j-2000. 2. CLOCK_MONOTONIC was made mandatory in Issue 8 (POSIX.1-2024). * FreeBSD [FREEBSD15] - CLOCK_BOOTTIME counts time since unspecified epoch, incl. suspend - CLOCK_MONOTONIC counts time since unspecified epoch, incl. suspend - CLOCK_UPTIME counts time running since unspecified epoch, excl. suspend History: 1. CLOCK_UPTIME was introduced in FreeBSD 7 [FREEBSD7], released 2008 2. CLOCK_BOOTTIME was introduced in FreeBSD 14 as an alias for CLOCK_UPTIME [FREEBSD14], released 2023 3. CLOCK_BOOTTIME was changed in FreeBSD 15 to be an alias for CLOCK_MONOTONIC [FREEBSD15] [FREEBSDFIXBOOTTIME], released 2025, prompted in part by [MOZILLATIME] * OpenBSD [OPENBSD78] - CLOCK_BOOTTIME counts time since boot, incl. suspend - CLOCK_MONOTONIC counts time since unspecified epoch, incl. suspend - CLOCK_UPTIME counts time running since boot, excl. suspend (Confusingly, the descriptions say: `CLOCK_BOOTTIME The uptime clock. [...] CLOCK_UPTIME The runtime clock.' But I'm reading out what the rest of the text, which matches the source code for clock_gettime(CLOCK_*) defining CLOCK_UPTIME to return nanoruntime and CLOCK_BOOTTIME and CLOCK_MONOTONIC to return nanouptime [OPENBSDKERNTIME], while the source code for nanoruntime/binruntime returns time since boot and the source code for nanouptime/binuptime returns time since boot minus time suspended [OPENBSDKERNTC].) History: 1. CLOCK_UPTIME was introduced in OpenBSD 5.5, released 2014 2. CLOCK_BOOTTIME was introduced in OpenBSD 6.3, released 2018 * Linux [LINUXCLOCKGETTIME] - CLOCK_MONOTONIC counts time running since boot, excl. suspend - CLOCK_BOOTTIME counts time since boot, incl. suspend History: 1. CLOCK_BOOTTIME was added around 2011 [LINUXBOOTTIME]. * macOS By hearsay [MOZILLATIME], since I am having trouble finding macOS man pages on the web, it sounds like: - CLOCK_MONOTONIC counts time since boot, incl. suspend - CLOCK_MONOTONIC_RAW counts time running since boot, excl. suspend History: no idea but macOS probably exposed this distinction to applications long before anyone else * Solaris/illumos Neither SmartOS [SMARTOS] nor Oracle Solaris [SOLARIS11] man pages say anything about suspend. * References [FREEBSD7] https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html (https://web.archive.org/web/20260608121016/https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html) [FREEBSD14] https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+14.0-RELEASE&format=html (https://web.archive.org/web/20260608121003/https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+14.0-RELEASE&format=html) [FREEBSD15] https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+15.0-RELEASE&format=html (https://web.archive.org/web/20260608122632/https://man.freebsd.org/cgi/man.cgi?query=clock_gettime&apropos=0&sektion=0&manpath=FreeBSD+15.0-RELEASE&format=html) [FREEBSDFIXBOOTTIME] https://reviews.freebsd.org/D39270 (https://web.archive.org/web/20251114203158/https://reviews.freebsd.org/D39270) [LINUXBOOTTIME] https://lwn.net/Articles/429925/ (https://web.archive.org/web/20260216121206/https://lwn.net/Articles/429925/) [LINUXCLOCKGETTIME] https://man7.org/linux/man-pages/man3/clock_gettime.3.html (https://web.archive.org/web/20260604162559/https://man7.org/linux/man-pages/man3/clock_gettime.3.html) [MOZILLATIME] https://bugzilla.mozilla.org/show_bug.cgi?id=1824084 (https://web.archive.org/web/20240803020239/https://bugzilla.mozilla.org/show_bug.cgi?id=1824084) [OPENBSD55] https://man.openbsd.org/OpenBSD-5.5/clock_gettime#DESCRIPTION (https://web.archive.org/web/20260608122317/https://man.openbsd.org/OpenBSD-5.5/clock_gettime#DESCRIPTION) [OPENBSD63] https://man.openbsd.org/OpenBSD-6.3/clock_gettime#DESCRIPTION (https://web.archive.org/web/20260608122450/https://man.openbsd.org/OpenBSD-6.3/clock_gettime#DESCRIPTION) [OPENBSD78] https://man.openbsd.org/OpenBSD-7.8/clock_gettime#DESCRIPTION (https://web.archive.org/web/20260608122547/https://man.openbsd.org/OpenBSD-7.8/clock_gettime#DESCRIPTION) [OPENBSDKERNTC] https://cvsweb.openbsd.org/checkout/src/sys/kern/kern_tc.c,v?rev=1.84 (https://web.archive.org/web/20260608122930/https://cvsweb.openbsd.org/checkout/src/sys/kern/kern_tc.c%2Cv?rev=1.84) [OPENBSDKERNTIME] https://cvsweb.openbsd.org/checkout/src/sys/kern/kern_time.c?rev=1.171 (https://web.archive.org/web/20260608122814/https://cvsweb.openbsd.org/checkout/src/sys/kern/kern_time.c?rev=1.171) [POSIXCLOCKGETRES] https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/functions/clock_getres.html (https://web.archive.org/web/20240918034116/https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/functions/clock_getres.html) [POSIXTIMEH] https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/basedefs/time.h.html (https://web.archive.org/web/20260305210410/https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/basedefs/time.h.html) [SMARTOS] https://smartos.org/man/3C/clock_gettime (https://web.archive.org/web/20260608120951/https://smartos.org/man/3C/clock_gettime) [SOLARIS11] https://docs.oracle.com/cd/E23824_01/html/821-1465/clock-gettime-3c.html (https://web.archive.org/web/20260316162548/https://docs.oracle.com/cd/E23824_01/html/821-1465/clock-gettime-3c.html)
