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