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