Hey Greg,
I've noticed a couple of minor issues in the patch.
On 28/03/2022 05:59, Greg Lehey wrote:
The branch main has been updated by grog:
URL:
https://cgit.FreeBSD.org/src/commit/?id=3c9f304b383bd378757ac33393b02f457947bc50
commit 3c9f304b383bd378757ac33393b02f457947bc50
Author: Greg Lehey <g...@freebsd.org>
AuthorDate: 2022-03-28 03:57:37 +0000
Commit: Greg Lehey <g...@freebsd.org>
CommitDate: 2022-03-28 03:57:37 +0000
Describe modern time zone handling.
Reviewed by: peterj@
MFC after: 2 weeks
That's probably a typo, but it is a good idea to leave an empty line after the first line. Otherwise
Git tooling thinks all the lines belong to the title of the commit message and it makes for a really
long email subject. ;)
---
bin/date/date.1 | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 83 insertions(+), 11 deletions(-)
diff --git a/bin/date/date.1 b/bin/date/date.1
index 0aaae1614327..e4aad28c7d81 100644
--- a/bin/date/date.1
+++ b/bin/date/date.1
@@ -195,6 +195,13 @@ Print the date and time of the last modification of
Display or set the date in
.Tn UTC
(Coordinated Universal) time.
+By default
+.Nm
+displays the time in the time zone described by
+.Pa /etc/localtime
+or the
+.Ev TZ
+environment variable.
.It Xo
.Fl v
.Sm off
@@ -337,10 +344,61 @@ Seconds, a number from 0 to 60
.Pp
Everything but the minutes is optional.
.Pp
-Time changes for Daylight Saving Time, standard time, leap seconds,
+.Nm
+understands the time zone definitions in the
+.Nm tzdata
+package located in
+.Pa /usr/share/zoneinfo .
+This requires the kernel clock to be set to UTC.
+Time changes for Daylight Saving Time, standard time, leap seconds
and leap years are handled automatically.
+.Pp
+There are two ways to specify the time zone:
+.Pp
+If the file or symlink
+.Pa /etc/localtime
+exists, it is interpreted as a time zone definition file, usually in
+the directory hierarchy
+.Pa /usr/share/zoneinfo ,
+which contains the time zone definitions from the
+.Nm tzdata
+package.
+.Pp
+If the environment variable
+.Ev TZ
+is set, its value is interpreted as the name of a time zone definition
+file, either an absolute path or a relative path to a time zone
+definition in
+.Pa /usr/share/zoneinfo .
+The
+.Ev TZ
+variable overrides
+.Pa /etc/localtime .
+.Pp
+If the time zone definition file is invalid,
+.Nm
+silently reverts to UTC.
+.Pp
+Previous versions of
+.Nm
+included the
+.Fl d
+(set daylight saving time flag) and
+.Fl t
+(set negative time zone offset) options, but these details are now
+handled automatically by
+.Nm tzdata .
This should be Sy instead of Nm. From what I understand, Nm should be used only when referring to
the subject of the manual page (in this case, "date").
+Modern offsets are positive for time zones ahead of UTC and negative
+for time zones behind UTC, but like the obsolete
+.Nm t
Nm should be Fl.
+option, the
+.Nm tzdata
I'd change Nm to Sy.
+files in the subdirectory
+.Pa /usr/share/zoneinfo/Etc
+still use an older convention where times ahead of UTC are considered
+negative.
.Sh ENVIRONMENT
-The following environment variables affect the execution of
+The following environment variable affects the execution of
.Nm :
.Bl -tag -width Ds
.It Ev TZ
@@ -350,16 +408,22 @@ The normal format is a pathname relative to
For example, the command
.Dq TZ=America/Los_Angeles date
displays the current time in California.
+The variable can also specify an absolute path.
See
.Xr environ 7
for more information.
.El
.Sh FILES
.Bl -tag -width /var/log/messages -compact
-.It Pa /var/log/utx.log
-record of date resets and time changes
+.It Pa /etc/localtime
+Time zone information file for default system time zone.
+May be omitted, in which case the default time zone is UTC.
+.It Pa /usr/share/zoneinfo
+Directory containing time zone information files.
.It Pa /var/log/messages
record of the user setting the time
+.It Pa /var/log/utx.log
+record of date resets and time changes
Perhaps unrelated to this change, but it would be nice to make all descriptions consistent (start
with a capital letter, finish with a period).
.El
.Sh EXIT STATUS
The
@@ -463,13 +527,14 @@ If this occurs,
.Nm
prints:
.Ql multiple output formats specified
-and exits with an error status.
+and exits with status 1.
I'm not sure if we want to limit ourselves to 1. Perhaps it's better to just say it is non-zero so
that we can have the flexibility in the future to return different exit codes for different errors.
.Sh SEE ALSO
.Xr locale 1 ,
.Xr gettimeofday 2 ,
.Xr getutxent 3 ,
.Xr strftime 3 ,
-.Xr strptime 3
+.Xr strptime 3 ,
+.Xr ntpd 8
.Rs
.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
.%A R. Gusella
@@ -480,11 +545,9 @@ The
.Nm
utility is expected to be compatible with
.St -p1003.2 .
-The
-.Fl f , I , j , r ,
-and
-.Fl v
-options are all extensions to the standard.
+With the exception of the
+.Fl u
+option, all options are extensions to the standard.
.Pp
The format selected by the
.Fl I
@@ -496,6 +559,15 @@ A
command appeared in
.At v1 .
.Pp
+A number of options were added and then removed again, including the
+.Fl d
+(set DST flag) and
+.Fl t
+(set negative time zone offset).
+Time zones are now handled by the
+.Nm tzdata
Nm should be Sy.
Ideally, we should create a manual page for tzdata and just use Xr here.
+package.
+.Pp
The
.Fl I
flag was added in
