New: clock_gettime CLOCK_TAI is incorrectly specified

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: [email protected]
Reporter: [email protected]
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.

Hi,

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>

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.

From a16a59fd1c8b7f4d8c5befc014e32b75887672fe Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email protected]>
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.

---
 man/man2/clock_getres.2 | 49 ++++++++++++++++++++++++++++++-----------
 1 file changed, 36 insertions(+), 13 deletions(-)

index 91af486f1..5b6483365 100644
@@ -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

Hi Paul,

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>

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

--- Comment #1 from Alejandro Colomar ([email protected]) --- Hi,

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.

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

--- Comment #2 from Paul Eggert ([email protected]) ---

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.

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

--- Comment #3 from Alejandro Colomar ([email protected]) --- Hi Paul,

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.