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