Skip to contentSkip to conversation

clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values

RFC PATCH In review Helge Deller 2 participants 4 messages Feb 20, 2020 – Feb 23, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Helge Deller

author
#0 lore raw

RFC PATCH 1/1 clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values

Consecutive calls to clock_gettime(CLOCK_MONOTONIC) are guaranteed to return MONOTONIC values, which means that they either return the *SAME* time value like the last call, or a later (higher) time value.

Due to high resolution counters like TSC on x86 most people see that the values returned increase, but on other less common platforms it's less likely that consecutive calls return newer values, and instead users may unexpectely get back the SAME time value.

I think it makes sense to document that people should not expect to see "always-growing" time values. For example in Debian I've seen in quite some source packages where return values of consecutive calls are compared against each other and then the package build fails if they are equal (e.g. ruby-hitimes, ...).

The patch below is just for RFC. I'm open for any better wording!

Signed-off-by Helge Deller <[email protected]>
man2/clock_getres.2 +4 -0
index 646fa37c0..89e9f6a30 100644
@@ -151,6 +151,10 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but they may return the identical (not-increased) time value.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
#1 lore raw

Hello Helge,

Quoted 24 lines · Helge Deller

Consecutive calls to clock_gettime(CLOCK_MONOTONIC) are guaranteed to return MONOTONIC values, which means that they either return the *SAME* time value like the last call, or a later (higher) time value.

Due to high resolution counters like TSC on x86 most people see that the values returned increase, but on other less common platforms it's less likely that consecutive calls return newer values, and instead users may unexpectely get back the SAME time value.

I think it makes sense to document that people should not expect to see "always-growing" time values. For example in Debian I've seen in quite some source packages where return values of consecutive calls are compared against each other and then the package build fails if they are equal (e.g. ruby-hitimes, ...).

The patch below is just for RFC. I'm open for any better wording!

Signed-off-by Helge Deller <[email protected]>
man2/clock_getres.2 +0 -0
index 646fa37c0..89e9f6a30 100644

man2/clock_getres.2 but is affected by the incremental adjustments performed by · line 160

Quoted 10 lines
man2/clock_getres.2 +4 -0
@@ -151,6 +151,10 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but they may return the identical (not-increased) time value.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3

Thanks. I applied your patch, and then tweaked slightly, so tha the change looks as below.

Cheers,

Michael

man2/clock_getres.2 +5 -0
index 646fa37c0..3fb0ac61c 100644
@@ -151,6 +151,11 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but successive calls may\(emdepending on the architecture\(emreturn
+identical (not-increased) time values.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
author
#2 lore raw
Quoted 32 lines · Michael Kerrisk (man-pages)

Hello Helge,

Quoted 29 lines · Helge Deller

Consecutive calls to clock_gettime(CLOCK_MONOTONIC) are guaranteed to return MONOTONIC values, which means that they either return the *SAME* time value like the last call, or a later (higher) time value.

Due to high resolution counters like TSC on x86 most people see that the values returned increase, but on other less common platforms it's less likely that consecutive calls return newer values, and instead users may unexpectely get back the SAME time value.

I think it makes sense to document that people should not expect to see "always-growing" time values. For example in Debian I've seen in quite some source packages where return values of consecutive calls are compared against each other and then the package build fails if they are equal (e.g. ruby-hitimes, ...).

The patch below is just for RFC. I'm open for any better wording!

Signed-off-by Helge Deller <[email protected]>
man2/clock_getres.2 +2 -0
index 646fa37c0..89e9f6a30 100644
@@ -151,6 +151,10 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
Quoted 8 lines

man2/clock_getres.2 but is affected by the incremental adjustments performed by · line 161

Quoted 5 lines
man2/clock_getres.2 +2 -0
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but they may return the identical (not-increased) time value.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3

Thanks. I applied your patch, and then tweaked slightly, so tha the change looks as below.

Looks good.
Thanks!

Helge

Quoted 23 lines

Cheers,

Michael

man2/clock_getres.2 +5 -0
index 646fa37c0..3fb0ac61c 100644
@@ -151,6 +151,11 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but successive calls may\(emdepending on the architecture\(emreturn
+identical (not-increased) time values.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
#3 lore raw
Quoted 43 lines · Helge Deller
Quoted 32 lines · Michael Kerrisk (man-pages)

Hello Helge,

Quoted 29 lines · Helge Deller

Consecutive calls to clock_gettime(CLOCK_MONOTONIC) are guaranteed to return MONOTONIC values, which means that they either return the *SAME* time value like the last call, or a later (higher) time value.

Due to high resolution counters like TSC on x86 most people see that the values returned increase, but on other less common platforms it's less likely that consecutive calls return newer values, and instead users may unexpectely get back the SAME time value.

I think it makes sense to document that people should not expect to see "always-growing" time values. For example in Debian I've seen in quite some source packages where return values of consecutive calls are compared against each other and then the package build fails if they are equal (e.g. ruby-hitimes, ...).

The patch below is just for RFC. I'm open for any better wording!

Signed-off-by Helge Deller <[email protected]>
man2/clock_getres.2 +2 -0
index 646fa37c0..89e9f6a30 100644
@@ -151,6 +151,10 @@ but is affected by the incremental adjustments performed by
 .BR adjtime (3)
 and NTP.
 This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
Quoted 8 lines

man2/clock_getres.2 but is affected by the incremental adjustments performed by · line 161

Quoted 5 lines
man2/clock_getres.2 +2 -0
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but they may return the identical (not-increased) time value.
 .TP
 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3

Thanks. I applied your patch, and then tweaked slightly, so tha the change looks as below.

Quoted 2 lines

Looks good.
Thanks!

Thanks for checking!

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/