💾 Archived View for cugi.ie › aminet › 1700107386.gmi captured on 2024-08-31 at 13:02:22. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

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
   Readme:       http://aminet.net/util/time/TZUtil.readme
   Downloads:    42

http://aminet.net/util/time/TZUtil.lha

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