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 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="" [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 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 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