Re: time.3: miscellaneous cleanup and rewrites
Hi Scott, since i see this wasn't committed yet, it is OK schwarze@, too. Consider leaving the .Nd alone since both jmc@ and millert@ recommended that, and use "That version counted the time" in the HISTORY section as recommended by jmc@. I think you should indeed remove the sentence about gettimeofday(2) from the DESCRIPTION because millert@ has a point that it's an implementation detail, and even if considered interesting, it's already mentioned in the HISTORY section. Yours, Ingo Scott Cheloha wrote on Fri, Jul 30, 2021 at 01:01:21PM -0500: > 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.329 Jan 2015 01:46:30 - 1.16 > +++ time.330 Jul 2021 17:59:37 - > @@ -36,52 +36,54 @@ > .Os > .Sh NAME > .Nm time > -.Nd get time of day > +.Nd get the time of day > .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, > +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 .
Re: time.3: miscellaneous cleanup and rewrites
On Fri, 30 Jul 2021 13:01:21 -0500, Scott Cheloha wrote: > NAME > > - get "the" time of day. I don't like having "the" in there. I'd suggest leaving this as it is or simply shortening to either "get time" or "get the time". > SYNOPSIS > > - Not a fan of the "tloc" variable name. Use "now" as we do in other > pages to reinforce the meaning of its contents. Sure. > 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. This seems like the kind of implementation detail that shouldn't be in the man page. For instance, there's no reason why time(3) couldn't be implemented via clock_gettime(2). If someone is really curious the source is available. > 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). Yeah, I wouldn't worry about it. > I'm also leaning toward omitting the full description of the UTC clock > and its behavior. Not completely sure. I think it is fine to have that info present. > 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. Right, looks good. > 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? I think it is useful to have the section. I know I search by the section to find this information. > STANDARDS > > - This section is missing. Our time() conforms to the latest > standard. Great. > HISTORY > > - Rework this a bit. > > - Note the fate of the historical time() system call. Fine. - todd
Re: time.3: miscellaneous cleanup and rewrites
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.329 Jan 2015 01:46:30 - 1.16 > +++ time.330 Jul 2021 17:59:37 - > @@ -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 . >
time.3: miscellaneous cleanup and rewrites
Next up, time.3. As before, changes by section, with "I don't knows" at the end of the change list in each section. 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 - 1.16 +++ time.3 30 Jul 2021 17:59:37 - @@ -36,52 +36,54 @@ .Os .Sh NAME .Nm time -.Nd get time of day +.Nd get the time of day .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, +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 .
