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