1.\" $OpenBSD: zic.8,v 1.3 2020/04/23 21:28:10 jmc Exp $ 2.Dd $Mdocdate: April 23 2020 $ 3.Dt ZIC 8 4.Os 5.Sh NAME 6.Nm zic 7.Nd time zone compiler 8.Sh SYNOPSIS 9.Nm zic 10.Bk -words 11.Op Fl v 12.Op Fl d Ar directory 13.Op Fl L Ar leapsecondfilename 14.Op Fl l Ar timezone 15.Op Fl p Ar timezone 16.Op Fl y Ar command 17.Op Ar filename ... 18.Ek 19.Sh DESCRIPTION 20.Nm 21reads text from the file(s) named on the command line 22and creates the time conversion information files specified in this input. 23If a 24.Ar filename 25is 26.Dq Fl , 27the standard input is read. 28.Pp 29These options are available: 30.Bl -tag -width "-d directory" 31.It Fl d Ar directory 32Create time conversion information files in the named directory rather than 33in the standard directory named below. 34.It Fl L Ar leapsecondfilename 35Read leap second information from the file with the given name. 36If this option is not used, 37no leap second information appears in output files. 38.It Fl l Ar timezone 39Use the given time zone as local time. 40.Nm 41will act as if the input contained a link line of the form 42.Pp 43.Dl Link timezone localtime 44.It Fl p Ar timezone 45Use the given time zone's rules when handling POSIX-format 46time zone environment variables. 47.Nm 48will act as if the input contained a link line of the form 49.Pp 50.Dl Link timezone posixrules 51.It Fl v 52Complain if a year that appears in a data file is outside the range 53of years representable by 54.Xr time 3 55values. 56Also complain if a time of 24:00 57(which cannot be handled by pre-1998 versions of 58.Nm zic ) 59appears in the input. 60.It Fl y Ar command 61Use the given 62.Ar command 63rather than 64.Em yearistype 65when checking year types (see below). 66.El 67.Pp 68Input lines are made up of fields. 69Fields are separated from one another by any number of whitespace characters. 70Leading and trailing whitespace on input lines is ignored. 71An unquoted sharp character (#) in the input introduces a comment which extends 72to the end of the line the sharp character appears on. 73White space characters and sharp characters may be enclosed in double quotes 74(") if they're to be used as part of a field. 75Any line that is blank (after comment stripping) is ignored. 76Non-blank lines are expected to be of one of three types: 77rule lines, zone lines, and link lines. 78.Pp 79Names (such as month names) must be in English and are case insensitive. 80Abbreviations, if used, must be unambiguous in context. 81.Pp 82A rule line has the form: 83.Bd -literal -offset indent 84Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 85.Ed 86.Pp 87For example: 88.Bd -literal -offset indent 89Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 90.Ed 91.Pp 92The fields that make up a rule line are: 93.Bl -tag -width "LETTER/S" 94.It Cm NAME 95Gives the (arbitrary) name of the set of rules this rule is part of. 96.It Cm FROM 97Gives the first year in which the rule applies. 98Any integer year can be supplied; the Gregorian calendar is assumed. 99The word 100.Em minimum 101(or an abbreviation) means the minimum year representable as an integer. 102The word 103.Em maximum 104(or an abbreviation) means the maximum year representable as an integer. 105Rules can describe times that are not representable as time values, 106with the unrepresentable times ignored; this allows rules to be portable 107among hosts with differing time value types. 108.It Cm TO 109Gives the final year in which the rule applies. 110In addition to 111.Em minimum 112and 113.Em maximum 114(as above), 115the word 116.Em only 117(or an abbreviation) 118may be used to repeat the value of the 119.Em FROM 120field. 121.It Cm TYPE 122Gives the type of year in which the rule applies. 123If 124.Em TYPE 125is 126.Dq Fl 127then the rule applies in all years between 128.Em FROM 129and 130.Em TO 131inclusive. 132If 133.Em TYPE 134is something else, then 135.Nm 136executes the command 137.Pp 138.Dl yearistype Ar year type 139.Pp 140to check the type of a year: 141an exit status of zero is taken to mean that the year is of the given type; 142an exit status of one is taken to mean that the year is not of the given type. 143.It Cm IN 144Names the month in which the rule takes effect. 145Month names may be abbreviated. 146.It Cm ON 147Gives the day on which the rule takes effect. 148Recognized forms include: 149.Pp 150.Bl -tag -width "SunXX25" -compact -offset indent 151.It 5 152the fifth of the month 153.It lastSun 154the last Sunday in the month 155.It lastMon 156the last Monday in the month 157.It Sun>=8 158first Sunday on or after the eighth 159.It Sun<=25 160last Sunday on or before the 25th 161.El 162.Pp 163Names of days of the week may be abbreviated or spelled out in full. 164Note that there must be no spaces within the 165.Em ON 166field. 167.It Cm AT 168Gives the time of day at which the rule takes effect. 169Recognized forms include: 170.Pp 171.Bl -tag -width "1:28:14" -compact -offset indent 172.It 2 173time in hours 174.It 2:00 175time in hours and minutes 176.It 15:00 17724-hour format time (for times after noon) 178.It 1:28:14 179time in hours, minutes, and seconds 180.It \&- 181equivalent to 0 182.El 183.Pp 184where hour 0 is midnight at the start of the day, 185and hour 24 is midnight at the end of the day. 186Any of these forms may be followed by the letter 187.Em w 188if the given time is local 189.Dq wall clock 190time, 191.Em s 192if the given time is local 193.Dq standard 194time, or 195.Em u 196(or 197.Em g 198or 199.Em z ) 200if the given time is universal time; 201in the absence of an indicator, 202wall clock time is assumed. 203.It Cm SAVE 204Gives the amount of time to be added to local standard time when the rule is in 205effect. 206This field has the same format as the 207.Em AT 208field 209(although, of course, the 210.Em w 211and 212.Em s 213suffixes are not used). 214.It Cm LETTER/S 215Gives the 216.Dq variable part 217(for example, the 218.Dq S 219or 220.Dq D 221in 222.Dq EST 223or 224.Dq EDT ) 225of time zone abbreviations to be used when this rule is in effect. 226If this field is 227.Dq Fl 228the variable part is null. 229.El 230.Pp 231A zone line has the form: 232.Bd -literal -offset 3n 233Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]] 234.Ed 235.Pp 236For example: 237.Bd -literal -offset 3n 238Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 239.Ed 240.Pp 241The fields that make up a zone line are: 242.Bl -tag -width GMTOFF 243.It Cm NAME 244The name of the time zone. 245This is the name used in creating the time conversion information file for the 246zone. 247.It Cm GMTOFF 248The amount of time to add to UTC to get standard time in this zone. 249This field has the same format as the 250.Em AT 251and 252.Em SAVE 253fields of rule lines; 254begin the field with a minus sign if time must be subtracted from UTC. 255.It Cm RULES/SAVE 256The name of the rule(s) that apply in the time zone or, 257alternately, an amount of time to add to local standard time. 258If this field is 259.Dq \- 260then standard time always applies in the time zone. 261.It Cm FORMAT 262The format for time zone abbreviations in this time zone. 263The pair of characters 264.Em %s 265is used to show where the 266.Dq variable part 267of the time zone abbreviation goes. 268Alternately, 269a slash 270.Pq \&/ 271separates standard and daylight abbreviations. 272.It Cm UNTILYEAR [MONTH [DAY [TIME]]] 273The time at which the UTC offset or the rule(s) change for a location. 274It is specified as a year, a month, a day, and a time of day. 275If this is specified, 276the time zone information is generated from the given UTC offset 277and rule change until the time specified. 278The month, day, and time of day have the same format as the IN, ON, and AT 279fields of a rule; trailing fields can be omitted, and default to the 280earliest possible value for the missing fields. 281.Pp 282The next line must be a 283.Dq continuation 284line; this has the same form as a zone line except that the 285string 286.Dq Zone 287and the name are omitted, as the continuation line will 288place information starting at the time specified as the 289.Dq until 290information in the previous line in the file used by the previous line. 291Continuation lines may contain 292.Dq until 293information, just as zone lines do, indicating that the next line is a further 294continuation. 295.El 296.Pp 297A link line has the form: 298.Bd -literal -offset indent 299Link LINK-FROM LINK-TO 300.Ed 301.Pp 302For example: 303.Bd -literal -offset indent 304Link Europe/Istanbul Asia/Istanbul 305.Ed 306.Pp 307The 308.Em LINK-FROM 309field should appear as the 310.Em NAME 311field in some zone line; 312the 313.Em LINK-TO 314field is used as an alternate name for that zone. 315.Pp 316Except for continuation lines, 317lines may appear in any order in the input. 318.Pp 319Lines in the file that describes leap seconds have the following form: 320.Bd -literal -offset indent 321Leap YEAR MONTH DAY HH:MM:SS CORR R/S 322.Ed 323.Pp 324For example: 325.Bd -literal -offset indent 326Leap 1974 Dec 31 23:59:60 + S 327.Ed 328.Pp 329The 330.Em YEAR , 331.Em MONTH , 332.Em DAY , 333and 334.Em HH:MM:SS 335fields tell when the leap second happened. 336The 337.Em CORR 338field 339should be 340.Dq + 341if a second was added 342or 343.Dq - 344if a second was skipped. 345.\" There's no need to document the following, since it's impossible for more 346.\" than one leap second to be inserted or deleted at a time. 347.\" The C Standard is in error in suggesting the possibility. 348.\" See Terry J Quinn, The BIPM and the accurate measure of time, 349.\" Proc IEEE 79, 7 (July 1991), 894-905. 350.\" or 351.\" .q ++ 352.\" if two seconds were added 353.\" or 354.\" .q -- 355.\" if two seconds were skipped. 356The 357.Em R/S 358field should be (an abbreviation of) 359.Dq Stationary 360if the leap second time given by the other fields should be interpreted as UTC 361or (an abbreviation of) 362.Dq Rolling 363if the leap second time given by the other fields should be interpreted as 364local wall clock time. 365.Sh EXTENDED EXAMPLE 366Here is an extended example of 367.Nm 368input, intended to illustrate many of its features. 369.Bd -literal 370# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 371Rule Swiss 1940 only - Nov 2 0:00 1:00 S 372Rule Swiss 1940 only - Dec 31 0:00 0 - 373Rule Swiss 1941 1942 - May Sun>=1 2:00 1:00 S 374Rule Swiss 1941 1942 - Oct Sun>=1 0:00 0 375 376Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S 377Rule EU 1977 only - Sep lastSun 1:00u 0 - 378Rule EU 1978 only - Oct 1 1:00u 0 - 379Rule EU 1979 1995 - Sep lastSun 1:00u 0 - 380Rule EU 1981 max - Mar lastSun 1:00u 1:00 S 381Rule EU 1996 max - Oct lastSun 1:00u 0 - 382 383# Zone NAME GMTOFF RULES FORMAT UNTIL 384Zone Europe/Zurich 0:34:08 - LMT 1848 Sep 12 385 0:29:44 - BMT 1894 Jun 386 1:00 Swiss CE%sT 1981 387 1:00 EU CE%sT 388 389Link Europe/Zurich Switzerland 390.Ed 391.Pp 392In this example, the zone is named Europe/Zurich 393but it has an alias as Switzerland. 394Zurich was 34 minutes and 8 seconds west of GMT until 1848-09-12 at 00:00, 395when the offset changed to 29 minutes and 44 seconds. 396After 1894-06-01 at 00:00 Swiss daylight saving rules 397(defined with lines beginning with "Rule Swiss") apply, 398and the GMT offset became one hour. 399From 1981 to the present, 400EU daylight saving rules have applied, 401and the UTC offset has remained at one hour. 402.Pp 403In 1940, daylight saving time applied from 404November 2 at 00:00 to December 31 at 00:00. 405In 1941 and 1942, daylight saving time applied 406from the first Sunday in May at 02:00 407to the first Sunday in October at 00:00. 408The pre-1981 EU daylight-saving rules have no effect here, 409but are included for completeness. 410Since 1981, 411daylight saving has begun on the last Sunday in March at 01:00 UTC. 412Until 1995 it ended the last Sunday in September at 01:00 UTC, 413but this changed to the last Sunday in October starting in 1996. 414.Pp 415For purposes of display, 416"LMT" and "BMT" were initially used, respectively. 417Since Swiss rules and later EU rules were applied, 418the display name for the timezone has been CET for standard time 419and CEST for daylight saving time. 420.Sh FILES 421.Bl -tag -width "/usr/share/zoneinfo" -compact 422.It Pa /etc/localtime 423link to local time zone 424.It Pa /usr/share/zoneinfo 425standard directory used for created files 426.El 427.Sh SEE ALSO 428.Xr ctime 3 , 429.Xr tzfile 5 , 430.Xr zdump 8 431.Sh CAVEATS 432For areas with more than two types of local time, 433you may need to use local standard time in the 434.Em AT 435field of the earliest transition time's rule to ensure that 436the earliest transition time recorded in the compiled file is correct. 437.Pp 438If, 439for a particular zone, 440a clock advance caused by the start of daylight saving 441coincides with and is equal to 442a clock retreat caused by a change in UTC offset, 443.Nm 444produces a single transition to daylight saving at the new UTC offset 445(without any change in wall clock time). 446To get separate transitions 447use multiple zone continuation lines 448specifying transition instants using universal time. 449.\" This file is in the public domain, so clarified as of 450.\" 2009-05-17 by Arthur David Olson. 451