Thanks for the review. I pushed the following patch into the experimental repository to try to fix (or at least document) the problems that you noted. diff --git a/newctime.3 b/newctime.3 index 8528deb..ece8507 100644 --- a/newctime.3 +++ b/newctime.3 @@ -36,8 +36,6 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time to .I Ctime\^ converts a long integer, pointed to by .IR clock , -representing the time in seconds since -00:00:00 UTC, 1970-01-01, and returns a pointer to a string of the form .br @@ -59,6 +57,17 @@ These unusual formats are designed to make it less likely that older software that expects exactly 26 bytes of output will mistakenly output misleading values for out-of-range years. .PP +The +.BI * clock +time stamp represents the time in seconds since 1970-01-01 00:00:00 +Coordinated Universal Time (UTC). +The POSIX standard says that time stamps must be nonnegative +must ignore leap seconds. +Many implementations extend POSIX by allowing negative time stamps, +and can therefore represent time stamps that that predate the +introduction of UTC and are some other flavor of Universal Time (UT). +Some implementations support leap seconds, in contradiction to POSIX. +.PP .I Localtime\^ and .I gmtime\^ @@ -186,6 +195,7 @@ is non-zero if summer time is in effect. is the offset (in seconds) of the time represented from UT, with positive values indicating east of the Prime Meridian. +The field's name is derived from Greenwich Mean Time, a precursor of UT. .SH FILES .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u /usr/local/etc/zoneinfo time zone information directory diff --git a/newstrftime.3 b/newstrftime.3 index 5b0dcdc..d39915c 100644 --- a/newstrftime.3 +++ b/newstrftime.3 @@ -164,7 +164,7 @@ using AM/PM notation. is replaced by the second as a decimal number (00-60). .TP %s -is replaced by the number of seconds since the Epoch, UT (see mktime(3)). +is replaced by the number of seconds since the Epoch (see newctime(3)). .TP %T is replaced by the time in the format %H:%M:%S. @@ -211,7 +211,8 @@ is replaced by the time zone name, or by the empty string if this is not determinable. .TP %z -is replaced by the offset from UT in the format +HHMM or -HHMM as appropriate, +is replaced by the offset from the Prime Meridian +in the format +HHMM or \(miHHMM as appropriate, with positive values representing locations east of Greenwich, or by the empty string if this is not determinable. .TP diff --git a/newtzset.3 b/newtzset.3 index 8162920..3689e50 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -27,8 +27,9 @@ If .B TZ appears in the environment but its value is a null string, Universal Time (UT) is used, with the abbreviation "UTC" -and without leap second -correction. If +and without leap second correction; please see +.IR newctime (3) +for more about UT, UTC, and leap seconds. If .B TZ appears in the environment and its value is not a null string: .IP diff --git a/zdump.8 b/zdump.8 index af3277d..106361a 100644 --- a/zdump.8 +++ b/zdump.8 @@ -61,6 +61,14 @@ Time discontinuities are found by sampling the results returned by localtime at twelve-hour intervals. This works in all real-world cases; one can construct artificial time zones for which this fails. +.PP +In the output, "UT" denotes the value returned by +.IR gmtime (3), +which uses UTC for modern time stamps and some other UT flavor for +time stamps that predate the introduction of UTC. +No attempt is currently made to have the output use "UTC" for newer +and "UT" for older time stamps, +partly because the exact date of the introduction of UTC is problematic. .SH "SEE ALSO" newctime(3), tzfile(5), zic(8) .\" This file is in the public domain, so clarified as of