[Bug manual/2636] New: manual/time.texi describes return value from times() incorrectly

["solar at openwall dot com" <sourceware-bugzilla at sourceware dot org>]

manual/time.texi in section Processor Time Inquiry says:

"The `times' function returns information about a process' consumption
of processor time in a `struct tms' object, in addition to the process'
CPU time.
[...]
     Unlike CPU time, these are the actual amounts of time ...
[...]
     The return value is the calling process' CPU time (the same value
     you get from `clock()'.
[...]
In the GNU system, the CPU time is defined to be
equivalent to the sum of the `tms_utime' and `tms_stime' fields
returned by `times'."

This describes times() as if it returned the same value that clock() does, but
this does not agree with any of: POSIX, the behavior I've observed on various
systems, and comments within glibc source code.

According to POSIX.1-2001, clock() "shall return the implementation's best
approximation to the processor time used by the process ...", whereas times()
"shall return the elapsed real time ..."

sysdeps/generic/times.c defines a dummy times() function and (correctly)
describes it like this:

/* Store the CPU time used by this process and all its
   dead children (and their dead children) in BUFFER.
   Return the elapsed real time, or (clock_t) -1 for errors.
   All times are in CLK_TCKths of a second.  */
clock_t
__times (buffer)
     struct tms *buffer;

The calculation of clock() return value can be seen in
sysdeps/unix/sysv/linux/clock.c; although the function uses times() internally,
it does not just pass the return value.

Additionally, the section CPU Time Inquiry, which describes clock(), wrongly
states that CLK_TCK "is an obsolete name for CLOCKS_PER_SEC", and _SC_CLK_TCK is
wrongly documented as corresponding to CLOCKS_PER_SEC rather than CLK_TCK.  See
these two Debian bugs:

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=284988
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=284989

-- 
           Summary: manual/time.texi describes return value from times()
                    incorrectly
           Product: glibc
           Version: 2.4
            Status: NEW
          Severity: normal
          Priority: P2
         Component: manual
        AssignedTo: roland at gnu dot org
        ReportedBy: solar at openwall dot com
                CC: glibc-bugs at sources dot redhat dot com
 GCC build triplet: i386-openwall-linux
  GCC host triplet: i386-openwall-linux
GCC target triplet: i386-openwall-linux


http://sourceware.org/bugzilla/show_bug.cgi?id=2636

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.