On Fri, Jul 30, 2021 at 01:01:21PM -0500, Scott Cheloha wrote: > Next up, time.3. > > As before, changes by section, with "I don't knows" at the end of the > change list in each section. >
hi. comments inline: > NAME > > - get "the" time of day. > > SYNOPSIS > > - Not a fan of the "tloc" variable name. Use "now" as we do in other > pages to reinforce the meaning of its contents. > > DESCRIPTION > > - Clean this up. In particular, format the Epoch date like we do in > other pages. We don't need two paragraphs, either. > > - Mention that we call gettimeofday(2). Not strictly necessary, but > useful for people tracing system calls to know what the library > is doing. > > Part of me wants to tell the reader not to use time() to measure > elapsed time. Then again, time() is low-res so it isn't misused > nearly as often as gettimeofday(2). > > I'm also leaning toward omitting the full description of the UTC clock > and its behavior. Not completely sure. > > RETURN VALUES > > - There are no relevant error cases, remove them. > > The underlying system call, gettimeofday(2), will not fail in this > context unless the stack is corrupted, which we cannot account for > anyway. > > - Just say that time() always succeeds. > > I cribbed this bit from another page to put something in the Return > Values section, but the return value is already described in the > Description. > > Maybe we don't need this section at all anymore? > > STANDARDS > > - This section is missing. Our time() conforms to the latest > standard. > > HISTORY > > - Rework this a bit. > > - Note the fate of the historical time() system call. > > Index: time.3 > =================================================================== > RCS file: /cvs/src/lib/libc/gen/time.3,v > retrieving revision 1.16 > diff -u -p -r1.16 time.3 > --- time.3 29 Jan 2015 01:46:30 -0000 1.16 > +++ time.3 30 Jul 2021 17:59:37 -0000 > @@ -36,52 +36,54 @@ > .Os > .Sh NAME > .Nm time > -.Nd get time of day > +.Nd get the time of day i'm honestly unconvinced about this. it makes more sense in normal english rules, but feels incorrect. for comparison, posix uses time - get time i think in this sense "time of day" is a thing, and does not require an article. i don;t see a good reason to change it. > .Sh SYNOPSIS > .In time.h > .Ft time_t > -.Fn time "time_t *tloc" > +.Fn time "time_t *now" > .Sh DESCRIPTION > The > .Fn time > -function returns the value of time in seconds since 0 hours, 0 minutes, > -0 seconds, January 1, 1970, Coordinated Universal Time (UTC). > +function returns the the number of seconds elapsed since > +Jan 1 1970 00:00:00 UTC. > +This value is also written to > +.Fa now > +unless > +.Fa now > +is > +.Dv NULL . > .Pp > -A copy of the time value may be saved to the area indicated by the > -pointer > -.Fa tloc . > -If > -.Fa tloc > -is a null pointer, no value is stored. > +This version of > +.Fn time > +is implemented with > +.Xr gettimeofday 2 . > .Sh RETURN VALUES > -Upon successful completion, > +The > .Fn time > -returns the value of time. > -Otherwise a value of > -.Po Fa time_t Pc Ns -1 > -is returned and the global variable > -.Va errno > -is set to indicate the error. > -.Sh ERRORS > -The following error codes may be set in > -.Va errno : > -.Bl -tag -width Er > -.It Bq Er EFAULT > -An argument address referenced invalid memory. > -.El > +function is always successful, > +and no return value is reserved to indicate an error. > .Sh SEE ALSO > .Xr clock_gettime 2 , > .Xr gettimeofday 2 , > .Xr ctime 3 > +.Sh STANDARDS > +The > +.Fn time > +function conforms to > +.St -p1003.1-2008 . > .Sh HISTORY > A > .Fn time > system call first appeared in > -.At v1 > -and used to return time in sixtieths of a second in 32 bits, > -which was to guarantee a crisis every 2.26 years. > -Since > -.At v6 , > -.Fn time > -scale was changed to seconds, extending the pre-crisis stagnation > -period up to a total of 68 years. > +.At v1 . > +This version counted time in sixtieths of a second with a 32-bit return > value, i think the text should be *that* version otherwise reads fine. jmc > +ensuring an integer overflow crisis every 2.26 years. > +In > +.At v6 > +the granularity of the return value was reduced to whole seconds, > +delaying the aforementioned crisis until 2038. > +In > +.Bx 4.1c > +the function was moved out of the kernel into the C standard library and > +reimplemented with > +.Xr gettimeofday 2 . >