1.\" $NetBSD: zdump.8,v 1.25 2023/12/06 21:45:11 kre Exp $ 2.\" @(#)zdump.8 8.2 3.\" This file is in the public domain, so clarified as of 4.\" 2009-05-17 by Arthur David Olson. 5.\" .TH zdump 8 6.Dd December 6, 2023 7.Dt ZDUMP 8 8.Os 9.Sh NAME 10.Nm zdump 11.Nd timezone dumper 12.Sh SYNOPSIS 13.Nm zdump 14.Op Fl \-version 15.Op Fl v 16.Op Fl V 17.Op Fl c Ar [loyear,]highyear 18.Op Ar timezone ... 19.Nm zdump 20.Fl t 21.Ar [lotime,]hightime 22.Op Ar zonename ... 23.Sh DESCRIPTION 24The 25.Nm 26program prints the current time in each 27.Ar timezone 28named on the command line. 29.Sh OPTIONS 30.Bl -tag -width XXXXXXXXX -compact 31.It Fl \-version 32Output version information and exit. 33.It Fl \-help 34Output short usage message and exit. 35.It Fl i 36Output a description of time intervals. 37For each 38.Ar timezone 39on the command line, output an interval-format description of the 40timezone. 41See 42.Sx "INTERVAL FORMAT" 43below. 44.It Fl v 45Output a verbose description of time intervals. 46For each 47.Ar timezon 48on the command line, 49print the times at the two extreme time values, 50the times (if present) at and just beyond the boundaries of years that 51.Xr localtime 3 52and 53.Xr gmtime 3 54can represent, and 55the times both one second before and exactly at 56each detected time discontinuity. 57Each line is followed by 58.Em isdst=D 59where 60.Em D 61is positive, zero, or negative depending on whether 62the given time is daylight saving time, standard time, 63or an unknown time type, respectively. 64Each line is also followed by 65.Em gmtoff=N 66if the given local time is known to be 67.Em N 68seconds east of Greenwich. 69.It Fl c Ar [loyear,]highyear 70Cut off interval output at the given year(s). 71Cutoff times are computed using the proleptic Gregorian calendar with year 0 72and with Universal Time (UT) ignoring leap seconds. 73Cutoffs are at the start of each year, where the lower-bound 74timestamp is inclusive and the upper is exclusive; for example, 75.Em "\&-c 1970,2070" 76selects transitions on or after 1970-01-01 00:00:00 UTC 77and before 2070-01-01 00:00:00 UTC. 78The default cutoff is 79.Em \&-500,2500 . 80.It Fl t Ar [lotime,]hightime 81Cut off interval output at the given time(s), 82given in decimal seconds since 1970-01-01 00:00:00 83Coordinated Universal Time (UTC). 84The 85.Ar timezone 86determines whether the count includes leap seconds. 87As with 88.Fl c , 89the cutoff's lower bound is inclusive and its upper bound is exclusive. 90.It Fl V 91Like 92.Fl v , 93except omit output concerning extreme time and year values. 94This generates output that is easier to compare to that of 95implementations with different time representations. 96.El 97.Sh "INTERVAL FORMAT" 98.Pp 99The interval format is a compact text representation that is intended 100to be both human- and machine-readable. 101It consists of an empty line, then a line 102.Dq TZ=string 103where 104.Dv string 105is a double-quoted string giving the timezone, a second line 106.Dq \&- \&- interval 107describing the time interval before the first transition if any, and 108zero or more following lines 109.Dq date time interval 110one line for each transition time and following interval. 111Fields are separated by single tabs. 112.Pp 113Dates are in 114.Dv yyyy-mm-dd 115format and times are in 24-hour 116.Dv hhmmss 117format where 118.Dv hh < 24 . 119Times are in local time immediately after the transition. 120A time interval description consists of a UT offset in signed 121.Dv \&+- hh : mm : ss 122format, a time zone abbreviation, and an isdst flag. 123An abbreviation that equals the UT offset is omitted; other abbreviations are 124double-quoted strings unless they consist of one or more alphabetic 125characters. 126An isdst flag is omitted for standard time, and otherwise 127is a decimal integer that is unsigned and positive (typically 1) for 128daylight saving time and negative for unknown. 129.Pp 130In times and in UT offsets with absolute value less than 100 hours, 131the seconds are omitted if they are zero, and 132the minutes are also omitted if they are also zero. 133Positive UT offsets are east of Greenwich. The UT offset \&-00 denotes a UT 134placeholder in areas where the actual offset is unspecified; by 135convention, this occurs when the UT offset is zero and the time zone 136abbreviation begins with 137.Dq \&- 138or is 139.Dq zzz . 140.Pp 141In double-quoted strings, escape sequences represent unusual 142characters. The escape sequences are \es for space, and \e", \e\e, 143\ef, \en, \er, \et, and \ev with their usual meaning in the C 144programming language. 145E.g., the double-quoted string 146.Sq "CET\es\e"\e\e" 147represents the character sequence 148.Sq CET 149.Pp 150Here is an example of the output, with the leading empty line omitted. 151(This example is shown with tab stops set far enough apart so that the 152tabbed columns line up.) 153.Bd -literal 154TZ="Pacific/Honolulu" 155.Ed 156.Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HHMMSS" "TZT" "X" -compact 157.It - Ta - Ta -103126 Ta LMT Ta 158.It 1896-01-13 Ta 12:01:26 Ta -1030 Ta HST Ta 159.It 1933-04-30 Ta 03 Ta -0930 Ta HDT Ta 1 160.It 1933-05-21 Ta 11 Ta -1030 Ta HST Ta 161.It 1942-02-09 Ta 03 Ta -0930 Ta HDT Ta 1 162.It 1945-08-14 Ta 13:30 Ta -0930 Ta HPT Ta 1 163.It 1945-09-30 Ta 01 Ta -1030 Ta HST Ta 164.It 1947-06-08 Ta 02:30 Ta -10 Ta HST Ta 165.El 166.Pp 167Here, local time begins 10 hours, 31 minutes and 26 seconds west of 168UT, and is a standard time abbreviated LMT. Immediately after the 169first transition, the date is 1896-01-13 and the time is 12:01:26, and 170the following time interval is 10.5 hours west of UT, a standard time 171abbreviated HST. 172Immediately after the second transition, the date is 1731933-04-30 and the time is 03:00:00 and the following time interval is 1749.5 hours west of UT, is abbreviated HDT, and is daylight saving time. 175Immediately after the last transition the date is 1947-06-08 and the 176time is 02:30:00, and the following time interval is 10 hours west of 177UT, a standard time abbreviated HST. 178.Pp 179Here are excerpts from another example: 180.Bd -literal 181TZ="Europe/Astrakhan" 182.Ed 183.Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HH:MM:SS" "TZT" "X" -compact 184.It - Ta - Ta +031212 Ta LMT Ta 185.It 1924-04-30 Ta 23:47:48 Ta +03 Ta Ta 186.It 1930-06-21 Ta 01 Ta +04 Ta Ta 187.It 1981-04-01 Ta 01 Ta +05 Ta Ta 1 188.It 1981-09-30 Ta 23 Ta +04 Ta Ta 189.It \&... Ta Ta Ta Ta 190.It 2014-10-26 Ta 01 Ta +03 Ta Ta 191.It 2016-03-27 Ta 03 Ta +04 Ta Ta 192.El 193.Pp 194This time zone is east of UT, so its UT offsets are positive. Also, 195many of its time zone abbreviations are omitted since they duplicate 196the text of the UT offset. 197.Sh LIMITATIONS 198Time discontinuities are found by sampling the results returned by 199.Xr localtime 3 200at twelve-hour intervals. 201This works in all real-world cases; 202one can construct artificial time zones for which this fails. 203.Pp 204In the 205.Fl v 206and 207.Fl V 208output, 209.Dq UT 210denotes the value returned by 211.Xr gmtime 3 , 212which uses UTC for modern timestamps and some other UT flavor for 213timestamps that predate the introduction of UTC. 214No attempt is currently made to have the output use 215.Dq UTC 216for newer and 217.Dq UT 218for older timestamps, partly because the exact date of the 219introduction of UTC is problematic. 220.Sh SEE ALSO 221.Xr localtime 3 , 222.Xr tzfile 5 , 223.Xr zic 8 224