Debian Bug report logs - #540872
clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

version graph

Package: manpages; Maintainer for manpages is Martin Schulze <joey@debian.org>; Source for manpages is src:manpages.

Reported by: Josh Triplett <josh@joshtriplett.org>

Date: Mon, 10 Aug 2009 18:33:02 UTC

Severity: wishlist

Tags: upstream

Found in version manpages/3.22-1

Fixed in version 3.42-1

Done: Simon Paillard <spaillard@debian.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, josh@joshtriplett.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Mon, 10 Aug 2009 18:33:06 GMT) Full text and rfc822 format available.

Message #3 received at submit@bugs.debian.org (full text, mbox):

From: Josh Triplett <josh@joshtriplett.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Mon, 10 Aug 2009 11:30:34 -0700
Package: manpages
Version: 3.22-1
Severity: wishlist

Developers of real-time programs (programs using real-time scheduling
and/or expecting low latency) sometimes see CLOCK_REALTIME and think
they want to use that, when they almost certainly don't.  Please
consider adding some clarification that the "real-time" of
CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
time, for instance) and that developers of real-time applications want
to use CLOCK_MONOTONIC.

Thanks,
Josh Triplett

-- System Information:
Debian Release: squeeze/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: i386 (i686)

Kernel: Linux 2.6.31-rc5 (SMP w/2 CPU cores; PREEMPT)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash

manpages depends on no packages.

manpages recommends no packages.

Versions of packages manpages suggests:
ii  man-db [man-browser]          2.5.5-3    on-line manual pager

-- no debconf information




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Sat, 28 Apr 2012 22:27:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Simon Paillard <spaillard@debian.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sat, 28 Apr 2012 22:27:03 GMT) Full text and rfc822 format available.

Message #8 received at 540872@bugs.debian.org (full text, mbox):

From: Simon Paillard <spaillard@debian.org>
To: Josh Triplett <josh@joshtriplett.org>, 540872@bugs.debian.org
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Sun, 29 Apr 2012 00:21:15 +0200
tags + upstream
thanks

Hi,

On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> Package: manpages
> Version: 3.22-1
> Severity: wishlist
> 
> Developers of real-time programs (programs using real-time scheduling
> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> they want to use that, when they almost certainly don't.  Please
> consider adding some clarification that the "real-time" of
> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> time, for instance) and that developers of real-time applications want
> to use CLOCK_MONOTONIC.

Michael Kerrisk improved clock_getres.2 in manpages 3.40: 

 .B CLOCK_MONOTONIC
 Clock that cannot be set and represents monotonic time since
 some unspecified starting point.
+This clock is not affected by discontinuous jumps in the system time
+(e.g., if the system administrator manually changes the clock),
+but is affected by the incremental adjustments performed by
+.BR adjtime (2)
+and NTP.

Maybe one can add (please proofread my english):
"This clock allow to precisely measuring time elapsed, for use in real-time programs."

http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html

-- 
Simon Paillard




Added tag(s) upstream. Request was from Simon Paillard <spaillard@debian.org> to control@bugs.debian.org. (Sat, 28 Apr 2012 22:39:02 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Sun, 29 Apr 2012 10:42:14 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sun, 29 Apr 2012 10:42:15 GMT) Full text and rfc822 format available.

Message #15 received at 540872@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org
Cc: Josh Triplett <josh@joshtriplett.org>
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Sun, 29 Apr 2012 22:40:48 +1200
On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> tags + upstream
> thanks
>
> Hi,
>
> On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
>> Package: manpages
>> Version: 3.22-1
>> Severity: wishlist
>>
>> Developers of real-time programs (programs using real-time scheduling
>> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
>> they want to use that, when they almost certainly don't.  Please
>> consider adding some clarification that the "real-time" of
>> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
>> time, for instance) and that developers of real-time applications want
>> to use CLOCK_MONOTONIC.
>
> Michael Kerrisk improved clock_getres.2 in manpages 3.40:
>
>  .B CLOCK_MONOTONIC
>  Clock that cannot be set and represents monotonic time since
>  some unspecified starting point.
> +This clock is not affected by discontinuous jumps in the system time
> +(e.g., if the system administrator manually changes the clock),
> +but is affected by the incremental adjustments performed by
> +.BR adjtime (2)
> +and NTP.
>
> Maybe one can add (please proofread my english):
> "This clock allow to precisely measuring time elapsed, for use in real-time programs."
>
> http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html

Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Sun, 29 Apr 2012 19:18:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Josh Triplett <josh@joshtriplett.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sun, 29 Apr 2012 19:18:03 GMT) Full text and rfc822 format available.

Message #20 received at 540872@bugs.debian.org (full text, mbox):

From: Josh Triplett <josh@joshtriplett.org>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Sun, 29 Apr 2012 12:15:08 -0700
On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> > tags + upstream
> > thanks
> >
> > Hi,
> >
> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> >> Package: manpages
> >> Version: 3.22-1
> >> Severity: wishlist
> >>
> >> Developers of real-time programs (programs using real-time scheduling
> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> >> they want to use that, when they almost certainly don't.  Please
> >> consider adding some clarification that the "real-time" of
> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> >> time, for instance) and that developers of real-time applications want
> >> to use CLOCK_MONOTONIC.
> >
> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
> >
> >  .B CLOCK_MONOTONIC
> >  Clock that cannot be set and represents monotonic time since
> >  some unspecified starting point.
> > +This clock is not affected by discontinuous jumps in the system time
> > +(e.g., if the system administrator manually changes the clock),
> > +but is affected by the incremental adjustments performed by
> > +.BR adjtime (2)
> > +and NTP.
> >
> > Maybe one can add (please proofread my english):
> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
> >
> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
> 
> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?

Probably, yes.

Ideally, I'd also like to see something like this added to the
description of CLOCK_REALTIME, to help avert a common trap people fall
into:

'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
not to suitability for realtime (latency-sensitive) applications.  Such
applications generally want to use CLOCK_MONOTONIC or
CLOCK_MONOTONIC_RAW.'

- Josh Triplett




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Sun, 29 Apr 2012 22:54:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sun, 29 Apr 2012 22:54:03 GMT) Full text and rfc822 format available.

Message #25 received at 540872@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Josh Triplett <josh@joshtriplett.org>
Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Mon, 30 Apr 2012 10:50:50 +1200
tags 540872 fixed-upstream
thanks

Hi Josh!

On Mon, Apr 30, 2012 at 7:15 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
>> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
>> > tags + upstream
>> > thanks
>> >
>> > Hi,
>> >
>> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
>> >> Package: manpages
>> >> Version: 3.22-1
>> >> Severity: wishlist
>> >>
>> >> Developers of real-time programs (programs using real-time scheduling
>> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
>> >> they want to use that, when they almost certainly don't.  Please
>> >> consider adding some clarification that the "real-time" of
>> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
>> >> time, for instance) and that developers of real-time applications want
>> >> to use CLOCK_MONOTONIC.
>> >
>> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
>> >
>> >  .B CLOCK_MONOTONIC
>> >  Clock that cannot be set and represents monotonic time since
>> >  some unspecified starting point.
>> > +This clock is not affected by discontinuous jumps in the system time
>> > +(e.g., if the system administrator manually changes the clock),
>> > +but is affected by the incremental adjustments performed by
>> > +.BR adjtime (2)
>> > +and NTP.
>> >
>> > Maybe one can add (please proofread my english):
>> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
>> >
>> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
>>
>> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?
>
> Probably, yes.
>
> Ideally, I'd also like to see something like this added to the
> description of CLOCK_REALTIME, to help avert a common trap people fall
> into:
>
> 'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
> not to suitability for realtime (latency-sensitive) applications.  Such
> applications generally want to use CLOCK_MONOTONIC or
> CLOCK_MONOTONIC_RAW.'

How about doing this in a different way. Instead of pointing the
reader at CLOCK_MONOTONIC*, let's be more explicit about what
CLOCK_REALTIME is, so that it's evident to the designer of a realtime
application that they don't want this clock.

[[
.TP
.B CLOCK_REALTIME
System-wide clock that measures real (i.e., wall-clock) time.
Setting this clock requires appropriate privileges.
This clock is affected by discontinuous jumps in the system time
(e.g., if the system administrator manually changes the clock),
and by the incremental adjustments performed by
.BR adjtime (2)
and NTP.
]]

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#540872; Package manpages. (Mon, 30 Apr 2012 00:45:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Josh Triplett <josh@joshtriplett.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Mon, 30 Apr 2012 00:45:03 GMT) Full text and rfc822 format available.

Message #30 received at 540872@bugs.debian.org (full text, mbox):

From: Josh Triplett <josh@joshtriplett.org>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Sun, 29 Apr 2012 17:41:23 -0700
On Mon, Apr 30, 2012 at 10:50:50AM +1200, Michael Kerrisk (man-pages) wrote:
> tags 540872 fixed-upstream
> thanks
> 
> Hi Josh!
> 
> On Mon, Apr 30, 2012 at 7:15 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> > On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
> >> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> >> > tags + upstream
> >> > thanks
> >> >
> >> > Hi,
> >> >
> >> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> >> >> Package: manpages
> >> >> Version: 3.22-1
> >> >> Severity: wishlist
> >> >>
> >> >> Developers of real-time programs (programs using real-time scheduling
> >> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> >> >> they want to use that, when they almost certainly don't.  Please
> >> >> consider adding some clarification that the "real-time" of
> >> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> >> >> time, for instance) and that developers of real-time applications want
> >> >> to use CLOCK_MONOTONIC.
> >> >
> >> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
> >> >
> >> >  .B CLOCK_MONOTONIC
> >> >  Clock that cannot be set and represents monotonic time since
> >> >  some unspecified starting point.
> >> > +This clock is not affected by discontinuous jumps in the system time
> >> > +(e.g., if the system administrator manually changes the clock),
> >> > +but is affected by the incremental adjustments performed by
> >> > +.BR adjtime (2)
> >> > +and NTP.
> >> >
> >> > Maybe one can add (please proofread my english):
> >> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
> >> >
> >> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
> >>
> >> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?
> >
> > Probably, yes.
> >
> > Ideally, I'd also like to see something like this added to the
> > description of CLOCK_REALTIME, to help avert a common trap people fall
> > into:
> >
> > 'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
> > not to suitability for realtime (latency-sensitive) applications.  Such
> > applications generally want to use CLOCK_MONOTONIC or
> > CLOCK_MONOTONIC_RAW.'
> 
> How about doing this in a different way. Instead of pointing the
> reader at CLOCK_MONOTONIC*, let's be more explicit about what
> CLOCK_REALTIME is, so that it's evident to the designer of a realtime
> application that they don't want this clock.
> 
> [[
> .TP
> .B CLOCK_REALTIME
> System-wide clock that measures real (i.e., wall-clock) time.
> Setting this clock requires appropriate privileges.
> This clock is affected by discontinuous jumps in the system time
> (e.g., if the system administrator manually changes the clock),
> and by the incremental adjustments performed by
> .BR adjtime (2)
> and NTP.
> ]]

Works for me.

- Josh Triplett




Reply sent to Simon Paillard <spaillard@debian.org>:
You have taken responsibility. (Sun, 21 Oct 2012 22:48:03 GMT) Full text and rfc822 format available.

Notification sent to Josh Triplett <josh@joshtriplett.org>:
Bug acknowledged by developer. (Sun, 21 Oct 2012 22:48:03 GMT) Full text and rfc822 format available.

Message #35 received at 540872-done@bugs.debian.org (full text, mbox):

From: Simon Paillard <spaillard@debian.org>
To: 540872-done@bugs.debian.org
Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME
Date: Mon, 22 Oct 2012 00:45:10 +0200
Version: 3.42-1

On Mon, Apr 30, 2012 at 10:50:50AM +1200, Michael Kerrisk (man-pages) wrote:
> tags 540872 fixed-upstream
> thanks
[..] 
> How about doing this in a different way. Instead of pointing the
> reader at CLOCK_MONOTONIC*, let's be more explicit about what
> CLOCK_REALTIME is, so that it's evident to the designer of a realtime
> application that they don't want this clock.
> 
> [[
> .TP
> .B CLOCK_REALTIME
> System-wide clock that measures real (i.e., wall-clock) time.
> Setting this clock requires appropriate privileges.
> This clock is affected by discontinuous jumps in the system time
> (e.g., if the system administrator manually changes the clock),
> and by the incremental adjustments performed by
> .BR adjtime (2)
> and NTP.
> ]]

http://git.kernel.org/?p=docs/man-pages/man-pages.git;a=commitdiff;h=22594a3cb
first in upstream 3.41, and first in debian through manpages 3.42-1.
 

-- 
Simon Paillard



Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Mon, 19 Nov 2012 07:26:40 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Thu Apr 24 20:16:43 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.