[Bug 221186] New: clock_gettime CLOCK_TAI is incorrectly specified

[Bug 221186] New: clock_gettime CLOCK_TAI is incorrectly specified

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=221186

            Bug ID: 221186
           Summary: clock_gettime CLOCK_TAI is incorrectly specified
           Product: Documentation
           Version: unspecified
          Hardware: All
                OS: Linux
            Status: NEW
          Severity: normal
          Priority: P3
         Component: man-pages
          Assignee: documentation_man-pages@kernel-bugs.osdl.org
          Reporter: mpatocka@redhat.com
        Regression: No

The man page for clock_gettime says "CLOCK_TAI (since Linux 3.10;
Linux-specific)
A nonsettable system-wide clock derived from wall-clock time but ignoring leap
seconds."

When UTC was announced, it was already 10 seconds behind TAI. Since that, 27
leap seconds have been added. According to the man page, the difference between
wall clock an CLOCK_TAI should be 27 seconds, but in it is 37 seconds in fact.
The kernel is correct (it returns 37 as the difference between TAI and UTC),
but the man page should be fixed to reflect that.

I suggest to change the man page to:

CLOCK_TAI (since Linux 3.10; Linux-specific)
A nonsettable system-wide clock showing physical time elapsed since Jan 1 1970
0:00:00.00 TAI (Dec 31 1969 23:59:50.00 UTC). This clock does not experience
discontinuities and backwards jumps caused by NTP inserting leap seconds as
CLOCK_REALTIME does. This clock changes when system time is adjusted by the
user or NTP for the purpose of correcting wrong time setting. TAI means temps
atomique international (International Atomic Time).

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

Re: [Bug 221186] New: clock_gettime CLOCK_TAI is incorrectly specified

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1912 bytes --]

Hi,

On 2026-03-07T14:21:17+0000, bugzilla-daemon@kernel.org wrote:
> https://bugzilla.kernel.org/show_bug.cgi?id=221186
> 
>             Bug ID: 221186
>            Summary: clock_gettime CLOCK_TAI is incorrectly specified
>            Product: Documentation
>            Version: unspecified
>           Hardware: All
>                 OS: Linux
>             Status: NEW
>           Severity: normal
>           Priority: P3
>          Component: man-pages
>           Assignee: documentation_man-pages@kernel-bugs.osdl.org
>           Reporter: mpatocka@redhat.com
>         Regression: No
> 
> The man page for clock_gettime says "CLOCK_TAI (since Linux 3.10;
> Linux-specific)
> A nonsettable system-wide clock derived from wall-clock time but ignoring leap
> seconds."
> 
> When UTC was announced, it was already 10 seconds behind TAI. Since that, 27
> leap seconds have been added. According to the man page, the difference between
> wall clock an CLOCK_TAI should be 27 seconds, but in it is 37 seconds in fact.
> The kernel is correct (it returns 37 as the difference between TAI and UTC),
> but the man page should be fixed to reflect that.
> 
> I suggest to change the man page to:
> 
> CLOCK_TAI (since Linux 3.10; Linux-specific)
> A nonsettable system-wide clock showing physical time elapsed since Jan 1 1970
> 0:00:00.00 TAI (Dec 31 1969 23:59:50.00 UTC). This clock does not experience
> discontinuities and backwards jumps caused by NTP inserting leap seconds as
> CLOCK_REALTIME does. This clock changes when system time is adjusted by the
> user or NTP for the purpose of correcting wrong time setting. TAI means temps
> atomique international (International Atomic Time).

Would you mind sending a patch?

BTW, Paul, would you mind reviewing this bug report and suggestion?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [Bug 221186] New: clock_gettime CLOCK_TAI is incorrectly specified

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 273 bytes --]

On 2026-03-07 06:56, Alejandro Colomar wrote:
> BTW, Paul, would you mind reviewing this bug report and suggestion?

Although it's a start, we should add more detail about TAI and leap 
seconds, and the neighboring area could use some cleanup too. Proposed 
patch attached.

[-- Attachment #2: 0001-man-man2-clock_getres.2-modernize-leapsec-doc.patch --]
[-- Type: text/x-patch, Size: 4068 bytes --]

From a16a59fd1c8b7f4d8c5befc014e32b75887672fe Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 7 Mar 2026 12:54:53 -0800
Subject: [PATCH] man/man2/clock_getres.2: modernize leapsec doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarify when clocks are indirectly settable, by setting CLOCK_REALTIME.
Tighten up the language.
Give more details about CLOCK_TAI, such as its epoch, its
connection to NTP, the past and planned future of leap seconds,
and what “TAI” stands for.

Signed-off-by: Paul Eggert <eggert@cs.ucla.edu>
---
 man/man2/clock_getres.2 | 49 ++++++++++++++++++++++++++++++-----------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/man/man2/clock_getres.2 b/man/man2/clock_getres.2
index 91af486f1..5b6483365 100644
--- a/man/man2/clock_getres.2
+++ b/man/man2/clock_getres.2
@@ -115,16 +115,18 @@ to stay roughly in sync with UTC.
 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
 Like
 .BR CLOCK_REALTIME ,
-but not settable.
+but settable only indirectly by setting
+.BR CLOCK_REALTIME ,
+and behaves differently if the system is suspended.
 See
-.BR timer_create (2)
-for further details.
+.BR timer_create (2).
 .TP
 .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
 A faster but less precise version of
 .BR CLOCK_REALTIME .
-This clock is not settable.
+It is settable only indirectly by setting
+.BR CLOCK_REALTIME .
 Use when you need very fast, but not fine-grained timestamps.
 Requires per-architecture support,
 and probably also architecture support for this flag in the
@@ -132,15 +134,36 @@ and probably also architecture support for this flag in the
 .TP
 .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
 .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
-A nonsettable system-wide clock derived from wall-clock time
+A system-wide clock derived from wall-clock time
 but counting leap seconds.
-This clock does
-not experience discontinuities or frequency adjustments caused by
+This clock does not experience clock adjustments caused by
 inserting leap seconds as
 .B CLOCK_REALTIME
 does.
+It counts seconds since 1970-01-01 00:00 TAI (1969-12-31 23:59:50 UTC),
+so its epoch is ten seconds before
+.BR CLOCK_REALTIME 's.
+However, its implementation requires help from NTP,
+and if that help is not available it behaves like
+.B CLOCK_REALTIME
+instead.
+.IP
+Its relationship to
+.B CLOCK_REALTIME
+for timestamps before 1972 is only approximate,
+as the leap second regime was introduced on 1972-01-01.
+Because leap seconds are planned to be discontinued,
+its value from now on will likely remain exactly 37 seconds greater than
+.BR CLOCK_REALTIME 's
+for many years, after which its offset from
+.BR CLOCK_REALTIME 's
+will likely be adjusted by some other mechanism as yet unspecified.
+It is settable only indirectly by setting
+.BR CLOCK_REALTIME .
 .IP
-The acronym TAI refers to International Atomic Time.
+The acronym TAI stands for the French
+.IR "temps atomique international" ,
+or International Atomic Time.
 .TP
 .B CLOCK_MONOTONIC
 A nonsettable system-wide clock that
@@ -193,18 +216,18 @@ or similar.
 .TP
 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)"
 Like
-.BR CLOCK_BOOTTIME .
+.B CLOCK_BOOTTIME
+but behaves differently if the system is suspended.
 See
-.BR timer_create (2)
-for further details.
+.BR timer_create (2).
 .TP
 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
-This is a clock that measures CPU time consumed by this process
+This clock measures CPU time consumed by this process
 (i.e., CPU time consumed by all threads in the process).
 On Linux, this clock is not settable.
 .TP
 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
-This is a clock that measures CPU time consumed by this thread.
+This clock measures CPU time consumed by this thread.
 On Linux, this clock is not settable.
 .P
 Linux also implements dynamic clock instances as described below.
-- 
2.53.0

Re: [Bug 221186] New: clock_gettime CLOCK_TAI is incorrectly specified

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 972 bytes --]

Hi Paul,

On 2026-03-07T12:59:10-0800, Paul Eggert wrote:
> On 2026-03-07 06:56, Alejandro Colomar wrote:
> > BTW, Paul, would you mind reviewing this bug report and suggestion?
> 
> Although it's a start, we should add more detail about TAI and leap seconds,
> and the neighboring area could use some cleanup too. Proposed patch
> attached.

Thanks a lot!  I've split the patch into several atomic patches, 
minimally amended, and pushed.

51a4b682 (2026-03-07; "man/man2/clock_getres.2: CLOCK_TAI: Modernize leap-seconds documentation")
ffcf7de8 (2026-03-07; "man/man2/clock_getres.2: Clarify what "TAI" stands for.")
0676ddff (2026-03-07; "man/man2/clock_getres.2: wfix")
78a707b1 (2026-03-07; "man/man2/clock_getres.2: Some clocks behave differently if the system is suspended")
47e30f8e (2026-03-07; "man/man2/clock_getres.2: Clarify when clocks are indirectly settable")


Have a lovely night!
Alex


-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[Bug 221186] clock_gettime CLOCK_TAI is incorrectly specified

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=221186

--- Comment #1 from Alejandro Colomar (alx@kernel.org) ---
Hi,

On 2026-03-07T14:21:17+0000, bugzilla-daemon@kernel.org wrote:
> https://bugzilla.kernel.org/show_bug.cgi?id=221186
> 
>             Bug ID: 221186
>            Summary: clock_gettime CLOCK_TAI is incorrectly specified
>            Product: Documentation
>            Version: unspecified
>           Hardware: All
>                 OS: Linux
>             Status: NEW
>           Severity: normal
>           Priority: P3
>          Component: man-pages
>           Assignee: documentation_man-pages@kernel-bugs.osdl.org
>           Reporter: mpatocka@redhat.com
>         Regression: No
> 
> The man page for clock_gettime says "CLOCK_TAI (since Linux 3.10;
> Linux-specific)
> A nonsettable system-wide clock derived from wall-clock time but ignoring
> leap
> seconds."
> 
> When UTC was announced, it was already 10 seconds behind TAI. Since that, 27
> leap seconds have been added. According to the man page, the difference
> between
> wall clock an CLOCK_TAI should be 27 seconds, but in it is 37 seconds in
> fact.
> The kernel is correct (it returns 37 as the difference between TAI and UTC),
> but the man page should be fixed to reflect that.
> 
> I suggest to change the man page to:
> 
> CLOCK_TAI (since Linux 3.10; Linux-specific)
> A nonsettable system-wide clock showing physical time elapsed since Jan 1
> 1970
> 0:00:00.00 TAI (Dec 31 1969 23:59:50.00 UTC). This clock does not experience
> discontinuities and backwards jumps caused by NTP inserting leap seconds as
> CLOCK_REALTIME does. This clock changes when system time is adjusted by the
> user or NTP for the purpose of correcting wrong time setting. TAI means temps
> atomique international (International Atomic Time).

Would you mind sending a patch?

BTW, Paul, would you mind reviewing this bug report and suggestion?


Have a lovely day!
Alex

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

[Bug 221186] clock_gettime CLOCK_TAI is incorrectly specified

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=221186

--- Comment #2 from Paul Eggert (eggert@cs.ucla.edu) ---
On 2026-03-07 06:56, Alejandro Colomar wrote:
> BTW, Paul, would you mind reviewing this bug report and suggestion?

Although it's a start, we should add more detail about TAI and leap 
seconds, and the neighboring area could use some cleanup too. Proposed 
patch attached.

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.

[Bug 221186] clock_gettime CLOCK_TAI is incorrectly specified

[bugzilla-daemon]

https://bugzilla.kernel.org/show_bug.cgi?id=221186

--- Comment #3 from Alejandro Colomar (alx@kernel.org) ---
Hi Paul,

On 2026-03-07T12:59:10-0800, Paul Eggert wrote:
> On 2026-03-07 06:56, Alejandro Colomar wrote:
> > BTW, Paul, would you mind reviewing this bug report and suggestion?
> 
> Although it's a start, we should add more detail about TAI and leap seconds,
> and the neighboring area could use some cleanup too. Proposed patch
> attached.

Thanks a lot!  I've split the patch into several atomic patches, 
minimally amended, and pushed.

51a4b682 (2026-03-07; "man/man2/clock_getres.2: CLOCK_TAI: Modernize
leap-seconds documentation")
ffcf7de8 (2026-03-07; "man/man2/clock_getres.2: Clarify what "TAI" stands
for.")
0676ddff (2026-03-07; "man/man2/clock_getres.2: wfix")
78a707b1 (2026-03-07; "man/man2/clock_getres.2: Some clocks behave differently
if the system is suspended")
47e30f8e (2026-03-07; "man/man2/clock_getres.2: Clarify when clocks are
indirectly settable")


Have a lovely night!
Alex

-- 
You may reply to this email to add a comment.

You are receiving this mail because:
You are watching the assignee of the bug.