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