--- Begin Message ---
> Date: Mon, 8 Jun 2026 16:59:36 +1000
> From: x85729201kza <x85729201kza%outlook.com@localhost>
>
> 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)
--- End Message ---