TZUtil - A Time Zone and DST Utility
------------------------------------
Given the apparent lack of clock-related support for time zone and
DST (Daylight Saving Time) in Amiga OS, a utility like this comes handy
for people tired of re-adjusting their Amiga clocks every six months.
Usage: TZUtil TZ="<timezone>" [ISLOCAL] [RESET] [SAVEDST] [VERBOSE]
TZUtil is, at least once, given a POSIX time zone definition and
adjusts the system time according to that time zone including its
optional DST definition. The given time zone is saved to ENVARC:TZ, and
can be omitted in subsequent calls.
For a list of POSIX time zone strings, see here:
https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
This list is derived from /usr/share/zoneinfo on Linux systems and
updated frequently. The linked repository also contains a script to
create this list on any Linux system yourself.
TZUtil itself does not read the RTC and does not query NTP servers. It
only reads the system time at the time of execution.
TZUtil knows two modes of operation, depending on whether system time
(as read from the RTC by the OS, or polled via NTP) is GMT or local
time:
a) If your system time at the time of execution is GMT (as a result of
keeping your RTC in GMT, or polling GMT from an NTP server), no further
parameter is required. TZUtil will calculate your local time, including
DST, from GMT time and the time zone definition.
b) If your system time at the time of execution is local time, call
TZUtil with the ISLOCAL parameter. TZUtil will determine DST and adjust
system time accordingly. For the disadvantages of keeping the RTC
in local time, see below.
Note that TZUtil does not write any data to the battery-backed clock.
It only sets the current system time.
Emulators: Do not use TZUtil on emulators. Emulators set the RTC to
the host's system time and therefore handle time zones and DST
automatically. (Changing the time behind TZUtil's back also messes
with its DST status determination and might yield incorrect results.)
Usage examples
--------------
1) If you keep your battery-backed RTC in GMT
Preparation: Set your RTC to GMT
Run TZUtil once with the TZ parameter to hand over a time zone (which
is saved to ENVARC:TZ):
> TZUtil TZ="CET-1CEST,M3.5.0,M10.5.0"
In your user-startup, insert
TZUtil
In your network start script, read NTP time in GMT and save it to the
RTC. The call TZUtil to convert GMT to your local time. Using ntpsync
(http://aminet.net/package/util/time/NTPSync) for the NTP part, this
would read:
ntpsync -c -d0 <server>
TZUtil
2) If you keep your battery-backed RTC in local time
Preparation: Set your RTC to actual local time
Run TZUtil once with the TZ parameter to hand over a time zone (which
is saved to ENVARC:TZ):
> TZUtil TZ="CET-1CEST,M3.5.0,M10.5.0" ISLOCAL
In your user-startup, insert
TZUtil ISLOCAL
In your network start script, read NTP time in GMT and use TZUtil to
convert it to your local time. Afterwards, save it to the RTC. Using
ntpsync, this would read:
ntpsync -d0 <server>
TZUtil SAVEDST
SetClock SAVE
If your RTC battery was depleted and changed, start the Amiga, set the
RTC with your favorite tool (eg "date"+"Setclock", or Prefs) to your
actual local time, and then call
> TZUtil ISLOCAL RESET
GMT vs. Local time
------------------
It is recommended to keep the battery backed RTC in GMT. Calculating
local time and DST is failsafe if the basis is GMT.
Using local time as a basis for DST determination is tricky and not
failsafe.
If ISLOCAL is specified, TZUtil, at its first execution, determines
the DST status and saves it to ENVARC:DST_STATUS. At later executions,
TZUtil reads the DST status from this file in order to know if current
system time is DST or not. Time and DST status must therefore match.
If, for whatever reason, the RTC is reset to a different time (such as
in case of a depleted battery), time and DST status no longer match.
TZUtil tries to find out if that happened, but might not detect a
mismatch in all cases.
If you know that your battery was empty, please set the RTC to your
actual local time and invoke TZUtil with the RESET keyword once, as
shown in the Usage Examples section above.
Command line parameters
-----------------------
TZ: Time zone to use, must be a POSIX time zone definition. Needs to be
specified once, is saved to ENVARC:TZ.
ISLOCAL: Tells TZUtil that the system time currently is local time (DST
or non-DST), as opposed to GMT. In this mode of operation, TZUtils,
at its first execution, determines if local time is DST or not DST, and
saves the result of this determimation in ENVARC:DST_STATUS. Note that
local time must be your actual local time when calling TZUtil for the
first time (or when using the RESET parameter).
RESET: [Only relevant if ISLOCAL is specified, too] Resets the previous
DST determination and re-assesses if current system time is DST or not.
Use this keyword after your RTC lost power and has been re-set to local
time.
SAVEDST: Forces TZUtil to save the determined DST status when run in
GMT mode (ie with ISLOCAL not specified). Normally, when run in GMT
mode, TZUtil does not save the DST status, simply because it is not
needed: If handed GMT, TZUtil can always determine DST. In ISLOCAL
mode, TZUtil needs to keep track if "local time" (as read from the RTC)
is DST or non-DST time. If you choose to keep your RTC in "local time",
but want to sync it with NTP, TZUtil needs to run in GMT mode after
polling NTP, but in ISLOCAL mode in user-startup. Use the SAVEDST
keyword after polling NTP in order to give user-startup's TZUtil the
correct hint. See examples above.
The source code is included and written for compiling with SAS C 6.58.
Version history:
1.01 (15-Nov-2023)
- Add SAVEDST command line switch
- Fix array size for ReadArgs()
- Extend documentation
1.00 (14-Nov-2023)
- Initial release
|
aminet net>