time(3): Update the HISTORY section
ClosedPublic
Actions

Authored by gbe on Apr 2 2022, 2:38 PM.

Details

Reviewers

imp
pauamma_gundo.com
0mp
jilles

Group Reviewers

manpages

Commits

rG6b642cf5c874: time(3): Refine history in the manual page
rGcf1c35c92e01: time(3): Refine history in the manual page
rGdd19f0e9c006: time(3): Refine history in the manual page
rG3e0f3678eca7: time(3): Refine history in the manual page

Summary

Be more precise of the return values of time(3) in historic versions
Update the POSIX conformance from 2001 to 2008

Obtained from: OpenBSD
MFC after: 1 week

Test Plan

mandoc output review and 'mandoc -Tlint' checks

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

gbe requested review of this revision.Apr 2 2022, 2:38 PM

gbe created this revision.

Harbormaster completed remote builds in B44966: Diff 104502.Apr 2 2022, 2:38 PM

And your excuse for not calling this "A brief history of time(3)" is?

This revision is now accepted and ready to land.Apr 2 2022, 2:45 PM

Close, but the history isn't quite right. See my comments.

lib/libc/gen/time.3
52	extra 'i' here.
124	This change to seconds happened in the 4th edition, not the 6th edition. The 3rd edition returned time in 1/HZ (1/60) since Jan 1, 1972. The 1st and 2nd Edition return since Jan 1, 1971
128	This is close, but not quite right. v7 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.1c implemented a higher-precision time function (gettimeofday) to replace ftime() and reimplemented time() in terms of that.

imp added inline comments.Apr 2 2022, 3:04 PM

lib/libc/gen/time.3
124	The new epoch in the 3rd edition presents challenges to reconstructing dates from tapes... And the headaches with it motivated the change in the 4th edition...

jilles added a subscriber: jilles.Apr 2 2022, 6:43 PM

jilles added inline comments.

lib/libc/gen/time.3
128	And a more recent change: git commit 358ed16f750576f266ebf86ea1ee56204d71bb52 (in 9.0 and 8.1) changed the implementation of `time()` to use `clock_gettime(CLOCK_SECOND)` instead of `gettimeofday()`, for performance reasons. The practical effect is that applications should use `time()` if a resolution of 1 second is good enough for them; `time()` is standard but `CLOCK_SECOND` is not.

Address comments from jilles and imp

This revision now requires review to proceed.Apr 3 2022, 9:57 AM

Harbormaster completed remote builds in B44974: Diff 104528.Apr 3 2022, 9:57 AM

Address feedback from @jilles and @imp

0mp accepted this revision.Apr 3 2022, 11:59 AM

This revision is now accepted and ready to land.Apr 3 2022, 11:59 AM

jilles accepted this revision.Apr 3 2022, 1:59 PM

imp added inline comments.Apr 3 2022, 5:04 PM

lib/libc/gen/time.3
129	I'd make this briefer: "The time system call first appeared in 1st edition. Through the 3rd edition, 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." and maybe leave out the tape date information. It's a bit more verbose than we normally do. And tape dates varied because they were both the 1971 and 1972 epoch, and you never knew which type of tape you had.
137	i386 is the only platform left with a 32-bit time_t, and the only one affected by the crisis. not entirely sure how to work that into this, however.

Updates for recent comments

Rework the first HISTORY paragraph according to @imp's suggestions
Remove a usless .Tn macro

This revision now requires review to proceed.Apr 10 2022, 7:34 AM

Harbormaster completed remote builds in B45103: Diff 104834.Apr 10 2022, 7:34 AM

Updates for some comments on the first paragraph.

lib/libc/gen/time.3
137	I left this out for the moment, since I am not sure what about arm6, or is i386 the only left 32bit architecture?

Looks good to me. Thanks!

This revision is now accepted and ready to land.Apr 10 2022, 8:31 PM

jilles accepted this revision.Apr 10 2022, 8:34 PM

pauamma_gundo.com added inline comments.Apr 10 2022, 9:52 PM

lib/libc/gen/time.3
82
96
113
137	I left this out for the moment, since I am not sure what about arm6, or is i386 the only left 32bit architecture? https://cgit.freebsd.org/src/tree/sys/arm/include/_types.h (which I think is arm[4-6]) has typedef __int64_t __time_t; /* time()... */