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