Return monotonically increasing values.

The latest POSIX description of times(3) (and all others I can find)
suggests that times(3) should return monotonically increasing values
and that these values are only useful for real time interval measurement.
All extant uses of times(3) confirm that this expectation is shared by
application programmers.

So, change gettimeofday(2) to clock_gettime(2)/CLOCK_MONOTONIC to ensure
the return value increases monotonically, even if the system clock is
changed by the superuser.  Then update the manpage accordingly.

While we're updating the manpage, move the information about the return
values to a new RETURN VALUES section to bring times.3 up to speed with
other library man pages.

Manpage changes kicked around on tech@ with millert@ and jmc@.

times.3 ok millert@ tb@ jmc@
times.c ok millert@ tb@

2 files changed, 32 insertions, 27 deletions

diff --git a/lib/libc/gen/times.3 b/lib/libc/gen/times.3
index c66750b9f3c..a5ad671e9da 100644
--- a/lib/libc/gen/times.3
+++ b/lib/libc/gen/times.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: times.3,v 1.14 2013/07/17 05:42:11 schwarze Exp $
+.\"	$OpenBSD: times.3,v 1.15 2018/03/02 16:35:58 cheloha Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 17 2013 $
+.Dd $Mdocdate: March 2 2018 $
 .Dt TIMES 3
 .Os
 .Sh NAME
@@ -40,20 +40,14 @@
 .Sh DESCRIPTION
 .Bf -symbolic
 This interface is obsoleted by
-.Xr getrusage 2
+.Xr clock_gettime 2
 and
-.Xr gettimeofday 2 .
+.Xr getrusage 2 .
 .Ef
 .Pp
 The
 .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).
-.Pp
-It also fills in the structure pointed to by
+function fills in the structure pointed to by
 .Fa tp
 with time-accounting information.
 .Pp
@@ -105,27 +99,38 @@ 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,
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn times
+returns the value of real time,
+in
+.Dv CLK_TCK Ns s
+of a second,
+elapsed since an arbitrary point in the past.
+This point does not change between invocations of
+.Fn times
+so two such return values constitute a real time interval.
+.Pp
+On failure,
 .Fn times
-returns the value
-.Li "(clock_t)-1" ,
-and sets
+returns
+.Li "(clock_t)-1"
+and the global variable
 .Va errno
-to indicate the error.
+is set to indicate the error.
 .Sh ERRORS
 The
 .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
-routines
-.Xr getrusage 2
+for any of the errors specified for
+.Xr clock_gettime 2
 and
-.Xr gettimeofday 2 .
+.Xr getrusage 2 .
 .Sh SEE ALSO
 .Xr time 1 ,
+.Xr clock_gettime 2 ,
 .Xr getrusage 2 ,
-.Xr gettimeofday 2 ,
 .Xr wait 2
 .Sh STANDARDS
 The
diff --git a/lib/libc/gen/times.c b/lib/libc/gen/times.c
index 582ef9736b9..d5a7210ee77 100644
--- a/lib/libc/gen/times.c
+++ b/lib/libc/gen/times.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: times.c,v 1.7 2015/11/02 17:02:37 mmcc Exp $ */
+/*	$OpenBSD: times.c,v 1.8 2018/03/02 16:35:58 cheloha Exp $ */
 /*-
  * Copyright (c) 1990, 1993
  *	The Regents of the University of California.  All rights reserved.
@@ -28,9 +28,9 @@
  * SUCH DAMAGE.
  */
 
-#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));
 }