zic.8.txt

   1 ZIC(8)                      System Manager's Manual                     ZIC(8)
   2
   3 NAME
   4        zic - time zone compiler
   5
   6 SYNOPSIS
   7        zic [ option ... ] [ filename ... ]
   8
   9 DESCRIPTION
  10        Zic reads text from the file(s) named on the command line and creates
  11        the time conversion information files specified in this input.  If a
  12        filename is "-", the standard input is read.
  13
  14        These options are available:
  15
  16        --version
  17               Output version information and exit.
  18
  19        -d directory
  20               Create time conversion information files in the named directory
  21               rather than in the standard directory named below.
  22
  23        -l timezone
  24               Use the given time zone as local time.  Zic will act as if the
  25               input contained a link line of the form
  26
  27                    Link timezone       localtime
  28
  29        -p timezone
  30               Use the given time zone's rules when handling POSIX-format time
  31               zone environment variables.  Zic will act as if the input
  32               contained a link line of the form
  33
  34                    Link timezone       posixrules
  35
  36        -L leapsecondfilename
  37               Read leap second information from the file with the given name.
  38               If this option is not used, no leap second information appears
  39               in output files.
  40
  41        -v     Be more verbose, and complain about the following situations:
  42
  43               The input specifies a link to a link.
  44
  45               A year that appears in a data file is outside the range of years
  46               representable by time(2) values.
  47
  48               A time of 24:00 or more appears in the input.  Pre-1998 versions
  49               of zic prohibit 24:00, and pre-2007 versions prohibit times
  50               greater than 24:00.
  51
  52               A rule goes past the start or end of the month.  Pre-2004
  53               versions of zic prohibit this.
  54
  55               The output file does not contain all the information about the
  56               long-term future of a zone, because the future cannot be
  57               summarized as an extended POSIX TZ string.  For example, as of
  58               2013 this problem occurs for Iran's daylight-saving rules for
  59               the predicted future, as these rules are based on the Iranian
  60               calendar, which cannot be represented.
  61
  62               The output contains data that may not be handled properly by
  63               client code designed for older zic output formats.  These
  64               compatibility issues affect only time stamps before 1970 or
  65               after the start of 2038.
  66
  67               A time zone abbreviation has fewer than 3 characters.  POSIX
  68               requires at least 3.
  69
  70               An output file name contains a byte that is not an ASCII letter,
  71               "-", "/", or "_"; or it contains a file name component that
  72               contains more than 14 bytes or that starts with "-".
  73
  74        -s     Limit time values stored in output files to values that are the
  75               same whether they're taken to be signed or unsigned.  You can
  76               use this option to generate SVVS-compatible files.
  77
  78        Input files should be text files, that is, they should be a series of
  79        zero or more lines, each ending in a newline byte and containing at
  80        most 511 bytes, and without any NUL bytes.  The input text's encoding
  81        is typically UTF-8 or ASCII; it should have a unibyte representation
  82        for the POSIX Portable Character Set (PPCS) <http://pubs.opengroup.org/
  83        onlinepubs/9699919799/basedefs/V1_chap06.html> and the encoding's non-
  84        unibyte characters should consist entirely of non-PPCS bytes.  Non-PPCS
  85        characters typically occur only in comments: although output file names
  86        and time zone abbreviations can contain nearly any character, other
  87        software will work better if these are limited to the restricted syntax
  88        described under the -v option.
  89
  90        Input lines are made up of fields.  Fields are separated from one
  91        another by one or more white space characters.  The white space
  92        characters are space, form feed, carriage return, newline, tab, and
  93        vertical tab.  Leading and trailing white space on input lines is
  94        ignored.  An unquoted sharp character (#) in the input introduces a
  95        comment which extends to the end of the line the sharp character
  96        appears on.  White space characters and sharp characters may be
  97        enclosed in double quotes (") if they're to be used as part of a field.
  98        Any line that is blank (after comment stripping) is ignored.  Non-blank
  99        lines are expected to be of one of three types: rule lines, zone lines,
 100        and link lines.
 101
 102        Names must be in English and are case insensitive.  They appear in
 103        several contexts, and include month and weekday names and keywords such
 104        as maximum, only, Rolling, and Zone.  A name can be abbreviated by
 105        omitting all but an initial prefix; any abbreviation must be
 106        unambiguous in context.
 107
 108        A rule line has the form
 109
 110             Rule  NAME  FROM  TO    TYPE  IN   ON       AT    SAVE  LETTER/S
 111
 112        For example:
 113
 114             Rule  US    1967  1973  -     Apr  lastSun  2:00  1:00  D
 115
 116        The fields that make up a rule line are:
 117
 118        NAME    Gives the (arbitrary) name of the set of rules this rule is
 119                part of.
 120
 121        FROM    Gives the first year in which the rule applies.  Any integer
 122                year can be supplied; the proleptic Gregorian calendar is
 123                assumed.  The word minimum (or an abbreviation) means the
 124                minimum year representable as an integer.  The word maximum (or
 125                an abbreviation) means the maximum year representable as an
 126                integer.  Rules can describe times that are not representable
 127                as time values, with the unrepresentable times ignored; this
 128                allows rules to be portable among hosts with differing time
 129                value types.
 130
 131        TO      Gives the final year in which the rule applies.  In addition to
 132                minimum and maximum (as above), the word only (or an
 133                abbreviation) may be used to repeat the value of the FROM
 134                field.
 135
 136        TYPE    should be "-" and is present for compatibility with older
 137                versions of zic in which it could contain year types.
 138
 139        IN      Names the month in which the rule takes effect.  Month names
 140                may be abbreviated.
 141
 142        ON      Gives the day on which the rule takes effect.  Recognized forms
 143                include:
 144
 145                     5        the fifth of the month
 146                     lastSun  the last Sunday in the month
 147                     lastMon  the last Monday in the month
 148                     Sun>=8   first Sunday on or after the eighth
 149                     Sun<=25  last Sunday on or before the 25th
 150
 151                A weekday name (e.g., Sunday) or a weekday name preceded by
 152                "last" (e.g., lastSunday) may be abbreviated or spelled out in
 153                full.  Note that there must be no spaces within the ON field.
 154
 155        AT      Gives the time of day at which the rule takes effect.
 156                Recognized forms include:
 157
 158                     2        time in hours
 159                     2:00     time in hours and minutes
 160                     15:00    24-hour format time (for times after noon)
 161                     1:28:14  time in hours, minutes, and seconds
 162                     -        equivalent to 0
 163
 164                where hour 0 is midnight at the start of the day, and hour 24
 165                is midnight at the end of the day.  Any of these forms may be
 166                followed by the letter w if the given time is local "wall
 167                clock" time, s if the given time is local "standard" time, or u
 168                (or g or z) if the given time is universal time; in the absence
 169                of an indicator, wall clock time is assumed.  The intent is
 170                that a rule line describes the instants when a clock/calendar
 171                set to the type of time specified in the AT field would show
 172                the specified date and time of day.
 173
 174        SAVE    Gives the amount of time to be added to local standard time
 175                when the rule is in effect.  This field has the same format as
 176                the AT field (although, of course, the w and s suffixes are not
 177                used).  Only the sum of standard time and this amount matters;
 178                for example, zic does not distinguish a 10:30 standard time
 179                plus an 0:30 SAVE from a 10:00 standard time plus a 1:00 SAVE.
 180
 181        LETTER/S
 182                Gives the "variable part" (for example, the "S" or "D" in "EST"
 183                or "EDT") of time zone abbreviations to be used when this rule
 184                is in effect.  If this field is "-", the variable part is null.
 185
 186        A zone line has the form
 187
 188             Zone  NAME                GMTOFF  RULES/SAVE  FORMAT  [UNTILYEAR [MONTH [DAY [TIME]]]]
 189
 190        For example:
 191
 192             Zone  Australia/Adelaide  9:30    Aus         AC%sT   1971 Oct 31  2:00
 193
 194        The fields that make up a zone line are:
 195
 196        NAME  The name of the time zone.  This is the name used in creating the
 197              time conversion information file for the zone.  It should not
 198              contain a file name component "." or ".."; a file name component
 199              is a maximal substring that does not contain "/".
 200
 201        GMTOFF
 202              The amount of time to add to UT to get standard time in this
 203              zone.  This field has the same format as the AT and SAVE fields
 204              of rule lines; begin the field with a minus sign if time must be
 205              subtracted from UT.
 206
 207        RULES/SAVE
 208              The name of the rule(s) that apply in the time zone or,
 209              alternately, an amount of time to add to local standard time.  If
 210              this field is - then standard time always applies in the time
 211              zone.  When an amount of time is given, only the sum of standard
 212              time and this amount matters.
 213
 214        FORMAT
 215              The format for time zone abbreviations in this time zone.  The
 216              pair of characters %s is used to show where the "variable part"
 217              of the time zone abbreviation goes.  Alternately, a format can
 218              use the pair of characters %z to stand for the UTC offset in the
 219              form +-hh, +-hhmm, or +-hhmmss, using the shortest form that does
 220              not lose information, where hh, mm, and ss are the hours,
 221              minutes, and seconds east (+) or west (-) of UTC.  Alternately, a
 222              slash (/) separates standard and daylight abbreviations.  To
 223              conform to POSIX, a time zone abbreviation should contain only
 224              alphanumeric ASCII characters, "+" and "-".
 225
 226        UNTILYEAR [MONTH [DAY [TIME]]]
 227              The time at which the UT offset or the rule(s) change for a
 228              location.  It is specified as a year, a month, a day, and a time
 229              of day.  If this is specified, the time zone information is
 230              generated from the given UT offset and rule change until the time
 231              specified, which is interpreted using the rules in effect just
 232              before the transition.  The month, day, and time of day have the
 233              same format as the IN, ON, and AT fields of a rule; trailing
 234              fields can be omitted, and default to the earliest possible value
 235              for the missing fields.
 236
 237              The next line must be a "continuation" line; this has the same
 238              form as a zone line except that the string "Zone" and the name
 239              are omitted, as the continuation line will place information
 240              starting at the time specified as the "until" information in the
 241              previous line in the file used by the previous line.
 242              Continuation lines may contain "until" information, just as zone
 243              lines do, indicating that the next line is a further
 244              continuation.
 245
 246        If a zone changes at the same instant that a rule would otherwise take
 247        effect in the earlier zone or continuation line, the rule is ignored.
 248        In a single zone it is an error if two rules take effect at the same
 249        instant, or if two zone changes take effect at the same instant.
 250
 251        A link line has the form
 252
 253             Link  TARGET           LINK-NAME
 254
 255        For example:
 256
 257             Link  Europe/Istanbul  Asia/Istanbul
 258
 259        The TARGET field should appear as the NAME field in some zone line.
 260        The LINK-NAME field is used as an alternate name for that zone; it has
 261        the same syntax as a zone line's NAME field.
 262
 263        Except for continuation lines, lines may appear in any order in the
 264        input.  However, the behavior is unspecified if multiple zone or link
 265        lines define the same name, or if the source of one link line is the
 266        target of another.
 267
 268        Lines in the file that describes leap seconds have the following form:
 269
 270             Leap  YEAR  MONTH  DAY  HH:MM:SS  CORR  R/S
 271
 272        For example:
 273
 274             Leap  1974  Dec    31   23:59:60  +     S
 275
 276        The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second
 277        happened.  The CORR field should be "+" if a second was added or "-" if
 278        a second was skipped.  The R/S field should be (an abbreviation of)
 279        "Stationary" if the leap second time given by the other fields should
 280        be interpreted as UTC or (an abbreviation of) "Rolling" if the leap
 281        second time given by the other fields should be interpreted as local
 282        wall clock time.
 283
 284 EXTENDED EXAMPLE
 285        Here is an extended example of zic input, intended to illustrate many
 286        of its features.
 287
 288          # Rule  NAME  FROM  TO    TYPE  IN   ON       AT    SAVE  LETTER/S
 289          Rule    Swiss 1941  1942  -     May  Mon>=1   1:00  1:00  S
 290          Rule    Swiss 1941  1942  -     Oct  Mon>=1   2:00  0     -
 291          Rule    EU    1977  1980  -     Apr  Sun>=1   1:00u 1:00  S
 292          Rule    EU    1977  only  -     Sep  lastSun  1:00u 0     -
 293          Rule    EU    1978  only  -     Oct   1       1:00u 0     -
 294          Rule    EU    1979  1995  -     Sep  lastSun  1:00u 0     -
 295          Rule    EU    1981  max   -     Mar  lastSun  1:00u 1:00  S
 296          Rule    EU    1996  max   -     Oct  lastSun  1:00u 0     -
 297
 298          # Zone  NAME           GMTOFF  RULES/SAVE  FORMAT  UNTIL
 299          Zone    Europe/Zurich  0:34:08 -           LMT     1853 Jul 16
 300                                 0:29:46 -           BMT     1894 Jun
 301                                 1:00    Swiss       CE%sT   1981
 302                                 1:00    EU          CE%sT
 303
 304          Link    Europe/Zurich  Switzerland
 305
 306        In this example, the zone is named Europe/Zurich but it has an alias as
 307        Switzerland.  This example says that Zurich was 34 minutes and 8
 308        seconds west of UT until 1853-07-16 at 00:00, when the legal offset was
 309        changed to 7o26'22.50''; although this works out to 0:29:45.50, the
 310        input format cannot represent fractional seconds so it is rounded here.
 311        After 1894-06-01 at 00:00 Swiss daylight saving rules (defined with
 312        lines beginning with "Rule Swiss") apply, and the UT offset became one
 313        hour.  From 1981 to the present, EU daylight saving rules have applied,
 314        and the UTC offset has remained at one hour.
 315
 316        In 1941 and 1942, daylight saving time applied from the first Monday in
 317        May at 01:00 to the first Monday in October at 02:00.  The pre-1981 EU
 318        daylight-saving rules have no effect here, but are included for
 319        completeness.  Since 1981, daylight saving has begun on the last Sunday
 320        in March at 01:00 UTC.  Until 1995 it ended the last Sunday in
 321        September at 01:00 UTC, but this changed to the last Sunday in October
 322        starting in 1996.
 323
 324        For purposes of display, "LMT" and "BMT" were initially used,
 325        respectively.  Since Swiss rules and later EU rules were applied, the
 326        display name for the time zone has been CET for standard time and CEST
 327        for daylight saving time.
 328
 329 NOTES
 330        For areas with more than two types of local time, you may need to use
 331        local standard time in the AT field of the earliest transition time's
 332        rule to ensure that the earliest transition time recorded in the
 333        compiled file is correct.
 334
 335        If, for a particular zone, a clock advance caused by the start of
 336        daylight saving coincides with and is equal to a clock retreat caused
 337        by a change in UT offset, zic produces a single transition to daylight
 338        saving at the new UT offset (without any change in wall clock time).
 339        To get separate transitions use multiple zone continuation lines
 340        specifying transition instants using universal time.
 341
 342        Time stamps well before the Big Bang are silently omitted from the
 343        output.  This works around bugs in software that mishandles large
 344        negative time stamps.  Call it sour grapes, but pre-Big-Bang time
 345        stamps are physically suspect anyway.  The pre-Big-Bang cutoff time is
 346        approximate and may change in future versions.
 347
 348 FILE
 349        /usr/local/etc/zoneinfo        standard directory used for created
 350        files
 351
 352 SEE ALSO
 353        newctime(3), tzfile(5), zdump(8)
 354
 355                                                                         ZIC(8)