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 .
>
