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