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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/