New: Confusing/wrong description of CLOCK_*_CPUTIME_ID

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/[email protected]
Reporter: nyh-TS7m/[email protected]
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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

Michael Kerrisk <[email protected]> changed:

What |Removed |Added
----------------------------------------------------------------------------

             Status|NEW                         |RESOLVED
                 CC|                            |[email protected]
         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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

--- Comment #1 from Michael Kerrisk <[email protected]> --- 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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html