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