Re: git: 3c9f304b383b - main - Describe modern time zone handling.
Date: Tue, 29 Mar 2022 08:12:15 UTC
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 <grog@FreeBSD.org> > AuthorDate: 2022-03-28 03:57:37 +0000 > Commit: Greg Lehey <grog@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 >