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