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