[Bug 67291] New: Confusing/wrong description of CLOCK_*_CPUTIME_ID

[Bug 67291] New: Confusing/wrong description of CLOCK_*_CPUTIME_ID

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=67291

            Bug ID: 67291
           Summary: Confusing/wrong description of CLOCK_*_CPUTIME_ID
           Product: Documentation
           Version: unspecified
          Hardware: All
                OS: Linux
            Status: NEW
          Severity: normal
          Priority: P1
         Component: man-pages
          Assignee: documentation_man-pages-ztI5WcYan/vQLgFONoPN62D2FQJk+8+b@public.gmane.org
          Reporter: nyh-TS7m/3hpY0sOpacJJkBjfT4kX+cae0hd@public.gmane.org
        Regression: No

clock_gettime(2) mention CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID,
but fail to mention the most important thing: That they measure "CPU time" as
defined by Posix (see
http://pubs.opengroup.org/onlinepubs/009696899/basedefs/xbd_chap03.html#tag_03
), i.e., they measure not wall-clock time but rather the amount of time the
thread or process actually ran on the CPU.

Worse, clock_gettime(2) contains several confusing, or perhaps even wrong,
statements about these clocks:

1. At one point it says "CLOCK_PROCESS_CPUTIME_ID:            High-resolution
per-process timer from the CPU.". The phrase "from the CPU" seems to imply some
CPU feature (e.g., TSC) is used, rather than to correctly suggest that CPU time
(i.e., execution time) is being measured.

2. Another paragraph says "The CLOCK_PROCESS_CPUTIME_ID and
CLOCK_THREAD_CPUTIME_ID clocks are realized on many platforms using timers from
the  CPUs  (TSC on i386, AR.ITC on Itanium).  These registers may differ
between CPUs and as a consequence these clocks may return bogus  results if a
process is migrated to another CPU.". Is this really correct? Why would Linux
have any trouble accounting the processes's runtime (using the current cpu's
TSC) before migrating?

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 67291] Confusing/wrong description of CLOCK_*_CPUTIME_ID

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=67291

Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
         Resolution|---                         |CODE_FIX

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Bug 67291] Confusing/wrong description of CLOCK_*_CPUTIME_ID

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=67291

--- Comment #1 from Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---
Regarding point 1, I applied the following patch:

@@ -172,7 +172,8 @@ which may have discontinuities if the time is changed using
 .BR settimeofday (2).
 .TP
 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
-High-resolution per-process timer from the CPU.
+Per-process CPU-time clock
+(measures CPU time consumed by all threads in the process).
 .TP
 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
 Thread-specific CPU-time clock.

Regarding point 2, I think the problem you are concerned about was addressed in
an earlier commit; see 
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/commit/?id=78638aae3035d85ca027c003f480ff5d7921fac0

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html