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

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

[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 <deller@gmx.de>

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 646fa37c0..89e9f6a30 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -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

Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values

[Michael Kerrisk (man-pages)]

Hello Helge,

On 2/20/20 6:24 PM, Helge Deller wrote:
> 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 <deller@gmx.de>
> 
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 646fa37c0..89e9f6a30 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -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

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 646fa37c0..3fb0ac61c 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -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



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

Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values

[Helge Deller]

On 23.02.20 22:09, Michael Kerrisk (man-pages) wrote:
> Hello Helge,
>
> On 2/20/20 6:24 PM, Helge Deller wrote:
>> 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 <deller@gmx.de>
>>
>> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
>> index 646fa37c0..89e9f6a30 100644
>> --- a/man2/clock_getres.2
>> +++ b/man2/clock_getres.2
>> @@ -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.


Looks good.
Thanks!

Helge


> Cheers,
>
> Michael
>
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 646fa37c0..3fb0ac61c 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -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
>
>
>

Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values

[Michael Kerrisk (man-pages)]

On 2/23/20 10:26 PM, Helge Deller wrote:
> On 23.02.20 22:09, Michael Kerrisk (man-pages) wrote:
>> Hello Helge,
>>
>> On 2/20/20 6:24 PM, Helge Deller wrote:
>>> 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 <deller@gmx.de>
>>>
>>> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
>>> index 646fa37c0..89e9f6a30 100644
>>> --- a/man2/clock_getres.2
>>> +++ b/man2/clock_getres.2
>>> @@ -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.
> 
> 
> Looks good.
> Thanks!
Thanks for checking!

Cheers,

Michael


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