1.\" $NetBSD: zic.8,v 1.36 2021/03/01 04:42:14 christos Exp $ 2.Dd Fabruary 28, 2021 3.Dt ZIC 8 4.Os 5.Sh NAME 6.Nm zic 7.Nd timezone compiler 8.Sh SYNOPSIS 9.Nm 10.Op Fl \-version 11.Op Fl \-help 12.Op Fl b 13.Op Fl d Ar directory 14.Op Fl L Ar leapsecondfilename 15.Op Fl l Ar localtime 16.Op Fl p Ar posixrules 17.Op Fl s 18.Op Fl t Ar file 19.Op Fl v 20.Op Fl y Ar command 21.Op Ar Filename ... 22.Sh DESCRIPTION 23The 24.Nm 25program reads text from the file(s) named on the command line 26and creates the time conversion information files specified in this input. 27If a 28.Ar filename 29is 30.Ar \&- , 31standard input is read. 32.Pp 33.Sh OPTIONS 34.Bl -tag -width XXXXXXXXXX -compact 35.It Fl \-version 36Output version information and exit. 37.It Fl \-help 38Output short usage message and exit. 39.It Fl b Ar bloat 40Output backward-compatibility data as specified by 41.Ar bloat . 42If 43.Ar bloat 44is 45.Dv fat , 46generate additional data entries that work around potential bugs or 47incompatibilities in older software, such as software that mishandles 48the 64-bit generated data. 49If 50.Ar bloat 51is 52.Dv slim , 53keep the output files small; this can help check for the bugs 54and incompatibilities. 55The default is 56.Dv slim , 57as software that mishandles 64-bit data typically 58Also see the 59.Fl r 60option for another way to alter output size. 61.It Fl d Ar directory 62Create time conversion information files in the named directory rather than 63in the standard directory named below. 64.It Fl l Ar timezone 65Use the 66.Ar timezone 67as local time. 68.Nm 69will act as if the input contained a link line of the form 70.Dl Link timezone localtime 71If 72.Ar timezone 73is 74.Dv \&- , 75any already-existing link is removed. 76.It Fl L Ar leapsecondfilename 77Read leap second information from the file with the given name. 78If this option is not used, 79no leap second information appears in output files. 80.It Fl p Ar timezone 81Use 82.Ar timezone's 83rules when handling POSIX-format 84TZ strings like 85.Qq EET\&-2EEST 86that lack transition rules. 87.Nm 88will act as if the input contained a link line of the form 89.Dl Link timezone posixrules 90.Pp 91This feature is obsolete and poorly supported. 92Among other things it should not be used for timestamps after the year 2037, 93and it should not be combined with 94.Fl b Ar slim 95if 96.Va timezone's 97transitions are at standard time or Universal Time (UT) instead of local time. 98If 99.Ar timezone 100is 101.Dv \&- , 102any already-existing link is removed. 103.It Fl r Op Ar @lo / Op Ar @hi 104Reduce the size of output files by limiting their applicability 105to timestamps in the range from 106.Ar lo 107(inclusive) to 108.Ar hi 109(exclusive), where 110.Ar lo 111and 112.Ar hi 113are possibly-signed decimal counts of seconds since the Epoch 114(1970-01-01 00:00:00 UTC). 115Omitted counts default to extreme values. 116For example, 117.Bd literal 118zic -r @0 119.Ed 120omits data intended for negative timestamps (i.e., before the Epoch), and 121.Bd literal 122zic -r @0/@2147483648 123.Ed 124outputs data intended only for nonnegative timestamps that fit into 12531-bit signed integers. 126Or using 127.Xr date 1 , 128.Bd literal 129zic -r @$(date +%s) 130.Ed 131omits data intended for past timestamps. 132Also see the 133.Fl b Ar slim 134option for another way to shrink output size. 135.It Fl t Ar file 136When creating local time information, put the configuration link in 137the named file rather than in the standard location. 138.It Fl v 139Be more verbose, and complain about the following situations: 140.Bl -dash 141.It 142The input specifies a link to a link. 143.It 144A year that appears in a data file is outside the range 145of representable years. 146.It 147A time of 24:00 or more appears in the input. 148Pre-1998 versions of 149.Nm 150prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00. 151.It 152A rule goes past the start or end of the month. 153Pre-2004 versions of 154.Nm 155prohibit this. 156.It 157A time zone abbreviation uses a 158.Dv %z 159format. 160Pre-2015 versions of 161.Nm 162do not support this. 163.It 164A timestamp contains fractional seconds. 165Pre-2018 versions of 166.Nm 167do not support this. 168.It 169The input contains abbreviations that are mishandled by pre-2018 versions of 170.Nm 171due to a longstanding coding bug. 172These abbreviations include 173.Qq L 174for 175.Qq Link , 176.Qq mi 177for 178.Qq min , 179.Qq Sa 180for 181.Qq Sat , 182and 183.Qq Su 184for 185.Qq Sun . 186.It 187The output file does not contain all the information about the 188long-term future of a timezone, because the future cannot be summarized as 189an extended POSIX TZ string. 190For example, as of 2019 this problem 191occurs for Iran's daylight-saving rules for the predicted future, as 192these rules are based on the Iranian calendar, which cannot be 193represented. 194.It 195The output contains data that may not be handled properly by client 196code designed for older 197.Xr zic 8 198output formats. 199These compatibility issues affect only timestamps 200before 1970 or after the start of 2038. 201.It 202The output file contains more than 1200 transitions, 203which may be mishandled by some clients. 204The current reference client supports at most 2000 transitions; 205pre-2014 versions of the reference client support at most 1200 206transitions. 207.It 208A time zone abbreviation has fewer than 3 or more than 6 characters. 209POSIX requires at least 3, and requires implementations to support 210at least 6. 211.It 212An output file name contains a byte that is not an ASCII letter, 213.Qq - , 214.Qq / , 215or 216.Qq _ ; 217or it 218or it contains a file name component that contains more than 14 bytes 219or that starts with 220.Qq - . 221.El 222.El 223.Pp 224Input files should be text files, that is, they should be a series of 225zero or more lines, each ending in a newline byte and containing at 226most 511 bytes, and without any 227.Dv NUL 228bytes. 229The input text's encoding 230is typically UTF-8 or ASCII; it should have a unibyte representation 231for the POSIX Portable Character Set (PPCS) 232.Rs 233.%U http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html 234.Re 235and the encoding's non-unibyte characters should consist entirely of 236non-PPCS bytes. 237Non-PPCS characters typically occur only in comments: 238although output file names and time zone abbreviations can contain 239nearly any character, other software will work better if these are 240limited to the restricted syntax described under the 241.Op v 242option. 243.Pp 244Input lines are made up of fields. 245Fields are separated from one another by one or more white space characters. 246The white space characters are space, form feed, carriage return, newline, 247tab, and vertical tab. 248Leading and trailing white space on input lines is ignored. 249An unquoted sharp character (#) in the input introduces a comment which extends 250to the end of the line the sharp character appears on. 251White space characters and sharp characters may be enclosed in double 252quotes 253.Pq \&" 254.\" XXX " 255if they're to be used as part of a field. 256Any line that is blank (after comment stripping) is ignored. 257Nonblank lines are expected to be of one of three types: 258rule lines, zone lines, and link lines. 259.Pp 260Names must be in English and are case insensitive. 261They appear in several contexts, and include month and weekday names 262and keywords such as 263.Qq maximum , 264.Qq only , 265.Qq Rolling , 266and 267.Qq Zone . 268A name can be abbreviated by omitting all but an initial prefix; any 269abbreviation must be unambiguous in context. 270.Pp 271A rule line has the form 272.Pp 273.Dl Rule NAME FROM TO \&- IN ON AT SAVE LETTER/S 274.Pp 275For example: 276.Pp 277.Dl Rule US 1967 1973 \&- Apr lastSun 2:00w 1:00d D 278.Pp 279The fields that make up a rule line are: 280.Bl -tag -width "LETTER/S" 281.It NAME 282Gives the name of the rule set that contains this line. 283The name must start with a character that is neither 284an ASCII digit nor 285.Ar \&- 286nor 287.Ar + . 288To allow for future extensions, 289an unquoted name should not contain characters from the set 290.Ar !$%&'()*,/:;<=>?@[\e]^`{|}~ . 291.It FROM 292Gives the first year in which the rule applies. 293Any signed integer year can be supplied; the proleptic Gregorian calendar 294is assumed, with year 0 preceding year 1. 295The word 296.Em minimum 297(or an abbreviation) means the indefinite past. 298The word 299.Em maximum 300(or an abbreviation) means the indefinite future. 301Rules can describe times that are not representable as time values, 302with the unrepresentable times ignored; this allows rules to be portable 303among hosts with differing time value types. 304.It TO 305Gives the final year in which the rule applies. 306In addition to 307.Em minimum 308and 309.Em maximum 310(as above), 311the word 312.Em only 313(or an abbreviation) 314may be used to repeat the value of the 315.Em FROM 316field. 317.It \&- 318should be 319.Qq \&- 320for compatibility with older versions of 321.Nm . 322It was previously known as the 323.Em TYPE 324field, which could contain values to allow a 325separate script to further restrict in which 326.Em types 327of years the rule would apply. 328.It IN 329Names the month in which the rule takes effect. 330Month names may be abbreviated. 331.It ON 332Gives the day on which the rule takes effect. 333Recognized forms include: 334.Pp 335.Bl -tag -width lastSun -compact -offset indent 336.It 5 337the fifth of the month 338.It lastSun 339the last Sunday in the month 340.It lastMon 341the last Monday in the month 342.It Sun\*[Ge]8 343first Sunday on or after the eighth 344.It Sun\*[Le]25 345last Sunday on or before the 25th 346.El 347.Pp 348Names of days of the week may be abbreviated or spelled out in full. 349A weekday name (e.g., 350.Qq Sunday ) 351or a weekday name preceded by 352.Qq last 353(e.g., 354.Qq lastSunday ) 355may be abbreviated or spelled out in full. 356There must be no white space characters within the 357.Em ON 358field. 359The 360.Qq <= 361and 362.Qq >= 363constructs can result in a day in the neighboring month; 364for example, the IN-ON combination 365.Qq "Oct Sun>=31" 366tands for the first Sunday on or after October 31, 367even if that Sunday occurs in November. 368.It AT 369Gives the time of day at which the rule takes effect, 370relative to 00:00, the start of a calendar day. 371Recognized forms include: 372.Pp 373.Bl -tag -width "00X19X32X13" -compact -offset indent 374.It 2 375time in hours 376.It 2:00 377time in hours and minutes 378.It 01:28:14 379time in hours, minutes, and seconds 380.It 00:19:32.13 381time with fractional seconds 382.It 12:00 383midday, 12 hours after 00:00 384.It 15:00 3853 PM, 15 hours after 00:00 386.It 24:00 387end of day, 24 hours after 00:00 388.It 260:00 389260 hours after 00:00 390.It \-2:30 3912.5 hours before 00:00 392.It \- 393equivalent to 0 394.El 395.Pp 396Although 397.I zic 398rounds times to the nearest integer second 399(breaking ties to the even integer), the fractions may be useful 400to other applications requiring greater precision. 401The source format does not specify any maximum precision. 402Any of these forms may be followed by the letter 403.Em w 404if the given time is local or 405.Qq wall clock 406time, 407.Em s 408if the given time is standard time without any adjustment for daylight saving, 409or 410.Em u 411(or 412.Em g 413or 414.Em z ) 415if the given time is universal time; 416in the absence of an indicator, 417local (wall clock) time is assumed. 418These forms ignore leap seconds; for example, 419if a leap second occurs at 00:59:60 local time, 420.q "1:00" 421stands for 3601 seconds after local midnight instead of the usual 3600 seconds. 422The intent is that a rule line describes the instants when a 423clock/calendar set to the type of time specified in the 424.Em AT 425field would show the specified date and time of day. 426.It SAVE 427Gives the amount of time to be added to local standard time when the rule is in 428effect, and whether the resulting time is standard or daylight saving. 429This field has the same format as the 430.Em AT 431field 432.Em s 433for standard time and 434.Em d 435for daylight saving time. 436The suffix letter is typically omitted, and defaults to 437.Em s 438if the offset is zero and to 439.Em d 440otherwise. 441Negative offsets are allowed; in Ireland, for example, daylight saving 442time is observed in winter and has a negative offset relative to 443Irish Standard Time. 444The offset is merely added to standard time; for example, 445.Nm 446does not distinguish a 10:30 standard time plus an 0:30 447.Em SAVE 448from a 10:00 standard time plus a 1:00 449.Em SAVE . 450.It LETTER/S 451Gives the 452.Qq variable part 453(for example, the 454.Qq S 455or 456.Qq D 457in 458.Qq EST 459or 460.Qq EDT ) 461of time zone abbreviations to be used when this rule is in effect. 462If this field is 463.Em \&- , 464the variable part is null. 465.El 466.Pp 467A zone line has the form 468.Pp 469.Dl Zone NAME STDOFF RULES/SAVE FORMAT [UNTIL] 470.Pp 471For example: 472.Pp 473.Dl Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 1:00 474.Pp 475The fields that make up a zone line are: 476.Bl -tag -width "RULES/SAVE" 477.It NAME 478The name of the timezone. 479This is the name used in creating the time conversion information file for the 480timezone. 481It should not contain a file name component 482.Qq . 483or 484.Qq .. ; 485a file name component is a maximal substring that does not contain 486.Qq / . 487.It STDOFF 488The amount of time to add to UT to get standard time, 489without any adjustment for daylight saving. 490This field has the same format as the 491.Em AT 492and 493.Em SAVE 494fields of rule lines; 495begin the field with a minus sign if time must be subtracted from UT. 496.It RULES 497The name of the rules that apply in the timezone or, 498alternatively, a field in the same format as a rule-line SAVE column, 499giving of the amount of time to be added to local standard time 500effect, and whether the resulting time is standard or daylight saving. 501If this field is 502.Em \&- 503then standard time always applies. 504When an amount of time is given, only the sum of standard time and 505this amount matters. 506.It FORMAT 507The format for time zone abbreviations. 508The pair of characters 509.Em %s 510is used to show where the 511.Qq variable part 512of the time zone abbreviation goes. 513Alternatively, a format can use the pair of characters 514.Em %z 515+to stand for the UT offset in the form 516.Em \(+- hh , 517.Em \(+- hhmm , 518or 519.Em \(+- hhmmss , 520using the shortest form that does not lose information, where 521.Em hh , 522.Em mm , 523and 524.Em ss 525are the hours, minutes, and seconds east (+) or west (\(mi) of UT. 526Alternatively, 527a slash 528.Pq \&/ 529separates standard and daylight abbreviations. 530To conform to POSIX, a time zone abbreviation should contain only 531alphanumeric ASCII characters, 532.Qq + 533and 534.Qq \&- . 535.It UNTIL 536The time at which the UT offset or the rule(s) change for a location. 537It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]]. 538If this is specified, 539the time zone information is generated from the given UT offset 540and rule change until the time specified, which is interpreted using 541the rules in effect just before the transition. 542The month, day, and time of day have the same format as the IN, ON, and AT 543fields of a rule; trailing fields can be omitted, and default to the 544earliest possible value for the missing fields. 545.Pp 546The next line must be a 547.Qq continuation 548line; this has the same form as a zone line except that the 549string 550.Qq Zone 551and the name are omitted, as the continuation line will 552place information starting at the time specified as the 553.Em until 554information in the previous line in the file used by the previous line. 555Continuation lines may contain 556.Em until 557information, just as zone lines do, indicating that the next line is a further 558continuation. 559.El 560.Pp 561If a zone changes at the same instant that a rule would otherwise take 562effect in the earlier zone or continuation line, the rule is ignored. 563A zone or continuation line 564.I L 565with a named rule set starts with standard time by default: 566that is, any of 567.IR L 's 568timestamps preceding 569.IR L 's 570earliest rule use the rule in effect after 571.IR L 's 572first transition into standard time. 573In a single zone it is an error if two rules take effect at the same 574instant, or if two zone changes take effect at the same instant. 575.Pp 576If a continuation line subtracts 577.Dv N 578seconds from the UT offset after a transition that would be 579interpreted to be later if using the continuation line's UT offset and 580rules, the 581.Em until 582time of the previous zone or continuation line is interpreted 583according to the continuation line's UT offset and rules, and any rule 584that would otherwise take effect in the next 585.Dv N 586seconds is instead assumed to take effect simultaneously. 587For example: 588.Pp 589.Bl -column -compact -offset indent "# Rule" "Swiss" "FROM" "1995" "\&*" "Oct" "lastSun" "1:00u" "SAVE" "LETTER/S" 590.It # Rule NAME FROM TO \&- IN ON AT SAVE LETTER/S 591.It Rule US 1967 2006 \&- Oct lastSun 2:00 0 S 592.It Rule US 1967 1973 \&- Apr lastSun 2:00 1:00 D 593.It # Zone NAME STDOFF RULES FORMAT [UNTIL] 594.It Zone America/Menominee \&-5:00 \&- EST 1973 Apr 29 2:00 595.It \&-6:00 US C%sT 596.El 597.Pp 598Here, an incorrect reading would be there were two clock changes on 1973-04-29, 599the first from 02:00 EST (\&-05) to 01:00 CST (\&-06), 600and the second an hour later from 02:00 CST (\&-06) to 03:00 CDT (\&-05). 601However, 602.Nm 603interprets this more sensibly as a single transition from 02:00 CST (\&-05) to 60402:00 CDT (\&-05). 605.Pp 606A link line has the form 607.Pp 608.Dl Link TARGET LINK-NAME 609.Pp 610For example: 611.Pp 612.Dl Link Europe/Istanbul Asia/Istanbul 613.Pp 614The 615.Em TARGET 616field should appear as the 617.Em NAME 618field in some zone line. 619The 620.Em LINK-NAME 621field is used as an alternative name for that zone; 622it has the same syntax as a zone line's 623.Em NAME 624field. 625.Pp 626Except for continuation lines, 627lines may appear in any order in the input. 628However, the behavior is unspecified if multiple zone or link lines 629define the same name, or if the source of one link line is the target 630of another. 631.Pp 632The file that describes leap seconds can have leap lines and an 633expiration line. 634Leap lines have the following form: 635.Pp 636.Dl Leap YEAR MONTH DAY HH:MM:SS CORR R/S 637.Pp 638For example: 639.Pp 640.Dl Leap 2016 Dec 31 23:59:60 + S 641.Pp 642The 643.Em YEAR , 644.Em MONTH , 645.Em DAY , 646and 647.Em HH:MM:SS 648fields tell when the leap second happened. 649The 650.Em CORR 651field 652should be 653.Qq \&+ 654if a second was added 655or 656.Qq \&- 657if a second was skipped. 658The 659.Em R/S 660field 661should be (an abbreviation of) 662.Qq Stationary 663if the leap second time given by the other fields should be interpreted as UTC 664or 665(an abbreviation of) 666.Qq Rolling 667if the leap second time given by the other fields should be interpreted as 668local (wall clock) time. 669.Pp 670The expiration line, if present, has the form: 671.Pp 672.Dl Expires YEAR MONTH DAY HH:MM:SS 673.Pp 674For example: 675.Pp 676.Dl Expires 2020 Dec 28 00:00:00 677.Pp 678The 679.Em YEAR , 680.Em MONTH , 681.Em DAY , 682and 683.Em HH:MM:SS 684fields give the expiration timestamp in UTC for the leap second table; 685.Nm 686outputs this expiration timestamp by truncating the end of the output 687file to the timestamp. 688If there is no expiration line, 689.Nm 690also accepts a comment 691.Qq "#expires \fIE\fP ...\&" 692where 693.Em E 694is the expiration timestamp as a decimal integer count of seconds 695since the Epoch, not counting leap seconds. 696However, the 697.Qq "#expires" 698comment is an obsolescent feature, 699and the leap second file should use an expiration line 700instead of relying on a comment. 701.Sh EXTENDED EXAMPLE 702Here is an extended example of 703.Ic zic 704input, intended to illustrate many of its features. 705In this example, the EU rules are for the European Union 706and for its predecessor organization, the European Communities. 707.Pp 708.Bl -column -compact -offset indent "# Rule" "Swiss" "FROM" "1995" "\&*" "Oct" "lastSun" "1:00u" "SAVE" "LETTER/S" 709.It # Rule NAME FROM TO \&- IN ON AT SAVE LETTER/S 710.It Rule Swiss 1941 1942 \&- May Mon>=1 1:00 1:00 S 711.It Rule Swiss 1941 1942 \&- Oct Mon>=1 2:00 0 - 712.Pp 713.It Rule EU 1977 1980 \&- Apr Sun>=1 1:00u 1:00 S 714.It Rule EU 1977 only \&- Sep lastSun 1:00u 0 - 715.It Rule EU 1978 only \&- Oct 1 1:00u 0 - 716.It Rule EU 1979 1995 \&- Sep lastSun 1:00u 0 - 717.It Rule EU 1981 max \&- Mar lastSun 1:00u 1:00 S 718.It Rule EU 1996 max \&- Oct lastSun 1:00u 0 - 719.El 720.Pp 721.Bl -column -compact -offset indent "# Zone" "Europe/Zurich" "0:29:45.50" "RULES/SAVE" "FORMAT" "UNTIL" 722.It # Zone NAME STDOFF RULES/SAVE FORMAT [UNTIL] 723.It Zone Europe/Zurich 0:34:08 \&- LMT 1853 Jul 16 724.It 0:29:45.50 \&- BMT 1894 Jun 725.It 1:00 Swiss CE%sT 1981 726.It 1:00 EU CE%sT 727.Pp 728.El 729.Bl -column -compact -offset indent "# Zone" "Europe/Zurich" "0:34:08" "RULES/SAVE" "FORMAT" "UNTIL" 730.It Link Europe/Zurich Europe/Vaduz 731.El 732.Pp 733In this example, the timezone is named Europe/Zurich but it has an alias 734as Europe/Vaduz. 735This example says that Zurich was 34 minutes and 8 736seconds east of UT until 1853-07-16 at 00:00, when the legal offset 737was changed to 7\(de\|26\(fm\|22.50\(sd; which this works out to 7380:29:45.50; 739.Nm 740treats this by rounding it to 0:29:46. 741After 1894-06-01 at 00:00 the UT offset became one hour 742and Swiss daylight saving rules (defined with lines beginning with 743.Qq "Rule Swiss" 744apply. 745From 1981 to the present, EU daylight saving rules have 746From 1981 to the present, EU daylight saving rules have 747.Pp 748In 1941 and 1942, daylight saving time applied from the first Monday 749in May at 01:00 to the first Monday in October at 02:00. 750The pre-1981 EU daylight-saving rules have no effect 751here, but are included for completeness. 752Since 1981, daylight 753saving has begun on the last Sunday in March at 01:00 UTC. 754Until 1995 it ended the last Sunday in September at 01:00 UTC, 755but this changed to the last Sunday in October starting in 1996. 756.Pp 757For purposes of display, 758.Qq LMT 759and 760.Qq BMT 761were initially used, respectively. 762Since 763Swiss rules and later EU rules were applied, the time zone abbreviation 764has been CET for standard time and CEST for daylight saving 765time. 766.Sh FILES 767Input files use the format described in this section; output files use 768.Xr tzfile 5 769format. 770.Bl -tag -width /usr/share/zoneinfo -compact 771.It Pa /etc/localtime 772Default local timezone file 773.It Pa /usr/share/zoneinfo 774Default timezone information directory 775.El 776.Sh NOTES 777For areas with more than two types of local time, 778you may need to use local standard time in the 779.Em AT 780field of the earliest transition time's rule to ensure that 781the earliest transition time recorded in the compiled file is correct. 782.Pp 783If, 784for a particular timezone, 785a clock advance caused by the start of daylight saving 786coincides with and is equal to 787a clock retreat caused by a change in UT offset, 788.Ic zic 789produces a single transition to daylight saving at the new UT offset 790without any change in local (wall clock) time. 791To get separate transitions 792use multiple zone continuation lines 793specifying transition instants using universal time. 794.Sh SEE ALSO 795.Xr tzfile 5 , 796.Xr zdump 8 797.\" @(#)zic.8 8.6 798.\" This file is in the public domain, so clarified as of 799.\" 2009-05-17 by Arthur David Olson. 800