mirror of https://github.com/mkerrisk/man-pages
zdump.8: Sync from tzdb upstream
Make zdump.8 a copy of the upstream tzdb version, except that the tzdb version's first line is replaced by man-pages boilerplate. This has the following effect: Document new options -i, -t, -V. New section LIMITATIONS. Do some minor reformatting. Omit some changes that were made on the man-pages side, notably by changing some "timezone"s back to the preferred-upstream "time zone" when talking about traditional time zones as opposed to POSIX timezone settings. Also, fix some formatting glitches. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
a312fa038d
commit
09c05a89e3
219
man8/zdump.8
219
man8/zdump.8
|
@ -6,26 +6,47 @@
|
|||
.SH NAME
|
||||
zdump \- timezone dumper
|
||||
.SH SYNOPSIS
|
||||
.BR zdump " [" \-\-version "] [" \-\-help "] [" \-v "] [" \-c
|
||||
.RI [ loyear \fB,\fR] hiyear "] [\fIzonename\fP...]"
|
||||
.B zdump
|
||||
[
|
||||
.I option
|
||||
\&... ] [
|
||||
.I timezone
|
||||
\&... ]
|
||||
.SH DESCRIPTION
|
||||
.ie '\(lq'' .ds lq \&"\"
|
||||
.el .ds lq \(lq\"
|
||||
.ie '\(rq'' .ds rq \&"\"
|
||||
.el .ds rq \(rq\"
|
||||
.de q
|
||||
\\$3\*(lq\\$1\*(rq\\$2
|
||||
..
|
||||
.ie \n(.g .ds - \f(CW-\fP
|
||||
.el ds - \-
|
||||
The
|
||||
.B zdump
|
||||
program prints the current time in each
|
||||
.I zonename
|
||||
.I timezone
|
||||
named on the command line.
|
||||
.PP
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.B \-\-version
|
||||
.B \*-\*-version
|
||||
Output version information and exit.
|
||||
.TP
|
||||
.B \-\-help
|
||||
.B \*-\*-help
|
||||
Output short usage message and exit.
|
||||
.TP
|
||||
.B \-v
|
||||
.B \*-i
|
||||
Output a description of time intervals. For each
|
||||
.I timezone
|
||||
on the command line, output an interval-format description of the
|
||||
timezone. See
|
||||
.q "INTERVAL FORMAT"
|
||||
below.
|
||||
.TP
|
||||
.B \*-v
|
||||
Output a verbose description of time intervals.
|
||||
For each
|
||||
.I zonename
|
||||
.I timezone
|
||||
on the command line,
|
||||
print the time at the lowest possible time value,
|
||||
the time one day after the lowest possible time value,
|
||||
|
@ -33,18 +54,178 @@ the times both one second before and exactly at
|
|||
each detected time discontinuity,
|
||||
the time at one day less than the highest possible time value,
|
||||
and the time at the highest possible time value.
|
||||
Each line ends with
|
||||
.B isdst=1
|
||||
if the given time is Daylight Saving Time or
|
||||
.B isdst=0
|
||||
otherwise.
|
||||
Each line is followed by
|
||||
.BI isdst= D
|
||||
where
|
||||
.I D
|
||||
is positive, zero, or negative depending on whether
|
||||
the given time is daylight saving time, standard time,
|
||||
or an unknown time type, respectively.
|
||||
Each line is also followed by
|
||||
.BI gmtoff= N
|
||||
if the given local time is known to be
|
||||
.I N
|
||||
seconds east of Greenwich.
|
||||
.TP
|
||||
.BI "\-c " \fR[\fIloyear , \fR]\fIhiyear
|
||||
Cut off the verbose output near the start of the given year(s).
|
||||
The output still includes the lowest possible time value
|
||||
and one day after it, and the highest possible time value
|
||||
preceded by the time value one day before it.
|
||||
.B \*-V
|
||||
Like
|
||||
.BR \*-v ,
|
||||
except omit the times relative to the extreme time values.
|
||||
This generates output that is easier to compare to that of
|
||||
implementations with different time representations.
|
||||
.TP
|
||||
.BI "\*-c " \fR[\fIloyear , \fR]\fIhiyear
|
||||
Cut off interval output at the given year(s).
|
||||
Cutoff times are computed using the proleptic Gregorian calendar with year 0
|
||||
and with Universal Time (UT) ignoring leap seconds.
|
||||
The lower bound is exclusive and the upper is inclusive; for example, a
|
||||
.I loyear
|
||||
of 1970 excludes a transition occurring at 1970-01-01 00:00:00 UTC but a
|
||||
.I hiyear
|
||||
of 1970 includes the transition.
|
||||
The default cutoff is
|
||||
.BR \*-500,2500 .
|
||||
.TP
|
||||
.BI "\*-t " \fR[\fIlotime , \fR]\fIhitime
|
||||
Cut off interval output at the given time(s),
|
||||
given in decimal seconds since 1970-01-01 00:00:00
|
||||
Coordinated Universal Time (UTC).
|
||||
The
|
||||
.I timezone
|
||||
determines whether the count includes leap seconds.
|
||||
As with
|
||||
.BR \*-c ,
|
||||
the cutoff's lower bound is exclusive and its upper bound is inclusive.
|
||||
.SH "INTERVAL FORMAT"
|
||||
The interval format is a compact text representation that is intended
|
||||
to be both human- and machine-readable. It consists of an empty line,
|
||||
then a line
|
||||
.q "TZ=\fIstring\fP"
|
||||
where
|
||||
.I string
|
||||
is a double-quoted string giving the timezone, a second line
|
||||
.q "\*- \*- \fIinterval\fP"
|
||||
describing the time interval before the first transition if any, and
|
||||
zero or more following lines
|
||||
.q "\fIdate time interval\fP",
|
||||
one line for each transition time and following interval. Fields are
|
||||
separated by single tabs.
|
||||
.PP
|
||||
Dates are in
|
||||
.IR yyyy - mm - dd
|
||||
format and times are in 24-hour
|
||||
.IR hh : mm : ss
|
||||
format where
|
||||
.IR hh <24.
|
||||
Times are in local time immediately after the transition. A
|
||||
time interval description consists of a UT offset in signed
|
||||
.RI \(+- hhmmss
|
||||
format, a time zone abbreviation, and an isdst flag. An abbreviation
|
||||
that equals the UT offset is omitted; other abbreviations are
|
||||
double-quoted strings unless they consist of one or more alphabetic
|
||||
characters. An isdst flag is omitted for standard time, and otherwise
|
||||
is a decimal integer that is unsigned and positive (typically 1) for
|
||||
daylight saving time and negative for unknown.
|
||||
.PP
|
||||
In times and in UT offsets with absolute value less than 100 hours,
|
||||
the seconds are omitted if they are zero, and
|
||||
the minutes are also omitted if they are also zero. Positive UT
|
||||
offsets are east of Greenwich. The UT offset \*-00 denotes a UT
|
||||
placeholder in areas where the actual offset is unspecified; by
|
||||
convention, this occurs when the UT offset is zero and the time zone
|
||||
abbreviation begins with
|
||||
.q "\*-"
|
||||
or is
|
||||
.q "zzz".
|
||||
.PP
|
||||
In double-quoted strings, escape sequences represent unusual
|
||||
characters. The escape sequences are \es for space, and \e", \e\e,
|
||||
\ef, \en, \er, \et, and \ev with their usual meaning in the C
|
||||
programming language. E.g., the double-quoted string
|
||||
\*(lq"CET\es\e"\e\e"\*(rq represents the character sequence \*(lqCET
|
||||
"\e\*(rq.\""
|
||||
.PP
|
||||
.ne 9
|
||||
Here is an example of the output, with the leading empty line omitted.
|
||||
(This example is shown with tab stops set far enough apart so that the
|
||||
tabbed columns line up.)
|
||||
.nf
|
||||
.sp
|
||||
.if \n(.g .ft CW
|
||||
.if t .in +.5i
|
||||
.if n .in +2
|
||||
.nr w \w'1896-01-13 'u
|
||||
.ta \nwu +\nwu +\nwu +\nwu
|
||||
TZ="Pacific/Honolulu"
|
||||
- - -10:31:26 LMT
|
||||
1896-01-13 12:01:26 -10:30 HST
|
||||
1933-04-30 03 -09:30 HDT 1
|
||||
1933-05-21 11 -10:30 HST
|
||||
1942-02-09 03 -09:30 HDT 1
|
||||
1945-09-30 01 -10:30 HST
|
||||
1947-06-08 02:30 -10 HST
|
||||
.in
|
||||
.if \n(.g .ft
|
||||
.sp
|
||||
.fi
|
||||
Here, local time begins 10 hours, 31 minutes and 26 seconds west of
|
||||
UT, and is a standard time abbreviated LMT. Immediately after the
|
||||
first transition, the date is 1896-01-13 and the time is 12:01:26, and
|
||||
the following time interval is 10.5 hours west of UT, a standard time
|
||||
abbreviated HST. Immediately after the second transition, the date is
|
||||
1933-04-30 and the time is 03:00:00 and the following time interval is
|
||||
9.5 hours west of UT, is abbreviated HDT, and is daylight saving time.
|
||||
Immediately after the last transition the date is 1947-06-08 and the
|
||||
time is 02:30:00, and the following time interval is 10 hours west of
|
||||
UT, a standard time abbreviated HST.
|
||||
.PP
|
||||
.ne 10
|
||||
Here are excerpts from another example:
|
||||
.nf
|
||||
.sp
|
||||
.if \n(.g .ft CW
|
||||
.if t .in +.5i
|
||||
.if n .in +2
|
||||
TZ="Europe/Astrakhan"
|
||||
- - +03:12:12 LMT
|
||||
1924-04-30 23:47:48 +03
|
||||
1930-06-21 01 +04
|
||||
1981-04-01 01 +05 1
|
||||
1981-09-30 23 +04
|
||||
\&...
|
||||
2014-10-26 01 +03
|
||||
2016-03-27 03 +04
|
||||
.in
|
||||
.if \n(.g .ft
|
||||
.sp
|
||||
.fi
|
||||
This time zone is east of UT, so its UT offsets are positive. Also,
|
||||
many of its time zone abbreviations are omitted since they duplicate
|
||||
the text of the UT offset.
|
||||
.SH LIMITATIONS
|
||||
Time discontinuities are found by sampling the results returned by localtime
|
||||
at twelve-hour intervals.
|
||||
This works in all real-world cases;
|
||||
one can construct artificial time zones for which this fails.
|
||||
.PP
|
||||
In the
|
||||
.B \*-v
|
||||
and
|
||||
.B \*-V
|
||||
output,
|
||||
.q "UT"
|
||||
denotes the value returned by
|
||||
.IR gmtime (3),
|
||||
which uses UTC for modern timestamps and some other UT flavor for
|
||||
timestamps that predate the introduction of UTC.
|
||||
No attempt is currently made to have the output use
|
||||
.q "UTC"
|
||||
for newer and
|
||||
.q "UT"
|
||||
for older timestamps, partly because the exact date of the
|
||||
introduction of UTC is problematic.
|
||||
.SH SEE ALSO
|
||||
.BR tzfile (5),
|
||||
.BR zic (8)
|
||||
.\" @(#)zdump.8 7.3
|
||||
.\" This file is in the public domain, so clarified as of
|
||||
.\" 2009-05-17 by Arthur David Olson.
|
||||
|
|
Loading…
Reference in New Issue