NetBSD Problem Report #60315

From www@netbsd.org  Mon Jun  8 13:12:16 2026
Return-Path: <www@netbsd.org>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
	 key-exchange X25519 server-signature RSA-PSS (2048 bits)
	 client-signature RSA-PSS (2048 bits))
	(Client CN "mail.netbsd.org", Issuer "R13" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id 4A3981A923A
	for <gnats-bugs@gnats.NetBSD.org>; Mon,  8 Jun 2026 13:12:16 +0000 (UTC)
Message-Id: <20260608131215.456911A923B@mollari.NetBSD.org>
Date: Mon,  8 Jun 2026 13:12:15 +0000 (UTC)
From: campbell+netbsd@mumble.net
Reply-To: campbell+netbsd@mumble.net
To: gnats-bugs@NetBSD.org
Subject: monotonic clock with or without time suspended
X-Send-Pr-Version: www-1.0
X-From4GNATS: "campbell+netbsd@mumble.net via gnats" <gnats-admin@NetBSD.org>

>Number:         60315
>Category:       kern
>Synopsis:       monotonic clock with or without time suspended
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Jun 08 13:15:00 +0000 2026
>Last-Modified:  Mon Jun 08 13:45:01 +0000 2026
>Originator:     Taylor R Campbell
>Release:        current, 11, 10, 9, ...
>Organization:
Acme Monotonic Clocks, Inc.
>Environment:
>Description:

	Does CLOCK_MONOTONIC keep counting time or not while the system
	is suspended?

	The answer is unclear from the documentation and the
	requirements are not obvious from the text of POSIX.

	Original discussion:
	https://mail-index.netbsd.org/tech-kern/2026/06/07/msg031069.html

>How-To-Repeat:

	docs inspection

	science

>Fix:

	We should adopt CLOCK_BOOTTIME and CLOCK_UPTIME for the two
	answers (respectively: yes, incl. suspend; no, time running
	only, excl. suspend) from FreeBSD and OpenBSD.  Linux also
	defines CLOCK_BOOTTIME (but not CLOCK_UPTIME) with the same
	semantics.

>Audit-Trail:
From: Taylor R Campbell <riastradh@NetBSD.org>
To: gnats-bugs@NetBSD.org, netbsd-bugs@NetBSD.org
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>
 To: x85729201kza <x85729201kza@outlook.com>
 CC: tech-kern@NetBSD.org
 Subject: Re: Clarification of CLOCK_MONOTONIC
 Message-Id: <20260608131712.D059684CD8@mail.netbsd.org>
 In-reply-to: 
 	<TYZPR02MB6044D23AFFD62C5AB5DAA05ED61C2@TYZPR02MB6044.apcprd02.prod.outlook.com> (x85729201kza@outlook.com)
 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>
 >=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--

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

 This is a multi-part message in MIME format.
 --=_NC1g7Zx04aXuOv/BTjb2XxgNiNEdj0K7

 [a brief lesson on why actual authoritative references are important
 and why hearsay is inadmissible as evidence]

 --=_NC1g7Zx04aXuOv/BTjb2XxgNiNEdj0K7
 Content-Type: message/rfc822
 Content-Disposition: inline

 Date: Mon, 8 Jun 2026 15:37:45 +0200
 From: Anders Magnusson <ragge@tethuvudet.se>
 To: Taylor R Campbell <riastradh@NetBSD.org>,
 	x85729201kza <x85729201kza@outlook.com>
 Cc: tech-kern@NetBSD.org
 Subject: Re: Clarification of CLOCK_MONOTONIC
 Message-ID: <6d1d64d9-edb6-46db-b325-0f003e558777@tethuvudet.se>
 In-Reply-To: <20260608131712.D059684CD8@mail.netbsd.org>
 References: <20260608131712.D059684CD8@mail.netbsd.org>
 MIME-Version: 1.0
 Content-Language: sv
 Content-Type: text/plain; charset=UTF-8; format=flowed
 Content-Transfer-Encoding: 7bit

 FYI; slight correction;

 > 
 > * 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
 > 
 The manpage on MacOS says:

       CLOCK_MONOTONIC
 	clock that increments monotonically, tracking the time
          since an arbitrary point, and will continue to
          increment while the system is asleep.

       CLOCK_MONOTONIC_RAW
          clock that increments monotonically, tracking the time
          since an arbitrary point like CLOCK_MONOTONIC.
          However, this clock is unaffected by frequency or time
          adjustments.  It should not be compared to other
          system time sources.

       CLOCK_UPTIME_RAW
 	clock that increments monotonically, in the same
 	manner as CLOCK_MONOTONIC_RAW, but that does not
 	increment while the system is asleep.  The returned
 	value is identical to the result of
 	mach_absolute_time() after the appropriate
 	mach_timebase conversion is applied.


 --=_NC1g7Zx04aXuOv/BTjb2XxgNiNEdj0K7--

Home	PR Database Search