Reading the latest POSIX description for times(3):

> Upon successful completion, times() shall return the elapsed
> real time, in clock ticks, since an arbitrary point in the past
> (for example, system start-up time). This point does not change
> from one invocation of times() within the process to another.

it seems to me that times(3) is meant to return a monotonically
increasing value.

All other uses I've ever seen don't suggest a different understanding
by other application developers.  There aren't many left in base, but
gnu/usr.bin/gcc/gcc/timevar.c seems to support this.

I don't have access to 1003.1-1988 [1] (the most recent standard
cited in times.3).  Has the description changed much?

But, so, with this patch we use CLOCK_MONOTONIC to derive the return
value and update the manpage to reflect that.  While here, add a
RETURN VALUES section like every other library function page and reword
things to look like other library function pages (did my best).

Attached changes ok?  Input on the manpage restructuring/rewording?

Scott Cheloha

[1] It's this, right?


Index: lib/libc/gen/times.c
RCS file: /cvs/src/lib/libc/gen/times.c,v
retrieving revision 1.7
diff -u -p -r1.7 times.c
--- lib/libc/gen/times.c        2 Nov 2015 17:02:37 -0000       1.7
+++ lib/libc/gen/times.c        27 Feb 2018 00:44:55 -0000
@@ -28,9 +28,9 @@
-#include <sys/time.h>
 #include <sys/times.h>
 #include <sys/resource.h>
+#include <time.h>
  * Convert usec to clock ticks; could do (usec * CLK_TCK) / 1000000,
@@ -42,7 +42,7 @@ clock_t
 times(struct tms *tp)
        struct rusage ru;
-       struct timeval t;
+       struct timespec ts;
        if (getrusage(RUSAGE_SELF, &ru) < 0)
                return ((clock_t)-1);
@@ -52,7 +52,7 @@ times(struct tms *tp)
                return ((clock_t)-1);
        tp->tms_cutime = CONVTCK(ru.ru_utime);
        tp->tms_cstime = CONVTCK(ru.ru_stime);
-       if (gettimeofday(&t, NULL))
+       if (clock_gettime(CLOCK_MONOTONIC, &ts) == -1)
                return ((clock_t)-1);
-       return ((clock_t)(CONVTCK(t)));
+       return (ts.tv_sec * CLK_TCK + ts.tv_nsec / (1000000000 / CLK_TCK));
Index: lib/libc/gen/times.3
RCS file: /cvs/src/lib/libc/gen/times.3,v
retrieving revision 1.14
diff -u -p -r1.14 times.3
--- lib/libc/gen/times.3        17 Jul 2013 05:42:11 -0000      1.14
+++ lib/libc/gen/times.3        27 Feb 2018 00:44:55 -0000
@@ -40,20 +40,14 @@
 .Bf -symbolic
 This interface is obsoleted by
-.Xr getrusage 2
+.Xr clock_gettime 2
-.Xr gettimeofday 2 .
+.Xr getrusage 2 .
 .Fn times
-function returns the value of time in
-.Dv CLK_TCK Ns s
-of a second since
-0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal
-Time (UTC).
-It also fills in the structure pointed to by
+function fills in the structure pointed to by
 .Fa tp
 with time-accounting information.
@@ -105,27 +99,33 @@ and
 elements of the parent when one of the
 .Xr wait 2
 functions returns the process ID of the terminated child to the parent.
-If an error occurs,
+Upon successful completion,
 .Fn times
-returns the value
+returns the value of real time,
+.Dv CLK_TCK Ns s
+of a second,
+elapsed since an arbitrary point in the past.
+Otherwise a value of 
 .Li "(clock_t)-1" ,
-and sets
+is returned and the global variable
 .Va errno
-to indicate the error.
+is set to indicate the error.
 .Fn times
-function may fail and set the global variable
+function may fail and set
 .Va errno
 for any of the errors specified for the library
-.Xr getrusage 2
+.Xr clock_gettime 2
-.Xr gettimeofday 2 .
+.Xr getrusage 2 .
 .Xr time 1 ,
+.Xr clock_gettime 2 ,
 .Xr getrusage 2 ,
-.Xr gettimeofday 2 ,
 .Xr wait 2

Reply via email to