1.\" $NetBSD: zdump.8,v 1.15 2016/10/07 15:29:42 christos Exp $ 2.Dd October 6, 2016 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 hh:mm:ss 111format where 112.Dv hh \*[Lt] 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 UT offsets, the seconds are omitted if they are zero, and 125the minutes are also omitted if they are also zero. 126Positive UT offsets are east of Greenwich. The UT offset \&-00 denotes a UT 127placeholder in areas where the actual offset is unspecified; by 128convention, this occurs when the UT offset is zero and the time zone 129abbreviation begins with 130.Dq \&- 131or is 132.Dq zzz . 133.Pp 134In double-quoted strings, escape sequences represent unusual 135characters. The escape sequences are \es for space, and \e", \e\e, 136\ef, \en, \er, \et, and \ev with their usual meaning in the C 137programming language. 138E.g., the double-quoted string 139.Sq "CET\es\e"\e\e" 140represents the character sequence 141.Sq CET 142.Pp 143Here is an example of the output, with the leading empty line omitted. 144(This example is shown with tab stops set far enough apart so that the 145tabbed columns line up.) 146.Bd -literal 147TZ="Pacific/Honolulu" 148.Ed 149.Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HH:MM:SS" "TZT" "X" -compact 150.It - Ta - Ta -10:31:26 Ta LMT Ta 151.It 1896-01-13 Ta 12:01:26 Ta -10:30 Ta HST Ta 152.It 1933-04-30 Ta 03 Ta -09:30 Ta HDT Ta 1 153.It 1933-05-21 Ta 11 Ta -10:30 Ta HST Ta 154.It 1942-02-09 Ta 03 Ta -09:30 Ta HDT Ta 1 155.It 1945-09-30 Ta 01 Ta -10:30 Ta HST Ta 156.It 1947-06-08 Ta 02:30 Ta -10 Ta HST Ta 157.El 158.Pp 159Here, local time begins 10 hours, 31 minutes and 26 seconds west of 160UT, and is a standard time abbreviated LMT. Immediately after the 161first transition, the date is 1896-01-13 and the time is 12:01:26, and 162the following time interval is 10.5 hours west of UT, a standard time 163abbreviated HST. 164Immediately after the second transition, the date is 1651933-04-30 and the time is 03:00:00 and the following time interval is 1669.5 hours west of UT, is abbreviated HDT, and is daylight saving time. 167Immediately after the last transition the date is 1947-06-08 and the 168time is 02:30:00, and the following time interval is 10 hours west of 169UT, a standard time abbreviated HST. 170.Pp 171Here are excerpts from another example: 172.Bd -literal 173TZ="Europe/Astrakhan" 174.Ed 175.Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HH:MM:SS" "TZT" "X" -compact 176.It - Ta - Ta +03:12:12 Ta LMT Ta 177.It 1924-04-30 Ta 23:47:48 Ta +03 Ta Ta 178.It 1930-06-21 Ta 01 Ta +04 Ta Ta 179.It 1981-04-01 Ta 01 Ta +05 Ta Ta 1 180.It 1981-09-30 Ta 23 Ta +04 Ta Ta 181.It \&... Ta Ta Ta Ta 182.It 2014-10-26 Ta 01 Ta +03 Ta Ta 183.It 2016-03-27 Ta 03 Ta +04 Ta Ta 184.El 185.Pp 186This time zone is east of UT, so its UT offsets are positive. Also, 187many of its time zone abbreviations are omitted since they duplicate 188the text of the UT offset. 189.Sh LIMITATIONS 190Time discontinuities are found by sampling the results returned by localtime 191at twelve-hour intervals. 192This works in all real-world cases; 193one can construct artificial time zones for which this fails. 194.Pp 195In the 196.Fl v 197and 198.Fl V 199output, 200.Dq UT 201denotes the value returned by 202.Xr gmtime 3 , 203which uses UTC for modern time stamps and some other UT flavor for 204time stamps that predate the introduction of UTC. 205No attempt is currently made to have the output use 206.Dq UTC 207for newer and 208.Dq UT 209for older time stamps, partly because the exact date of the 210introduction of UTC is problematic. 211.Sh SEE ALSO 212.Xr ctime 3 , 213.Xr tzfile 5 , 214.Xr zic 8 215.\" @(#)zdump.8 8.2 216.\" This file is in the public domain, so clarified as of 217.\" 2009-05-17 by Arthur David Olson. 218