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