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