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