1.\" $NetBSD: zic.8,v 1.18 2010/05/30 07:57:08 wiz 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 85A rule line has the form 86.Dl Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 87For example: 88.Dl Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D 89The fields that make up a rule line are: 90.Bl -tag -width "LETTER/S" -compact 91.It NAME 92Gives the (arbitrary) name of the set of rules this rule is part of. 93.It FROM 94Gives the first year in which the rule applies. 95Any integer year can be supplied; the Gregorian calendar is assumed. 96The word 97.Em minimum 98(or an abbreviation) means the minimum year representable as an integer. 99The word 100.Em maximum 101(or an abbreviation) means the maximum year representable as an integer. 102Rules can describe times that are not representable as time values, 103with the unrepresentable times ignored; this allows rules to be portable 104among hosts with differing time value types. 105.It TO 106Gives the final year in which the rule applies. 107In addition to 108.Em minimum 109and 110.Em maximum 111(as above), 112the word 113.Em only 114(or an abbreviation) 115may be used to repeat the value of the 116.Em FROM 117field. 118.It TYPE 119Gives the type of year in which the rule applies. 120If 121.Em TYPE 122is 123.Em \&- 124then the rule applies in all years between 125.Em FROM 126and 127.Em TO 128inclusive. 129If 130.Em TYPE 131is something else, then 132.Nm 133executes the command 134.Pp 135.Ic yearistype Ar year type 136.Pp 137to check the type of a year: 138an exit status of zero is taken to mean that the year is of the given type; 139an exit status of one is taken to mean that the year is not of the given type. 140.It IN 141Names the month in which the rule takes effect. 142Month names may be abbreviated. 143.It ON 144Gives the day on which the rule takes effect. 145Recognized forms include: 146.Bl -tag -width lastSun -compact -offset indent 147.It 5 148the fifth of the month 149.It lastSun 150the last Sunday in the month 151.It lastMon 152the last Monday in the month 153.It Sun\*[Ge]8 154first Sunday on or after the eighth 155.It Sun\*[Le]25 156last Sunday on or before the 25th 157.El 158Names of days of the week may be abbreviated or spelled out in full. 159Note that there must be no spaces within the 160.Em ON 161field. 162.It AT 163Gives the time of day at which the rule takes effect. 164Recognized forms include: 165.Bl -tag -width "1X28X14" -compact -offset indent 166.It 2 167time in hours 168.It 2:00 169time in hours and minutes 170.It 15:00 17124-hour format time (for times after noon) 172.It 1:28:14 173time in hours, minutes, and seconds 174.It \- 175equivalent to 0 176.El 177where hour 0 is midnight at the start of the day, 178and hour 24 is midnight at the end of the day. 179Any of these forms may be followed by the letter 180.Em w 181if the given time is local 182.Dq wall clock 183time, 184.Em s 185if the given time is local 186.Dq standard 187time, or 188.Em u 189(or 190.Em g 191or 192.Em z ) 193if the given time is universal time; 194in the absence of an indicator, 195wall clock time is assumed. 196.It SAVE 197Gives the amount of time to be added to local standard time when the rule is in 198effect. 199This field has the same format as the 200.Em AT 201field 202(although, of course, the 203.Em w 204and 205.Em s 206suffixes are not used). 207.It LETTER/S 208Gives the 209.Dq variable part 210(for example, the 211.Dq S 212or 213.Dq D 214in 215.Dq EST 216or 217.Dq EDT ) 218of time zone abbreviations to be used when this rule is in effect. 219If this field is 220.Em \&- , 221the variable part is null. 222.El 223.Pp 224A zone line has the form 225.sp 226.Dl Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]] 227For example: 228.Dl Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 229The fields that make up a zone line are: 230.Bl -tag -width "RULES/SAVE" -compact 231.It NAME 232The name of the time zone. 233This is the name used in creating the time conversion information file for the 234zone. 235.It GMTOFF 236The amount of time to add to UTC to get standard time in this zone. 237This field has the same format as the 238.Em AT 239and 240.Em SAVE 241fields of rule lines; 242begin the field with a minus sign if time must be subtracted from UTC. 243.It RULES/SAVE 244The name of the rule(s) that apply in the time zone or, 245alternatively, an amount of time to add to local standard time. 246If this field is 247.Em \&- 248then standard time always applies in the time zone. 249.It FORMAT 250The format for time zone abbreviations in this time zone. 251The pair of characters 252.Em %s 253is used to show where the 254.Dq variable part 255of the time zone abbreviation goes. 256Alternatively, 257a slash 258.Pq \&/ 259separates standard and daylight abbreviations. 260.It UNTILYEAR [MONTH [DAY [TIME]]] 261The time at which the UTC offset or the rule(s) change for a location. 262It is specified as a year, a month, a day, and a time of day. 263If this is specified, 264the time zone information is generated from the given UTC offset 265and rule change until the time specified. 266The month, day, and time of day have the same format as the IN, ON, and AT 267fields of a rule; trailing fields can be omitted, and default to the 268earliest possible value for the missing fields. 269.El 270The next line must be a 271.Dq continuation 272line; this has the same form as a zone line except that the 273string 274.Dq Zone 275and the name are omitted, as the continuation line will 276place information starting at the time specified as the 277.Em until 278information in the previous line in the file used by the previous line. 279Continuation lines may contain 280.Em until 281information, just as zone lines do, indicating that the next line is a further 282continuation. 283.Pp 284A link line has the form 285.Dl Link LINK-FROM LINK-TO 286For example: 287.Dl Link Europe/Istanbul Asia/Istanbul 288The 289.Em LINK-FROM 290field should appear as the 291.Em NAME 292field in some zone line; 293the 294.Em LINK-TO 295field is used as an alternative name for that zone. 296.Pp 297Except for continuation lines, 298lines may appear in any order in the input. 299.Pp 300Lines in the file that describes leap seconds have the following form: 301.Dl Leap YEAR MONTH DAY HH:MM:SS CORR R/S 302For example: 303.Dl Leap 1974 Dec 31 23:59:60 + S 304The 305.Em YEAR , 306.Em MONTH , 307.Em DAY , 308and 309.Em HH:MM:SS 310fields tell when the leap second happened. 311The 312.Em CORR 313field 314should be 315.Dq \&+ 316if a second was added 317or 318.Dq \&- 319if a second was skipped. 320.\" There's no need to document the following, since it's impossible for more 321.\" than one leap second to be inserted or deleted at a time. 322.\" The C Standard is in error in suggesting the possibility. 323.\" See Terry J Quinn, The BIPM and the accurate measure of time, 324.\" Proc IEEE 79, 7 (July 1991), 894-905. 325.\" or 326.\" .Dq ++ 327.\" if two seconds were added 328.\" or 329.\" .Dq -- 330.\" if two seconds were skipped. 331The 332.Em R/S 333field 334should be (an abbreviation of) 335.Dq Stationary 336if the leap second time given by the other fields should be interpreted as UTC 337or 338(an abbreviation of) 339.Dq Rolling 340if the leap second time given by the other fields should be interpreted as 341local wall clock time. 342.El 343.Sh EXTENDED EXAMPLE 344Here is an extended example of 345.Ic zic 346input, intended to illustrate many of its features. 347.Bl -column -compact "# Rule" "Swiss" "FROM" "1995" "TYPE" "Oct" "lastSun" "1:00u" "SAVE" "LETTER/S" 348.It # Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 349.It Rule Swiss 1940 only - Nov 2 0:00 1:00 S 350.It Rule Swiss 1940 only - Dec 31 0:00 0 - 351.It Rule Swiss 1941 1942 - May Sun>=1 2:00 1:00 S 352.It Rule Swiss 1941 1942 - Oct Sun>=1 0:00 0 353.Pp 354.It Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S 355.It Rule EU 1977 only - Sep lastSun 1:00u 0 - 356.It Rule EU 1978 only - Oct 1 1:00u 0 - 357.It Rule EU 1979 1995 - Sep lastSun 1:00u 0 - 358.It Rule EU 1981 max - Mar lastSun 1:00u 1:00 S 359.It Rule EU 1996 max - Oct lastSun 1:00u 0 - 360.El 361.Pp 362.Bl -column -compact "# Zone" "Europe/Zurich" "0:29:44" "RULES" "FORMAT" "UNTIL" 363.It # Zone NAME GMTOFF RULES FORMAT UNTIL 364.It Zone Europe/Zurich 0:34:08 - LMT 1848 Sep 12 365.It 0:29:44 - BMT 1894 Jun 366.It 1:00 Swiss CE%sT 1981 367.It 1:00 EU CE%sT 368.It Link Europe/Zurich Switzerland 369.El 370.Pp 371In this example, the zone is named Europe/Zurich but it has an alias 372as Switzerland. 373Zurich was 34 minutes and 8 seconds west of GMT until 3741848-09-12 at 00:00, when the offset changed to 29 minutes and 44 375seconds. 376After 1894-06-01 at 00:00 Swiss daylight saving rules (defined 377with lines beginning with "Rule Swiss") apply, and the GMT offset 378became one hour. 379From 1981 to the present, EU daylight saving rules have 380applied, and the UTC offset has remained at one hour. 381.Pp 382In 1940, daylight saving time applied from November 2 at 00:00 to 383December 31 at 00:00. 384In 1941 and 1942, daylight saving time applied 385from the first Sunday in May at 02:00 to the first Sunday in October 386at 00:00. 387The pre-1981 EU daylight-saving rules have no effect 388here, but are included for completeness. 389Since 1981, daylight 390saving has begun on the last Sunday in March at 01:00 UTC. 391Until 1995 it ended the last Sunday in September at 01:00 UTC, 392but this changed to the last Sunday in October starting in 1996. 393.Pp 394For purposes of 395display, "LMT" and "BMT" were initially used, respectively. 396Since 397Swiss rules and later EU rules were applied, the display name for the 398timezone has been CET for standard time and CEST for daylight saving 399time. 400.Sh NOTES 401For areas with more than two types of local time, 402you may need to use local standard time in the 403.Em AT 404field of the earliest transition time's rule to ensure that 405the earliest transition time recorded in the compiled file is correct. 406.Pp 407If, 408for a particular zone, 409a clock advance caused by the start of daylight saving 410coincides with and is equal to 411a clock retreat caused by a change in UTC offset, 412.Ic zic 413produces a single transition to daylight saving at the new UTC offset 414(without any change in wall clock time). 415To get separate transitions 416use multiple zone continuation lines 417specifying transition instants using universal time. 418.Sh FILES 419.Pa /usr/share/zoneinfo 420- standard directory used for created files 421.Sh SEE ALSO 422.Xr ctime 3 , 423.Xr tzfile 5 , 424.Xr zdump 8 425.\" @(#)zic.8 8.5 426.\" This file is in the public domain, so clarified as of 427.\" 2009-05-17 by Arthur David Olson. 428