AminetAminet
Search:
84420 packages online
About
Recent
Browse
Search
Upload
Setup
Services

util/time/TZUtil.lha

Mirror:Random
Showing:m68k-amigaosgeneric
No screenshot available
Short:Time Zone and DST Utility
Author:Thomas Winischhofer
Uploader:thomas winischhofer net (Thomas Winischhofer)
Type:util/time
Version:1.01
Replaces:util/time/dstd.lha
Architecture:m68k-amigaos >= 2.0
Date:2023-11-15
Download:http://aminet.net/util/time/TZUtil.lha - View contents
Readme:http://aminet.net/util/time/TZUtil.readme
Downloads:212

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




Contents of util/time/TZUtil.lha
PERMISSION  UID  GID    PACKED    SIZE  RATIO METHOD CRC     STAMP     NAME
---------- ----------- ------- ------- ------ ---------- ------------ ----------
[unknown]                 9638   16076  60.0% -lh5- 652f Nov 13 21:59 TZUtil
[unknown]                 8977   29255  30.7% -lh5- 3b23 Nov 14 08:48 TZUtil.cpp
[unknown]                 2525    6168  40.9% -lh5- ba54 Nov 14 08:49 TZUtil.readme
---------- ----------- ------- ------- ------ ---------- ------------ ----------
 Total         3 files   21140   51499  41.0%            Nov 16 04:03

Aminet © 1992-2024 Urban Müller and the Aminet team. Aminet contact address: <aminetaminet net>