git: cf1c35c92e01 - stable/12 - time(3): Refine history in the manual page

The branch stable/12 has been updated by gbe (doc committer):

URL: https://cgit.FreeBSD.org/src/commit/?id=cf1c35c92e01384614a64ea9a66ba6d08121a4f6

commit cf1c35c92e01384614a64ea9a66ba6d08121a4f6
Author:     Gordon Bergling <gbe@FreeBSD.org>
AuthorDate: 2022-04-14 08:04:14 +0000
Commit:     Gordon Bergling <gbe@FreeBSD.org>
CommitDate: 2022-04-21 06:27:29 +0000

    time(3): Refine history in the manual page
    
    The time() system call first appeared in Version 1 AT&T UNIX.  Through
    the Version 3 AT&T UNIX, it returned 60 Hz ticks since an epoch that
    changed occasionally, because it was a 32-bit value that overflowed in a
    little over 2 years.
    
    In Version 4 AT&T UNIX the granularity of the return value was reduced to
    whole seconds, delaying the aforementioned overflow until 2038.
    
    Version 7 AT&T UNIX introduced the ftime() system call, which returned
    time at a millisecond level, though retained the gtime() system call
    (exposed as time() in userland).  time() could have been implemented as a
    wrapper around ftime(), but that wasn't done.
    
    4.1cBSD implemented a higher-precision time function gettimeofday() to
    replace ftime() and reimplemented time() in terms of that.
    
    Since FreeBSD 9 the implementation of time() uses
    clock_gettime(CLOCK_SECOND) instead of gettimeofday() for performance
    reasons.
    
    With most valuable input from Warner (imp@).
    
    Reviewed by:    0mp, jilles, imp
    Differential Revision:  https://reviews.freebsd.org/D34751
    
    (cherry picked from commit 3e0f3678eca7c3f296b9f702992737356f1792da)
---
 lib/libc/gen/time.3 | 57 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 8 deletions(-)

diff --git a/lib/libc/gen/time.3 b/lib/libc/gen/time.3
index 1563e672b3ba..52785057a56b 100644
--- a/lib/libc/gen/time.3
+++ b/lib/libc/gen/time.3
@@ -32,7 +32,7 @@
 .\"     @(#)time.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd March 4, 2022
+.Dd April 14, 2022
 .Dt TIME 3
 .Os
 .Sh NAME
@@ -49,7 +49,7 @@ The
 .Fn time
 function
 returns the value of time in seconds since 0 hours, 0 minutes,
-0 seconds, January 1, 1970, Coordinated Universal Time.
+0 seconds, January 1, 1970, Coordinated Universal Time (UTC).
 If an error occurs,
 .Fn time
 returns the value
@@ -73,12 +73,54 @@ function may fail for any of the reasons described in
 The
 .Nm
 function conforms to
-.St -p1003.1-2001 .
+.St -p1003.1-2008 .
 .Sh HISTORY
-A
+The
+.Fn time
+system call first appeared in
+.At v1 .
+Through the
+.At v3 ,
+it returned 60 Hz ticks since an epoch that changed occasionally, because it
+was a 32-bit value that overflowed in a little over 2 years.
+.Pp
+In
+.At v4
+the granularity of the return value was reduced to whole seconds,
+delaying the aforementioned overflow until 2038.
+.Pp
+.At v7
+introduced the
+.Fn ftime
+system call, which returned time at a millisecond level,
+though retained the
+.Fn gtime
+system call (exposed as
+.Fn time
+in userland).
+.Fn time
+could have been implemented as a wrapper around
+.Fn ftime ,
+but that wasn't done.
+.Pp
+.Bx 4.1c
+implemented a higher-precision time function
+.Fn gettimeofday
+to replace
+.Fn ftime
+and reimplemented
+.Fn time
+in terms of that.
+.Pp
+Since
+.Fx 9
+the implementation of
 .Fn time
-function appeared in
-.At v6 .
+uses
+.Fn clock_gettime "CLOCK_SECOND"
+instead of
+.Fn gettimeofday
+for performance reasons.
 .Sh BUGS
 Neither
 .St -isoC-99
@@ -92,8 +134,7 @@ on failure; thus, it is impossible for an application to distinguish
 the valid time value \-1 (representing the last UTC second of 1969)
 from the error return value.
 .Pp
-Systems conforming to earlier versions of the C and
-.Tn POSIX
+Systems conforming to earlier versions of the C and POSIX
 standards (including older versions of
 .Fx )
 did not set