1.\" $NetBSD: zdump.8,v 1.17 2017/07/03 21:32:50 wiz Exp $ 2.Dd March 11, 2017 3.Dt ZDUMP 8 4.Os 5.Sh NAME 6.Nm zdump 7.Nd time zone 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 zonename ... 15.Nm zdump 16.Fl t 17.Ar [lotime,]hightime 18.Op Ar zonename ... 19.Sh DESCRIPTION 20.Nm 21prints the current time in each 22.Ar zonename 23named on the command line. 24.Pp 25These options are available: 26.Bl -tag -width XXXXXXXXX -compact 27.It Fl \-version 28Output version information and exit. 29.It Fl i 30.Em This option is experimental: its behavior may change in future versions. 31Output a description of time intervals. 32For each 33.Ar zonename 34on the command line, output an interval-format description of the 35zone. 36See 37.Sx "INTERVAL FORMAT" 38below. 39.It Fl v 40Output a verbose description of time intervals. 41For each 42.Ar zonename 43on the command line, 44print the time at the lowest possible time value, 45the time one day after the lowest possible time value, 46the times both one second before and exactly at 47each detected time discontinuity, 48the time at one day less than the highest possible time value, 49and the time at the highest possible time value. 50Each line is followed by 51.Em isdst=D 52where 53.Em D 54is positive, zero, or negative depending on whether 55the given time is daylight saving time, standard time, 56or an unknown time type, respectively. 57Each line is also followed by 58.Em gmtoff=N 59if the given local time is known to be 60.Em N 61seconds east of Greenwich. 62.It Fl c Ar [loyear,]highyear 63Cut off interval output at the given year(s). 64Cutoff times are computed using the proleptic Gregorian calendar with year 0 65and with Universal Time (UT) ignoring leap seconds. 66The lower bound is exclusive and the upper is inclusive; for example, a 67.Em loyear 68of 1970 excludes a transition occurring at 1970-01-01 00:00:00 UTC but a 69.Em hiyear 70of 1970 includes the transition. 71The default cutoff is 72.Em \&-500,2500 . 73.It Fl t Ar [lotime,]hightime 74Cut off interval output at the given time(s), 75given in decimal seconds since 1970-01-01 00:00:00 76Coordinated Universal Time (UTC). 77The 78.Ar zonename 79determines whether the count includes leap seconds. 80As with 81.Fl c , 82the cutoff's lower bound is exclusive and its upper bound is inclusive. 83.It Fl V 84Like 85.Fl v , 86except omit the times relative to the extreme time values. 87This generates output that is easier to compare to that of 88implementations with different time representations. 89.El 90.Sh "INTERVAL FORMAT" 91.Em This format is experimental: it may change in future versions. 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 zone name, 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" "-HH:MM:SS" "TZT" "X" -compact 151.It - Ta - Ta -10:31:26 Ta LMT Ta 152.It 1896-01-13 Ta 12:01:26 Ta -10:30 Ta HST Ta 153.It 1933-04-30 Ta 03 Ta -09:30 Ta HDT Ta 1 154.It 1933-05-21 Ta 11 Ta -10:30 Ta HST Ta 155.It 1942-02-09 Ta 03 Ta -09:30 Ta HDT Ta 1 156.It 1945-09-30 Ta 01 Ta -10:30 Ta HST Ta 157.It 1947-06-08 Ta 02:30 Ta -10 Ta HST Ta 158.El 159.Pp 160Here, local time begins 10 hours, 31 minutes and 26 seconds west of 161UT, and is a standard time abbreviated LMT. Immediately after the 162first transition, the date is 1896-01-13 and the time is 12:01:26, and 163the following time interval is 10.5 hours west of UT, a standard time 164abbreviated HST. 165Immediately after the second transition, the date is 1661933-04-30 and the time is 03:00:00 and the following time interval is 1679.5 hours west of UT, is abbreviated HDT, and is daylight saving time. 168Immediately after the last transition the date is 1947-06-08 and the 169time is 02:30:00, and the following time interval is 10 hours west of 170UT, a standard time abbreviated HST. 171.Pp 172Here are excerpts from another example: 173.Bd -literal 174TZ="Europe/Astrakhan" 175.Ed 176.Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HH:MM:SS" "TZT" "X" -compact 177.It - Ta - Ta +03:12:12 Ta LMT Ta 178.It 1924-04-30 Ta 23:47:48 Ta +03 Ta Ta 179.It 1930-06-21 Ta 01 Ta +04 Ta Ta 180.It 1981-04-01 Ta 01 Ta +05 Ta Ta 1 181.It 1981-09-30 Ta 23 Ta +04 Ta Ta 182.It \&... Ta Ta Ta Ta 183.It 2014-10-26 Ta 01 Ta +03 Ta Ta 184.It 2016-03-27 Ta 03 Ta +04 Ta Ta 185.El 186.Pp 187This time zone is east of UT, so its UT offsets are positive. Also, 188many of its time zone abbreviations are omitted since they duplicate 189the text of the UT offset. 190.Sh LIMITATIONS 191Time discontinuities are found by sampling the results returned by localtime 192at twelve-hour intervals. 193This works in all real-world cases; 194one can construct artificial time zones for which this fails. 195.Pp 196In the 197.Fl v 198and 199.Fl V 200output, 201.Dq UT 202denotes the value returned by 203.Xr gmtime 3 , 204which uses UTC for modern time stamps and some other UT flavor for 205time stamps that predate the introduction of UTC. 206No attempt is currently made to have the output use 207.Dq UTC 208for newer and 209.Dq UT 210for older time stamps, partly because the exact date of the 211introduction of UTC is problematic. 212.Sh SEE ALSO 213.Xr ctime 3 , 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