Re: kern/60315: monotonic clock with or without time suspended

To: kern-bug-people%netbsd.org@localhost,gnats-admin%netbsd.org@localhost,netbsd-bugs%netbsd.org@localhost,campbell+netbsd%mumble.net@localhost
Subject: Re: kern/60315: monotonic clock with or without time suspended
From: "Taylor R Campbell via gnats" <gnats-admin%NetBSD.org@localhost>
Date: Mon, 8 Jun 2026 13:30:02 +0000 (UTC)
The following reply was made to PR kern/60315; it has been noted by GNATS.

From: Taylor R Campbell <riastradh%NetBSD.org@localhost>
To: gnats-bugs%NetBSD.org@localhost, netbsd-bugs%NetBSD.org@localhost
Cc: 
Subject: Re: kern/60315: monotonic clock with or without time suspended
Date: Mon, 8 Jun 2026 13:28:03 +0000

 This is a multi-part message in MIME format.
 --=_arl01tETGp76ibT8eUyNNP7VF0pOsarz
 
 
 --=_arl01tETGp76ibT8eUyNNP7VF0pOsarz
 Content-Type: message/rfc822
 Content-Disposition: inline
 
 Date: Mon, 8 Jun 2026 13:17:11 +0000
 From: Taylor R Campbell <riastradh%NetBSD.org@localhost>
 To: x85729201kza <x85729201kza%outlook.com@localhost>
 CC: tech-kern%NetBSD.org@localhost
 Subject: Re: Clarification of CLOCK_MONOTONIC
 Message-Id: <20260608131712.D059684CD8%mail.netbsd.org@localhost>
 In-reply-to: 
 	<TYZPR02MB6044D23AFFD62C5AB5DAA05ED61C2%TYZPR02MB6044.apcprd02.prod.outlook.com@localhost> (x85729201kza%outlook.com@localhost)
 MIME-Version: 1.0
 Content-Type: text/plain; charset=us-ascii
 Content-Transfer-Encoding: quoted-printable
 
 > Date: Mon, 8 Jun 2026 16:59:36 +1000
 > From: x85729201kza <x85729201kza%outlook.com@localhost>
 >=20
 > 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).
 >=20
 > 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>=3D15, 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:=20
 
 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=3Dclock_gettime&apropo=
 s=3D0&sektion=3D0&manpath=3DFreeBSD+7.0-RELEASE&format=3Dhtml (https://web.=
 archive.org/web/20260608121016/https://man.freebsd.org/cgi/man.cgi?query=3D=
 clock_gettime&apropos=3D0&sektion=3D0&manpath=3DFreeBSD+7.0-RELEASE&format=
 =3Dhtml)
 [FREEBSD14] https://man.freebsd.org/cgi/man.cgi?query=3Dclock_gettime&aprop=
 os=3D0&sektion=3D0&manpath=3DFreeBSD+14.0-RELEASE&format=3Dhtml (https://we=
 b.archive.org/web/20260608121003/https://man.freebsd.org/cgi/man.cgi?query=
 =3Dclock_gettime&apropos=3D0&sektion=3D0&manpath=3DFreeBSD+14.0-RELEASE&for=
 mat=3Dhtml)
 [FREEBSD15] https://man.freebsd.org/cgi/man.cgi?query=3Dclock_gettime&aprop=
 os=3D0&sektion=3D0&manpath=3DFreeBSD+15.0-RELEASE&format=3Dhtml (https://we=
 b.archive.org/web/20260608122632/https://man.freebsd.org/cgi/man.cgi?query=
 =3Dclock_gettime&apropos=3D0&sektion=3D0&manpath=3DFreeBSD+15.0-RELEASE&for=
 mat=3Dhtml)
 [FREEBSDFIXBOOTTIME] https://reviews.freebsd.org/D39270 (https://web.archiv=
 e.org/web/20251114203158/https://reviews.freebsd.org/D39270)
 [LINUXBOOTTIME] https://lwn.net/Articles/429925/ (https://web.archive.org/w=
 eb/20260216121206/https://lwn.net/Articles/429925/)
 [LINUXCLOCKGETTIME] https://man7.org/linux/man-pages/man3/clock_gettime.3.h=
 tml (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=3D1824084 (https=
 ://web.archive.org/web/20240803020239/https://bugzilla.mozilla.org/show_bug=
 .cgi?id=3D1824084)
 [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=3D1.84 (https://web.archive.org/web/20260608122930/https://cvsweb.ope=
 nbsd.org/checkout/src/sys/kern/kern_tc.c%2Cv?rev=3D1.84)
 [OPENBSDKERNTIME] https://cvsweb.openbsd.org/checkout/src/sys/kern/kern_tim=
 e.c?rev=3D1.171 (https://web.archive.org/web/20260608122814/https://cvsweb.=
 openbsd.org/checkout/src/sys/kern/kern_time.c?rev=3D1.171)
 [POSIXCLOCKGETRES] https://pubs.opengroup.org/onlinepubs/9799919799.2024edi=
 tion/functions/clock_getres.html (https://web.archive.org/web/2024091803411=
 6/https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/functions/cl=
 ock_getres.html)
 [POSIXTIMEH] https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/b=
 asedefs/time.h.html (https://web.archive.org/web/20260305210410/https://pub=
 s.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-gettim=
 e-3c.html (https://web.archive.org/web/20260316162548/https://docs.oracle.c=
 om/cd/E23824_01/html/821-1465/clock-gettime-3c.html)
 
 --=_arl01tETGp76ibT8eUyNNP7VF0pOsarz--
Prev by Date: Re: kern/60315: monotonic clock with or without time suspended
Next by Date: Re: kern/60315: monotonic clock with or without time suspended
Previous by Thread: Re: kern/60315: monotonic clock with or without time suspended
Next by Thread: Re: kern/60315: monotonic clock with or without time suspended
Indexes:
Home | Main Index | Thread Index | Old Index