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, 2016 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. 333To conform to POSIX, a time zone abbreviation should contain only 334alphanumeric ASCII characters, 335.Dq + 336and 337.Dq - . 338.It UNTILYEAR [MONTH [DAY [TIME]]] 339The time at which the UT offset or the rule(s) change for a location. 340It is specified as a year, a month, a day, and a time of day. 341If this is specified, 342the time zone information is generated from the given UT offset 343and rule change until the time specified. 344The month, day, and time of day have the same format as the IN, ON, and AT 345fields of a rule; trailing fields can be omitted, and default to the 346earliest possible value for the missing fields. 347.Pp 348The next line must be a 349.Dq continuation 350line; this has the same form as a zone line except that the 351string 352.Dq Zone 353and the name are omitted, as the continuation line will 354place information starting at the time specified as the 355.Dq until 356information in the previous line in the file used by the previous line. 357Continuation lines may contain 358.Dq until 359information, just as zone lines do, indicating that the next line is a further 360continuation. 361.El 362.Pp 363A link line has the form 364.Dl "Link LINK-FROM LINK-TO" 365For example: 366.Dl "Link Europe/Istanbul Asia/Istanbul" 367The 368.Em LINK-FROM 369field should appear as the 370.Em NAME 371field in some zone line; 372the 373.Em LINK-TO 374field is used as an alternate name for that zone. 375.Pp 376Except for continuation lines, 377lines may appear in any order in the input. 378However, the behavior is unspecified if multiple zone or link 379lines define the same name, or if the source of one link line is the 380target of another. 381.Pp 382Lines in the file that describes leap seconds have the following form: 383.Dl "Leap YEAR MONTH DAY HH:MM:SS CORR R/S" 384For example: 385.Dl "Leap 1974 Dec 31 23:59:60 + S" 386The 387.Em YEAR , 388.Em MONTH , 389.Em DAY , 390and 391.Em HH:MM:SS 392fields tell when the leap second happened. 393The 394.Em CORR 395field 396should be 397.Dq + 398if a second was added 399or 400.Dq - 401if a second was skipped. 402The 403.Em R/S 404field 405should be (an abbreviation of) 406.Dq Stationary 407if the leap second time given by the other fields should be interpreted as UTC 408or 409(an abbreviation of) 410.Dq Rolling 411if the leap second time given by the other fields should be interpreted as 412local wall clock time. 413.Sh FILES 414.Bl -tag -width ".Pa /usr/share/zoneinfo" -compact 415.It Pa /usr/share/zoneinfo 416standard directory used for created files 417.El 418.Sh EXAMPLES 419Here is an extended example of 420.Nm 421input, intended to illustrate many of its features. 422.Bd -literal 423# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 424Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S 425Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 - 426 427Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S 428Rule EU 1977 only - Sep lastSun 1:00u 0 - 429Rule EU 1978 only - Oct 1 1:00u 0 - 430Rule EU 1979 1995 - Sep lastSun 1:00u 0 - 431Rule EU 1981 max - Mar lastSun 1:00u 1:00 S 432Rule EU 1996 max - Oct lastSun 1:00u 0 - 433 434# Zone NAME GMTOFF RULES/SAVE FORMAT UNTIL 435Zone Europe/Zurich 0:34:08 - LMT 1853 Jul 16 436 0:29:46 - BMT 1894 Jun 437 1:00 Swiss CE%sT 1981 438 1:00 EU CE%sT 439 440Link Europe/Zurich Switzerland 441.Ed 442.Pp 443In this example, the zone is named Europe/Zurich but it has an alias 444as Switzerland. 445Zurich was 34 minutes and 8 seconds west of UT until 4461853-07-16 at 00:00, when the offset changed to 7o26'22.50''; 447although this works out to 0:29:45.50, the 448input format cannot represent fractional seconds so it is rounded here. 449After 1894-06-01 at 00:00 Swiss daylight saving rules (defined 450with lines beginning with 451.Dq Rule Swiss ) 452apply, and the UT offset became one hour. 453From 1981 to the present, EU daylight saving rules have 454applied, and the UTC offset has remained at one hour. 455.Pp 456In 1941 and 1942, daylight saving time applied 457from the first Monday in May at 01:00 to the first Monday in October 458at 02:00. 459The pre-1981 EU daylight-saving rules have no effect 460here, but are included for completeness. 461Since 1981, daylight 462saving has begun on the last Sunday in March at 01:00 UTC. 463Until 1995 it ended the last Sunday in September at 01:00 UTC, 464but this changed to the last Sunday in October starting in 1996. 465.Pp 466For purposes of 467display, 468.Dq LMT 469and 470.Dq BMT 471were initially used, respectively. 472Since 473Swiss rules and later EU rules were applied, the display name for the 474timezone has been CET for standard time and CEST for daylight saving 475time. 476.Sh NOTES 477For areas with more than two types of local time, 478you may need to use local standard time in the 479.Em AT 480field of the earliest transition time's rule to ensure that 481the earliest transition time recorded in the compiled file is correct. 482.Pp 483If, 484for a particular zone, 485a clock advance caused by the start of daylight saving 486coincides with and is equal to 487a clock retreat caused by a change in UT offset, 488.Nm 489produces a single transition to daylight saving at the new UT offset 490(without any change in wall clock time). 491To get separate transitions 492use multiple zone continuation lines 493specifying transition instants using universal time. 494.Sh SEE ALSO 495.Xr ctime 3 , 496.Xr tzfile 5 , 497.Xr zdump 8 498