"Fossies" - the Fresh Open Source Software Archive

Member "zic.8.txt" (26 Nov 2022, 26657 Bytes) of package /linux/misc/tzcode2022g.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "zic.8.txt": 2022f_vs_2022g.

    1 zic(8)                      System Manager's Manual                     zic(8)
    3 NAME
    4        zic - timezone compiler
    7        zic [ option ... ] [ filename ... ]
   10        The zic program reads text from the file(s) named on the command line
   11        and creates the timezone information format (TZif) files specified in
   12        this input.  If a filename is "-", standard input is read.
   15        --version
   16               Output version information and exit.
   18        --help Output short usage message and exit.
   20        -b bloat
   21               Output backward-compatibility data as specified by bloat.  If
   22               bloat is fat, generate additional data entries that work around
   23               potential bugs or incompatibilities in older software, such as
   24               software that mishandles the 64-bit generated data.  If bloat is
   25               slim, keep the output files small; this can help check for the
   26               bugs and incompatibilities.  The default is slim, as software
   27               that mishandles 64-bit data typically mishandles timestamps
   28               after the year 2038 anyway.  Also see the -r option for another
   29               way to alter output size.
   31        -d directory
   32               Create time conversion information files in the named directory
   33               rather than in the standard directory named below.
   35        -l timezone
   36               Use timezone as local time.  zic will act as if the input
   37               contained a link line of the form
   39                    Link  timezone  localtime
   41               If timezone is -, any already-existing link is removed.
   43        -L leapsecondfilename
   44               Read leap second information from the file with the given name.
   45               If this option is not used, no leap second information appears
   46               in output files.
   48        -p timezone
   49               Use timezone's rules when handling nonstandard TZ strings like
   50               "EET-2EEST" that lack transition rules.  zic will act as if the
   51               input contained a link line of the form
   53                    Link  timezone  posixrules
   55               This feature is obsolete and poorly supported.  Among other
   56               things it should not be used for timestamps after the year 2037,
   57               and it should not be combined with -b slim if timezone's
   58               transitions are at standard time or Universal Time (UT) instead
   59               of local time.
   61               If timezone is -, any already-existing link is removed.
   63        -r [@lo][/@hi]
   64               Limit the applicability of output files to timestamps in the
   65               range from lo (inclusive) to hi (exclusive), where lo and hi are
   66               possibly-signed decimal counts of seconds since the Epoch
   67               (1970-01-01 00:00:00 UTC).  Omitted counts default to extreme
   68               values.  The output files use UT offset 0 and abbreviation "-00"
   69               in place of the omitted timestamp data.  For example, "zic -r
   70               @0" omits data intended for negative timestamps (i.e., before
   71               the Epoch), and "zic -r @0/@2147483648" outputs data intended
   72               only for nonnegative timestamps that fit into 31-bit signed
   73               integers.  On platforms with GNU date, "zic -r @$(date +%s)"
   74               omits data intended for past timestamps.  Although this option
   75               typically reduces the output file's size, the size can increase
   76               due to the need to represent the timestamp range boundaries,
   77               particularly if hi causes a TZif file to contain explicit
   78               entries for pre-hi transitions rather than concisely
   79               representing them with an extended POSIX TZ string.  Also see
   80               the -b slim option for another way to shrink output size.
   82        -R @hi Generate redundant trailing explicit transitions for timestamps
   83               that occur less than hi seconds since the Epoch, even though the
   84               transitions could be more concisely represented via the extended
   85               POSIX TZ string.  This option does not affect the represented
   86               timestamps.  Although it accommodates nonstandard TZif readers
   87               that ignore the extended POSIX TZ string, it increases the size
   88               of the altered output files.
   90        -t file
   91               When creating local time information, put the configuration link
   92               in the named file rather than in the standard location.
   94        -v     Be more verbose, and complain about the following situations:
   96               The input specifies a link to a link, something not supported by
   97               some older parsers, including zic itself through release 2022e.
   99               A year that appears in a data file is outside the range of
  100               representable years.
  102               A time of 24:00 or more appears in the input.  Pre-1998 versions
  103               of zic prohibit 24:00, and pre-2007 versions prohibit times
  104               greater than 24:00.
  106               A rule goes past the start or end of the month.  Pre-2004
  107               versions of zic prohibit this.
  109               A time zone abbreviation uses a %z format.  Pre-2015 versions of
  110               zic do not support this.
  112               A timestamp contains fractional seconds.  Pre-2018 versions of
  113               zic do not support this.
  115               The input contains abbreviations that are mishandled by pre-2018
  116               versions of zic due to a longstanding coding bug.  These
  117               abbreviations include "L" for "Link", "mi" for "min", "Sa" for
  118               "Sat", and "Su" for "Sun".
  120               The output file does not contain all the information about the
  121               long-term future of a timezone, because the future cannot be
  122               summarized as an extended POSIX TZ string.  For example, as of
  123               2019 this problem occurs for Iran's daylight-saving rules for
  124               the predicted future, as these rules are based on the Iranian
  125               calendar, which cannot be represented.
  127               The output contains data that may not be handled properly by
  128               client code designed for older zic output formats.  These
  129               compatibility issues affect only timestamps before 1970 or after
  130               the start of 2038.
  132               The output contains a truncated leap second table, which can
  133               cause some older TZif readers to misbehave.  This can occur if
  134               the -L option is used, and either an Expires line is present or
  135               the -r option is also used.
  137               The output file contains more than 1200 transitions, which may
  138               be mishandled by some clients.  The current reference client
  139               supports at most 2000 transitions; pre-2014 versions of the
  140               reference client support at most 1200 transitions.
  142               A time zone abbreviation has fewer than 3 or more than 6
  143               characters.  POSIX requires at least 3, and requires
  144               implementations to support at least 6.
  146               An output file name contains a byte that is not an ASCII letter,
  147               "-", "/", or "_"; or it contains a file name component that
  148               contains more than 14 bytes or that starts with "-".
  150 FILES
  151        Input files use the format described in this section; output files use
  152        tzfile(5) format.
  154        Input files should be text files, that is, they should be a series of
  155        zero or more lines, each ending in a newline byte and containing at
  156        most 2048 bytes counting the newline, and without any NUL bytes.  The
  157        input text's encoding is typically UTF-8 or ASCII; it should have a
  158        unibyte representation for the POSIX Portable Character Set (PPCS)
  159        <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06
  160        .html> and the encoding's non-unibyte characters should consist
  161        entirely of non-PPCS bytes.  Non-PPCS characters typically occur only
  162        in comments: although output file names and time zone abbreviations can
  163        contain nearly any character, other software will work better if these
  164        are limited to the restricted syntax described under the -v option.
  166        Input lines are made up of fields.  Fields are separated from one
  167        another by one or more white space characters.  The white space
  168        characters are space, form feed, carriage return, newline, tab, and
  169        vertical tab.  Leading and trailing white space on input lines is
  170        ignored.  An unquoted sharp character (#) in the input introduces a
  171        comment which extends to the end of the line the sharp character
  172        appears on.  White space characters and sharp characters may be
  173        enclosed in double quotes (") if they're to be used as part of a field.
  174        Any line that is blank (after comment stripping) is ignored.  Nonblank
  175        lines are expected to be of one of three types: rule lines, zone lines,
  176        and link lines.
  178        Names must be in English and are case insensitive.  They appear in
  179        several contexts, and include month and weekday names and keywords such
  180        as maximum, only, Rolling, and Zone.  A name can be abbreviated by
  181        omitting all but an initial prefix; any abbreviation must be
  182        unambiguous in context.
  184        A rule line has the form
  186             Rule  NAME  FROM  TO    -  IN   ON       AT     SAVE   LETTER/S
  188        For example:
  190             Rule  US    1967  1973  -  Apr  lastSun  2:00w  1:00d  D
  192        The fields that make up a rule line are:
  194        NAME    Gives the name of the rule set that contains this line.  The
  195                name must start with a character that is neither an ASCII digit
  196                nor "-" nor "+".  To allow for future extensions, an unquoted
  197                name should not contain characters from the set
  198                "!$%&'()*,/:;<=>?@[\]^`{|}~".
  200        FROM    Gives the first year in which the rule applies.  Any signed
  201                integer year can be supplied; the proleptic Gregorian calendar
  202                is assumed, with year 0 preceding year 1.  The word minimum (or
  203                an abbreviation) means the indefinite past.  The word maximum
  204                (or an abbreviation) means the indefinite future.  Rules can
  205                describe times that are not representable as time values, with
  206                the unrepresentable times ignored; this allows rules to be
  207                portable among hosts with differing time value types.
  209        TO      Gives the final year in which the rule applies.  In addition to
  210                minimum and maximum (as above), the word only (or an
  211                abbreviation) may be used to repeat the value of the FROM
  212                field.
  214        -       Is a reserved field and should always contain "-" for
  215                compatibility with older versions of zic.  It was previously
  216                known as the TYPE field, which could contain values to allow a
  217                separate script to further restrict in which "types" of years
  218                the rule would apply.
  220        IN      Names the month in which the rule takes effect.  Month names
  221                may be abbreviated.
  223        ON      Gives the day on which the rule takes effect.  Recognized forms
  224                include:
  226                     5        the fifth of the month
  227                     lastSun  the last Sunday in the month
  228                     lastMon  the last Monday in the month
  229                     Sun>=8   first Sunday on or after the eighth
  230                     Sun<=25  last Sunday on or before the 25th
  232                A weekday name (e.g., Sunday) or a weekday name preceded by
  233                "last" (e.g., lastSunday) may be abbreviated or spelled out in
  234                full.  There must be no white space characters within the ON
  235                field.  The "<=" and ">=" constructs can result in a day in the
  236                neighboring month; for example, the IN-ON combination "Oct
  237                Sun>=31" stands for the first Sunday on or after October 31,
  238                even if that Sunday occurs in November.
  240        AT      Gives the time of day at which the rule takes effect, relative
  241                to 00:00, the start of a calendar day.  Recognized forms
  242                include:
  244                     2            time in hours
  245                     2:00         time in hours and minutes
  246                     01:28:14     time in hours, minutes, and seconds
  247                     00:19:32.13  time with fractional seconds
  248                     12:00        midday, 12 hours after 00:00
  249                     15:00        3 PM, 15 hours after 00:00
  250                     24:00        end of day, 24 hours after 00:00
  251                     260:00       260 hours after 00:00
  252                     -2:30        2.5 hours before 00:00
  253                     -            equivalent to 0
  255                Although zic rounds times to the nearest integer second
  256                (breaking ties to the even integer), the fractions may be
  257                useful to other applications requiring greater precision.  The
  258                source format does not specify any maximum precision.  Any of
  259                these forms may be followed by the letter w if the given time
  260                is local or "wall clock" time, s if the given time is standard
  261                time without any adjustment for daylight saving, or u (or g or
  262                z) if the given time is universal time; in the absence of an
  263                indicator, local (wall clock) time is assumed.  These forms
  264                ignore leap seconds; for example, if a leap second occurs at
  265                00:59:60 local time, "1:00" stands for 3601 seconds after local
  266                midnight instead of the usual 3600 seconds.  The intent is that
  267                a rule line describes the instants when a clock/calendar set to
  268                the type of time specified in the AT field would show the
  269                specified date and time of day.
  271        SAVE    Gives the amount of time to be added to local standard time
  272                when the rule is in effect, and whether the resulting time is
  273                standard or daylight saving.  This field has the same format as
  274                the AT field except with a different set of suffix letters: s
  275                for standard time and d for daylight saving time.  The suffix
  276                letter is typically omitted, and defaults to s if the offset is
  277                zero and to d otherwise.  Negative offsets are allowed; in
  278                Ireland, for example, daylight saving time is observed in
  279                winter and has a negative offset relative to Irish Standard
  280                Time.  The offset is merely added to standard time; for
  281                example, zic does not distinguish a 10:30 standard time plus an
  282                0:30 SAVE from a 10:00 standard time plus a 1:00 SAVE.
  284        LETTER/S
  285                Gives the "variable part" (for example, the "S" or "D" in "EST"
  286                or "EDT") of time zone abbreviations to be used when this rule
  287                is in effect.  If this field is "-", the variable part is null.
  289        A zone line has the form
  291             Zone  NAME        STDOFF  RULES   FORMAT  [UNTIL]
  293        For example:
  295             Zone  Asia/Amman  2:00    Jordan  EE%sT   2017 Oct 27 01:00
  297        The fields that make up a zone line are:
  299        NAME  The name of the timezone.  This is the name used in creating the
  300              time conversion information file for the timezone.  It should not
  301              contain a file name component "." or ".."; a file name component
  302              is a maximal substring that does not contain "/".
  304        STDOFF
  305              The amount of time to add to UT to get standard time, without any
  306              adjustment for daylight saving.  This field has the same format
  307              as the AT and SAVE fields of rule lines, except without suffix
  308              letters; begin the field with a minus sign if time must be
  309              subtracted from UT.
  311        RULES The name of the rules that apply in the timezone or,
  312              alternatively, a field in the same format as a rule-line SAVE
  313              column, giving the amount of time to be added to local standard
  314              time and whether the resulting time is standard or daylight
  315              saving.  If this field is - then standard time always applies.
  316              When an amount of time is given, only the sum of standard time
  317              and this amount matters.
  319        FORMAT
  320              The format for time zone abbreviations.  The pair of characters
  321              %s is used to show where the "variable part" of the time zone
  322              abbreviation goes.  Alternatively, a format can use the pair of
  323              characters %z to stand for the UT offset in the form +-hh,
  324              +-hhmm, or +-hhmmss, using the shortest form that does not lose
  325              information, where hh, mm, and ss are the hours, minutes, and
  326              seconds east (+) or west (-) of UT.  Alternatively, a slash (/)
  327              separates standard and daylight abbreviations.  To conform to
  328              POSIX, a time zone abbreviation should contain only alphanumeric
  329              ASCII characters, "+" and "-".  By convention, the time zone
  330              abbreviation "-00" is a placeholder that means local time is
  331              unspecified.
  333        UNTIL The time at which the UT offset or the rule(s) change for a
  334              location.  It takes the form of one to four fields YEAR [MONTH
  335              [DAY [TIME]]].  If this is specified, the time zone information
  336              is generated from the given UT offset and rule change until the
  337              time specified, which is interpreted using the rules in effect
  338              just before the transition.  The month, day, and time of day have
  339              the same format as the IN, ON, and AT fields of a rule; trailing
  340              fields can be omitted, and default to the earliest possible value
  341              for the missing fields.
  343              The next line must be a "continuation" line; this has the same
  344              form as a zone line except that the string "Zone" and the name
  345              are omitted, as the continuation line will place information
  346              starting at the time specified as the "until" information in the
  347              previous line in the file used by the previous line.
  348              Continuation lines may contain "until" information, just as zone
  349              lines do, indicating that the next line is a further
  350              continuation.
  352        If a zone changes at the same instant that a rule would otherwise take
  353        effect in the earlier zone or continuation line, the rule is ignored.
  354        A zone or continuation line L with a named rule set starts with
  355        standard time by default: that is, any of L's timestamps preceding L's
  356        earliest rule use the rule in effect after L's first transition into
  357        standard time.  In a single zone it is an error if two rules take
  358        effect at the same instant, or if two zone changes take effect at the
  359        same instant.
  361        If a continuation line subtracts N seconds from the UT offset after a
  362        transition that would be interpreted to be later if using the
  363        continuation line's UT offset and rules, the "until" time of the
  364        previous zone or continuation line is interpreted according to the
  365        continuation line's UT offset and rules, and any rule that would
  366        otherwise take effect in the next N seconds is instead assumed to take
  367        effect simultaneously.  For example:
  369          # Rule  NAME  FROM  TO    -  IN   ON       AT    SAVE  LETTER/S
  370          Rule    US    1967  2006  -  Oct  lastSun  2:00  0     S
  371          Rule    US    1967  1973  -  Apr  lastSun  2:00  1:00  D
  372          # Zone  NAME             STDOFF  RULES  FORMAT  [UNTIL]
  373          Zone  America/Menominee  -5:00   -      EST     1973 Apr 29 2:00
  374                                   -6:00   US     C%sT
  376        Here, an incorrect reading would be there were two clock changes on
  377        1973-04-29, the first from 02:00 EST (-05) to 01:00 CST (-06), and the
  378        second an hour later from 02:00 CST (-06) to 03:00 CDT (-05).  However,
  379        zic interprets this more sensibly as a single transition from 02:00 CST
  380        (-05) to 02:00 CDT (-05).
  382        A link line has the form
  384             Link  TARGET           LINK-NAME
  386        For example:
  388             Link  Europe/Istanbul  Asia/Istanbul
  390        The TARGET field should appear as the NAME field in some zone line or
  391        as the LINK-NAME field in some link line.  The LINK-NAME field is used
  392        as an alternative name for that zone; it has the same syntax as a zone
  393        line's NAME field.  Links can chain together, although the behavior is
  394        unspecified if a chain of one or more links does not terminate in a
  395        Zone name.  A link line can appear before the line that defines the
  396        link target.  For example:
  398          Link  Greenwich  G_M_T
  399          Link  Etc/GMT    Greenwich
  400          Zone  Etc/GMT  0  -  GMT
  402        The two links are chained together, and G_M_T, Greenwich, and Etc/GMT
  403        all name the same zone.
  405        Except for continuation lines, lines may appear in any order in the
  406        input.  However, the behavior is unspecified if multiple zone or link
  407        lines define the same name.
  409        The file that describes leap seconds can have leap lines and an
  410        expiration line.  Leap lines have the following form:
  412             Leap  YEAR  MONTH  DAY  HH:MM:SS  CORR  R/S
  414        For example:
  416             Leap  2016  Dec    31   23:59:60  +     S
  418        The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second
  419        happened.  The CORR field should be "+" if a second was added or "-" if
  420        a second was skipped.  The R/S field should be (an abbreviation of)
  421        "Stationary" if the leap second time given by the other fields should
  422        be interpreted as UTC or (an abbreviation of) "Rolling" if the leap
  423        second time given by the other fields should be interpreted as local
  424        (wall clock) time.
  426        Rolling leap seconds were implemented back when it was not clear
  427        whether common practice was rolling or stationary, with concerns that
  428        one would see Times Square ball drops where there'd be a "3... 2...
  429        1... leap... Happy New Year" countdown, placing the leap second at
  430        midnight New York time rather than midnight UTC.  However, this
  431        countdown style does not seem to have caught on, which means rolling
  432        leap seconds are not used in practice; also, they are not supported if
  433        the -r option is used.
  435        The expiration line, if present, has the form:
  437             Expires  YEAR  MONTH  DAY  HH:MM:SS
  439        For example:
  441             Expires  2020  Dec    28   00:00:00
  443        The YEAR, MONTH, DAY, and HH:MM:SS fields give the expiration timestamp
  444        in UTC for the leap second table.
  447        Here is an extended example of zic input, intended to illustrate many
  448        of its features.
  450          # Rule  NAME  FROM  TO    -  IN   ON       AT    SAVE  LETTER/S
  451          Rule    Swiss 1941  1942  -  May  Mon>=1   1:00  1:00  S
  452          Rule    Swiss 1941  1942  -  Oct  Mon>=1   2:00  0     -
  453          Rule    EU    1977  1980  -  Apr  Sun>=1   1:00u 1:00  S
  454          Rule    EU    1977  only  -  Sep  lastSun  1:00u 0     -
  455          Rule    EU    1978  only  -  Oct   1       1:00u 0     -
  456          Rule    EU    1979  1995  -  Sep  lastSun  1:00u 0     -
  457          Rule    EU    1981  max   -  Mar  lastSun  1:00u 1:00  S
  458          Rule    EU    1996  max   -  Oct  lastSun  1:00u 0     -
  460          # Zone  NAME           STDOFF      RULES  FORMAT  [UNTIL]
  461          Zone    Europe/Zurich  0:34:08     -      LMT     1853 Jul 16
  462                                 0:29:45.50  -      BMT     1894 Jun
  463                                 1:00        Swiss  CE%sT   1981
  464                                 1:00        EU     CE%sT
  466          Link    Europe/Zurich  Europe/Vaduz
  468        In this example, the EU rules are for the European Union and for its
  469        predecessor organization, the European Communities.  The timezone is
  470        named Europe/Zurich and it has the alias Europe/Vaduz.  This example
  471        says that Zurich was 34 minutes and 8 seconds east of UT until
  472        1853-07-16 at 00:00, when the legal offset was changed to 7 degrees 26
  473        minutes 22.50 seconds, which works out to 0:29:45.50; zic treats this
  474        by rounding it to 0:29:46.  After 1894-06-01 at 00:00 the UT offset
  475        became one hour and Swiss daylight saving rules (defined with lines
  476        beginning with "Rule Swiss") apply.  From 1981 to the present, EU
  477        daylight saving rules have applied, and the UTC offset has remained at
  478        one hour.
  480        In 1941 and 1942, daylight saving time applied from the first Monday in
  481        May at 01:00 to the first Monday in October at 02:00.  The pre-1981 EU
  482        daylight-saving rules have no effect here, but are included for
  483        completeness.  Since 1981, daylight saving has begun on the last Sunday
  484        in March at 01:00 UTC.  Until 1995 it ended the last Sunday in
  485        September at 01:00 UTC, but this changed to the last Sunday in October
  486        starting in 1996.
  488        For purposes of display, "LMT" and "BMT" were initially used,
  489        respectively.  Since Swiss rules and later EU rules were applied, the
  490        time zone abbreviation has been CET for standard time and CEST for
  491        daylight saving time.
  493 FILES
  494        /etc/localtime
  495               Default local timezone file.
  497        /usr/share/zoneinfo
  498               Default timezone information directory.
  500 NOTES
  501        For areas with more than two types of local time, you may need to use
  502        local standard time in the AT field of the earliest transition time's
  503        rule to ensure that the earliest transition time recorded in the
  504        compiled file is correct.
  506        If, for a particular timezone, a clock advance caused by the start of
  507        daylight saving coincides with and is equal to a clock retreat caused
  508        by a change in UT offset, zic produces a single transition to daylight
  509        saving at the new UT offset without any change in local (wall clock)
  510        time.  To get separate transitions use multiple zone continuation lines
  511        specifying transition instants using universal time.
  513 SEE ALSO
  514        tzfile(5), zdump(8)
  516                                                                         zic(8)