On Wed, Feb 28, 2018 at 08:58:41AM -0700, Todd C. Miller wrote:
> On Wed, 28 Feb 2018 09:46:30 -0600, Scott Cheloha wrote:
> 
> > I want to avoid giving the reader even the slightest impression that
> > the return value from times(3) can be used for anything but real-time
> > interval measurement.  Mentioning that the value is relative to the
> > system start time seems to lean in that direction.  What did you want
> > to impart by documenting that?
> 
> That's reasonable.  My only concern is that by using the word
> "arbitrary" it becomes unclear whether the returned time is consistent
> between calls.  I'm not sure how best to get that across.  Maybe
> it is not really important since this is a deprecated interface.

I know it's not customary to put extra details in RETURN VALUES, but
times(3) is a bit unwieldy.  How does the attached read?

I have some unrelated tweaks I want to make in a subsequent patch, so
maybe introducing an example then will put a nail in this coffin.

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        28 Feb 2018 16:21:43 -0000
@@ -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

Reply via email to