[BACK]Return to zdump.8 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/zdump.8, Revision 1.19

1.19    ! christos    1: .\"    $NetBSD: zdump.8,v 1.18 2018/10/19 23:05:35 christos Exp $
        !             2: .Dd October 27, 2018
1.6       joerg       3: .Dt ZDUMP 8
1.4       wiz         4: .Os
                      5: .Sh NAME
                      6: .Nm zdump
1.18      christos    7: .Nd timezone dumper
1.4       wiz         8: .Sh SYNOPSIS
                      9: .Nm zdump
1.5       kleink     10: .Op Fl \-version
1.4       wiz        11: .Op Fl v
1.10      christos   12: .Op Fl V
1.7       mlelstv    13: .Op Fl c Ar [loyear,]highyear
1.18      christos   14: .Op Ar timezone ...
1.10      christos   15: .Nm zdump
                     16: .Fl t
1.13      christos   17: .Ar [lotime,]hightime
1.10      christos   18: .Op Ar zonename ...
1.4       wiz        19: .Sh DESCRIPTION
1.18      christos   20: The
1.4       wiz        21: .Nm
1.18      christos   22: program prints the current time in each
                     23: .Ar timezone
1.1       jtc        24: named on the command line.
1.18      christos   25: .SH OPTIONS
1.5       kleink     26: .Bl -tag -width XXXXXXXXX -compact
                     27: .It Fl \-version
                     28: Output version information and exit.
1.18      christos   29: .It Fl \-help
                     30: Output short usage message and exit.
1.15      christos   31: .It Fl i
                     32: Output a description of time intervals.
                     33: For each
1.18      christos   34: .Ar timezone
1.15      christos   35: on the command line, output an interval-format description of the
1.18      christos   36: timezone.
1.15      christos   37: See
                     38: .Sx "INTERVAL FORMAT"
                     39: below.
1.4       wiz        40: .It Fl v
1.15      christos   41: Output a verbose description of time intervals.
1.1       jtc        42: For each
1.18      christos   43: .Ar timezon
1.1       jtc        44: on the command line,
1.3       jtc        45: print the time at the lowest possible time value,
1.1       jtc        46: the time one day after the lowest possible time value,
                     47: the times both one second before and exactly at
                     48: each detected time discontinuity,
                     49: the time at one day less than the highest possible time value,
1.13      christos   50: and the time at the highest possible time value.
                     51: Each line is followed by
1.15      christos   52: .Em isdst=D
1.13      christos   53: where
1.15      christos   54: .Em D
1.13      christos   55: is positive, zero, or negative depending on whether
                     56: the given time is daylight saving time, standard time,
                     57: or an unknown time type, respectively.
                     58: Each line is also followed by
1.15      christos   59: .Em gmtoff=N
1.13      christos   60: if the given local time is known to be
1.15      christos   61: .Em N
1.13      christos   62: seconds east of Greenwich.
1.7       mlelstv    63: .It Fl c Ar [loyear,]highyear
1.15      christos   64: Cut off interval output at the given year(s).
1.13      christos   65: Cutoff times are computed using the proleptic Gregorian calendar with year 0
                     66: and with Universal Time (UT) ignoring leap seconds.
                     67: The lower bound is exclusive and the upper is inclusive; for example, a
1.15      christos   68: .Em loyear
1.14      christos   69: of 1970 excludes a transition occurring at 1970-01-01 00:00:00 UTC but a
1.15      christos   70: .Em hiyear
1.13      christos   71: of 1970 includes the transition.
                     72: The default cutoff is
1.15      christos   73: .Em \&-500,2500 .
1.13      christos   74: .It Fl t Ar [lotime,]hightime
1.15      christos   75: Cut off interval output at the given time(s),
1.13      christos   76: given in decimal seconds since 1970-01-01 00:00:00
                     77: Coordinated Universal Time (UTC).
                     78: The
1.18      christos   79: .Ar timezone
1.13      christos   80: determines whether the count includes leap seconds.
                     81: As with
                     82: .Fl c ,
                     83: the cutoff's lower bound is exclusive and its upper bound is inclusive.
1.10      christos   84: .It Fl V
                     85: Like
                     86: .Fl v ,
                     87: except omit the times relative to the extreme time values.
                     88: This generates output that is easier to compare to that of
                     89: implementations with different time representations.
1.4       wiz        90: .El
1.15      christos   91: .Sh "INTERVAL FORMAT"
                     92: .Pp
                     93: The interval format is a compact text representation that is intended
                     94: to be both human- and machine-readable.
                     95: It consists of an empty line, then a line
                     96: .Dq TZ=string
                     97: where
                     98: .Dv string
1.18      christos   99: is a double-quoted string giving the timezone, a second line
1.15      christos  100: .Dq \&- \&- interval
                    101: describing the time interval before the first transition if any, and
                    102: zero or more following lines
                    103: .Dq date time interval
                    104: one line for each transition time and following interval.
                    105: Fields are separated by single tabs.
                    106: .Pp
                    107: Dates are in
                    108: .Dv yyyy-mm-dd
                    109: format and times are in 24-hour
1.16      christos  110: .Dv hhmmss
1.15      christos  111: format where
1.17      wiz       112: .Dv hh < 24 .
1.15      christos  113: Times are in local time immediately after the transition.
                    114: A time interval description consists of a UT offset in signed
                    115: .Dv \&+- hh : mm : ss
                    116: format, a time zone abbreviation, and an isdst flag.
                    117: An abbreviation that equals the UT offset is omitted; other abbreviations are
                    118: double-quoted strings unless they consist of one or more alphabetic
                    119: characters.
                    120: An isdst flag is omitted for standard time, and otherwise
                    121: is a decimal integer that is unsigned and positive (typically 1) for
                    122: daylight saving time and negative for unknown.
                    123: .Pp
1.16      christos  124: In times and in UT offsets with absolute value less than 100 hours,
                    125: the seconds are omitted if they are zero, and
1.15      christos  126: the minutes are also omitted if they are also zero.
                    127: Positive UT offsets are east of Greenwich.  The UT offset \&-00 denotes a UT
                    128: placeholder in areas where the actual offset is unspecified; by
                    129: convention, this occurs when the UT offset is zero and the time zone
                    130: abbreviation begins with
                    131: .Dq \&-
                    132: or is
                    133: .Dq zzz .
                    134: .Pp
                    135: In double-quoted strings, escape sequences represent unusual
                    136: characters.  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
                    138: programming language.
                    139: E.g., the double-quoted string
                    140: .Sq "CET\es\e"\e\e"
                    141: represents the character sequence
                    142: .Sq CET
                    143: .Pp
                    144: Here 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
                    146: tabbed columns line up.)
                    147: .Bd -literal
                    148: TZ="Pacific/Honolulu"
                    149: .Ed
1.19    ! christos  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
1.15      christos  158: .It 1947-06-08 Ta 02:30 Ta -10 Ta HST Ta
                    159: .El
                    160: .Pp
                    161: Here, local time begins 10 hours, 31 minutes and 26 seconds west of
                    162: UT, and is a standard time abbreviated LMT.  Immediately after the
                    163: first transition, the date is 1896-01-13 and the time is 12:01:26, and
                    164: the following time interval is 10.5 hours west of UT, a standard time
                    165: abbreviated HST.
                    166: Immediately after the second transition, the date is
                    167: 1933-04-30 and the time is 03:00:00 and the following time interval is
                    168: 9.5 hours west of UT, is abbreviated HDT, and is daylight saving time.
                    169: Immediately after the last transition the date is 1947-06-08 and the
                    170: time is 02:30:00, and the following time interval is 10 hours west of
                    171: UT, a standard time abbreviated HST.
                    172: .Pp
                    173: Here are excerpts from another example:
                    174: .Bd -literal
                    175: TZ="Europe/Astrakhan"
                    176: .Ed
                    177: .Bl -column "XXXX-XX-XX" "HH:MM:SS" "-HH:MM:SS" "TZT" "X" -compact
1.19    ! christos  178: .It - Ta - Ta +031212 Ta LMT Ta
1.15      christos  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
                    188: This time zone is east of UT, so its UT offsets are positive.  Also,
                    189: many of its time zone abbreviations are omitted since they duplicate
                    190: the text of the UT offset.
1.8       joerg     191: .Sh LIMITATIONS
1.7       mlelstv   192: Time discontinuities are found by sampling the results returned by localtime
                    193: at twelve-hour intervals.
                    194: This works in all real-world cases;
                    195: one can construct artificial time zones for which this fails.
1.11      christos  196: .Pp
1.15      christos  197: In the
                    198: .Fl v
                    199: and
                    200: .Fl V
                    201: output,
1.11      christos  202: .Dq UT
                    203: denotes the value returned by
                    204: .Xr gmtime 3 ,
1.18      christos  205: which uses UTC for modern timestamps and some other UT flavor for
                    206: timestamps that predate the introduction of UTC.
1.11      christos  207: No attempt is currently made to have the output use
                    208: .Dq UTC
                    209: for newer and
                    210: .Dq UT
1.18      christos  211: for older timestamps, partly because the exact date of the
1.15      christos  212: introduction of UTC is problematic.
1.4       wiz       213: .Sh SEE ALSO
                    214: .Xr tzfile 5 ,
                    215: .Xr zic 8
1.7       mlelstv   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.

CVSweb <webmaster@jp.NetBSD.org>