Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values
@ 2020-02-20 17:24 Helge Deller
  2020-02-23 21:09 ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 4+ messages in thread
From: Helge Deller @ 2020-02-20 17:24 UTC (permalink / raw)
  To: Michael Kerrisk; +Cc: linux-man, John Stultz, Thomas Gleixner

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values
  2020-02-20 17:24 [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values Helge Deller
@ 2020-02-23 21:09 ` Michael Kerrisk (man-pages)
  2020-02-23 21:26   ` Helge Deller
  0 siblings, 1 reply; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-02-23 21:09 UTC (permalink / raw)
  To: Helge Deller; +Cc: mtk.manpages, linux-man, John Stultz, Thomas Gleixner

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/

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values
  2020-02-23 21:09 ` Michael Kerrisk (man-pages)
@ 2020-02-23 21:26   ` Helge Deller
  2020-02-23 21:36     ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 4+ messages in thread
From: Helge Deller @ 2020-02-23 21:26 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: linux-man, John Stultz, Thomas Gleixner

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
>
>
>


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values
  2020-02-23 21:26   ` Helge Deller
@ 2020-02-23 21:36     ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-02-23 21:36 UTC (permalink / raw)
  To: Helge Deller; +Cc: mtk.manpages, linux-man, John Stultz, Thomas Gleixner

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/

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-20 17:24 [PATCH][RFC] clock_getres.2: Document that consecutive calls for CLOCK_MONOTONIC may return same values Helge Deller
2020-02-23 21:09 ` Michael Kerrisk (man-pages)
2020-02-23 21:26   ` Helge Deller
2020-02-23 21:36     ` Michael Kerrisk (man-pages)

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git