1ZIC(8) System Manager's Manual ZIC(8) 2 3NAME 4 zic - timezone compiler 5 6SYNOPSIS 7 zic [ option ... ] [ filename ... ] 8 9DESCRIPTION 10 The zic program reads text from the file(s) named on the command line 11 and creates the time conversion information files specified in this 12 input. If a filename is "-", standard input is read. 13 14OPTIONS 15 --version 16 Output version information and exit. 17 18 --help Output short usage message and exit. 19 20 -b bloat 21 Output backward-compatibility data as specified by bloat. If 22 bloat is fat, generate additional data entries that work around 23 potential bugs or incompatibilities in older software, such as 24 software that mishandles the 64-bit generated data. If bloat is 25 slim, keep the output files small; this can help check for the 26 bugs and incompatibilities. The default is slim, as software 27 that mishandles 64-bit data typically mishandles timestamps 28 after the year 2038 anyway. Also see the -r option for another 29 way to alter output size. 30 31 -d directory 32 Create time conversion information files in the named directory 33 rather than in the standard directory named below. 34 35 -l timezone 36 Use timezone as local time. zic will act as if the input 37 contained a link line of the form 38 39 Link timezone localtime 40 41 If timezone is -, any already-existing link is removed. 42 43 -L leapsecondfilename 44 Read leap second information from the file with the given name. 45 If this option is not used, no leap second information appears 46 in output files. 47 48 -p timezone 49 Use timezone's rules when handling nonstandard TZ strings like 50 "EET-2EEST" that lack transition rules. zic will act as if the 51 input contained a link line of the form 52 53 Link timezone posixrules 54 55 This feature is obsolete and poorly supported. Among other 56 things it should not be used for timestamps after the year 2037, 57 and it should not be combined with -b slim if timezone's 58 transitions are at standard time or Universal Time (UT) instead 59 of local time. 60 61 If timezone is -, any already-existing link is removed. 62 63 -r [@lo][/@hi] 64 Reduce the size of output files by limiting their applicability 65 to timestamps in the range from lo (inclusive) to hi 66 (exclusive), where lo and hi are possibly-signed decimal counts 67 of seconds since the Epoch (1970-01-01 00:00:00 UTC). Omitted 68 counts default to extreme values. For example, "zic -r @0" 69 omits data intended for negative timestamps (i.e., before the 70 Epoch), and "zic -r @0/@2147483648" outputs data intended only 71 for nonnegative timestamps that fit into 31-bit signed integers. 72 On platforms with GNU date, "zic -r @$(date +%s)" omits data 73 intended for past timestamps. Also see the -b slim option for 74 another way to shrink output size. 75 76 -t file 77 When creating local time information, put the configuration link 78 in the named file rather than in the standard location. 79 80 -v Be more verbose, and complain about the following situations: 81 82 The input specifies a link to a link. 83 84 A year that appears in a data file is outside the range of 85 representable years. 86 87 A time of 24:00 or more appears in the input. Pre-1998 versions 88 of zic prohibit 24:00, and pre-2007 versions prohibit times 89 greater than 24:00. 90 91 A rule goes past the start or end of the month. Pre-2004 92 versions of zic prohibit this. 93 94 A time zone abbreviation uses a %z format. Pre-2015 versions of 95 zic do not support this. 96 97 A timestamp contains fractional seconds. Pre-2018 versions of 98 zic do not support this. 99 100 The input contains abbreviations that are mishandled by pre-2018 101 versions of zic due to a longstanding coding bug. These 102 abbreviations include "L" for "Link", "mi" for "min", "Sa" for 103 "Sat", and "Su" for "Sun". 104 105 The output file does not contain all the information about the 106 long-term future of a timezone, because the future cannot be 107 summarized as an extended POSIX TZ string. For example, as of 108 2019 this problem occurs for Iran's daylight-saving rules for 109 the predicted future, as these rules are based on the Iranian 110 calendar, which cannot be represented. 111 112 The output contains data that may not be handled properly by 113 client code designed for older zic output formats. These 114 compatibility issues affect only timestamps before 1970 or after 115 the start of 2038. 116 117 The output file contains more than 1200 transitions, which may 118 be mishandled by some clients. The current reference client 119 supports at most 2000 transitions; pre-2014 versions of the 120 reference client support at most 1200 transitions. 121 122 A time zone abbreviation has fewer than 3 or more than 6 123 characters. POSIX requires at least 3, and requires 124 implementations to support at least 6. 125 126 An output file name contains a byte that is not an ASCII letter, 127 "-", "/", or "_"; or it contains a file name component that 128 contains more than 14 bytes or that starts with "-". 129 130FILES 131 Input files use the format described in this section; output files use 132 tzfile(5) format. 133 134 Input files should be text files, that is, they should be a series of 135 zero or more lines, each ending in a newline byte and containing at 136 most 511 bytes, and without any NUL bytes. The input text's encoding 137 is typically UTF-8 or ASCII; it should have a unibyte representation 138 for the POSIX Portable Character Set (PPCS) <http://pubs.opengroup.org/ 139 onlinepubs/9699919799/basedefs/V1_chap06.html> and the encoding's non- 140 unibyte characters should consist entirely of non-PPCS bytes. Non-PPCS 141 characters typically occur only in comments: although output file names 142 and time zone abbreviations can contain nearly any character, other 143 software will work better if these are limited to the restricted syntax 144 described under the -v option. 145 146 Input lines are made up of fields. Fields are separated from one 147 another by one or more white space characters. The white space 148 characters are space, form feed, carriage return, newline, tab, and 149 vertical tab. Leading and trailing white space on input lines is 150 ignored. An unquoted sharp character (#) in the input introduces a 151 comment which extends to the end of the line the sharp character 152 appears on. White space characters and sharp characters may be 153 enclosed in double quotes (") if they're to be used as part of a field. 154 Any line that is blank (after comment stripping) is ignored. Nonblank 155 lines are expected to be of one of three types: rule lines, zone lines, 156 and link lines. 157 158 Names must be in English and are case insensitive. They appear in 159 several contexts, and include month and weekday names and keywords such 160 as maximum, only, Rolling, and Zone. A name can be abbreviated by 161 omitting all but an initial prefix; any abbreviation must be 162 unambiguous in context. 163 164 A rule line has the form 165 166 Rule NAME FROM TO - IN ON AT SAVE LETTER/S 167 168 For example: 169 170 Rule US 1967 1973 - Apr lastSun 2:00w 1:00d D 171 172 The fields that make up a rule line are: 173 174 NAME Gives the name of the rule set that contains this line. The 175 name must start with a character that is neither an ASCII digit 176 nor "-" nor "+". To allow for future extensions, an unquoted 177 name should not contain characters from the set 178 "!$%&'()*,/:;<=>?@[\]^`{|}~". 179 180 FROM Gives the first year in which the rule applies. Any signed 181 integer year can be supplied; the proleptic Gregorian calendar 182 is assumed, with year 0 preceding year 1. The word minimum (or 183 an abbreviation) means the indefinite past. The word maximum 184 (or an abbreviation) means the indefinite future. Rules can 185 describe times that are not representable as time values, with 186 the unrepresentable times ignored; this allows rules to be 187 portable among hosts with differing time value types. 188 189 TO Gives the final year in which the rule applies. In addition to 190 minimum and maximum (as above), the word only (or an 191 abbreviation) may be used to repeat the value of the FROM 192 field. 193 194 - Is a reserved field and should always contain "-" for 195 compatibility with older versions of zic. It was previously 196 known as the TYPE field, which could contain values to allow a 197 separate script to further restrict in which "types" of years 198 the rule would apply. 199 200 IN Names the month in which the rule takes effect. Month names 201 may be abbreviated. 202 203 ON Gives the day on which the rule takes effect. Recognized forms 204 include: 205 206 5 the fifth of the month 207 lastSun the last Sunday in the month 208 lastMon the last Monday in the month 209 Sun>=8 first Sunday on or after the eighth 210 Sun<=25 last Sunday on or before the 25th 211 212 A weekday name (e.g., Sunday) or a weekday name preceded by 213 "last" (e.g., lastSunday) may be abbreviated or spelled out in 214 full. There must be no white space characters within the ON 215 field. The "<=" and ">=" constructs can result in a day in the 216 neighboring month; for example, the IN-ON combination "Oct 217 Sun>=31" stands for the first Sunday on or after October 31, 218 even if that Sunday occurs in November. 219 220 AT Gives the time of day at which the rule takes effect, relative 221 to 00:00, the start of a calendar day. Recognized forms 222 include: 223 224 2 time in hours 225 2:00 time in hours and minutes 226 01:28:14 time in hours, minutes, and seconds 227 00:19:32.13 time with fractional seconds 228 12:00 midday, 12 hours after 00:00 229 15:00 3 PM, 15 hours after 00:00 230 24:00 end of day, 24 hours after 00:00 231 260:00 260 hours after 00:00 232 -2:30 2.5 hours before 00:00 233 - equivalent to 0 234 235 Although zic rounds times to the nearest integer second 236 (breaking ties to the even integer), the fractions may be 237 useful to other applications requiring greater precision. The 238 source format does not specify any maximum precision. Any of 239 these forms may be followed by the letter w if the given time 240 is local or "wall clock" time, s if the given time is standard 241 time without any adjustment for daylight saving, or u (or g or 242 z) if the given time is universal time; in the absence of an 243 indicator, local (wall clock) time is assumed. These forms 244 ignore leap seconds; for example, if a leap second occurs at 245 00:59:60 local time, "1:00" stands for 3601 seconds after local 246 midnight instead of the usual 3600 seconds. The intent is that 247 a rule line describes the instants when a clock/calendar set to 248 the type of time specified in the AT field would show the 249 specified date and time of day. 250 251 SAVE Gives the amount of time to be added to local standard time 252 when the rule is in effect, and whether the resulting time is 253 standard or daylight saving. This field has the same format as 254 the AT field except with a different set of suffix letters: s 255 for standard time and d for daylight saving time. The suffix 256 letter is typically omitted, and defaults to s if the offset is 257 zero and to d otherwise. Negative offsets are allowed; in 258 Ireland, for example, daylight saving time is observed in 259 winter and has a negative offset relative to Irish Standard 260 Time. The offset is merely added to standard time; for 261 example, zic does not distinguish a 10:30 standard time plus an 262 0:30 SAVE from a 10:00 standard time plus a 1:00 SAVE. 263 264 LETTER/S 265 Gives the "variable part" (for example, the "S" or "D" in "EST" 266 or "EDT") of time zone abbreviations to be used when this rule 267 is in effect. If this field is "-", the variable part is null. 268 269 A zone line has the form 270 271 Zone NAME STDOFF RULES FORMAT [UNTIL] 272 273 For example: 274 275 Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 276 277 The fields that make up a zone line are: 278 279 NAME The name of the timezone. This is the name used in creating the 280 time conversion information file for the timezone. It should not 281 contain a file name component "." or ".."; a file name component 282 is a maximal substring that does not contain "/". 283 284 STDOFF 285 The amount of time to add to UT to get standard time, without any 286 adjustment for daylight saving. This field has the same format 287 as the AT and SAVE fields of rule lines; begin the field with a 288 minus sign if time must be subtracted from UT. 289 290 RULES The name of the rules that apply in the timezone or, 291 alternatively, a field in the same format as a rule-line SAVE 292 column, giving of the amount of time to be added to local 293 standard time effect, and whether the resulting time is standard 294 or daylight saving. If this field is - then standard time always 295 applies. When an amount of time is given, only the sum of 296 standard time and this amount matters. 297 298 FORMAT 299 The format for time zone abbreviations. The pair of characters 300 %s is used to show where the "variable part" of the time zone 301 abbreviation goes. Alternatively, a format can use the pair of 302 characters %z to stand for the UT offset in the form +-hh, 303 +-hhmm, or +-hhmmss, using the shortest form that does not lose 304 information, where hh, mm, and ss are the hours, minutes, and 305 seconds east (+) or west (-) of UT. Alternatively, a slash (/) 306 separates standard and daylight abbreviations. To conform to 307 POSIX, a time zone abbreviation should contain only alphanumeric 308 ASCII characters, "+" and "-". 309 310 UNTIL The time at which the UT offset or the rule(s) change for a 311 location. It takes the form of one to four fields YEAR [MONTH 312 [DAY [TIME]]]. If this is specified, the time zone information 313 is generated from the given UT offset and rule change until the 314 time specified, which is interpreted using the rules in effect 315 just before the transition. The month, day, and time of day have 316 the same format as the IN, ON, and AT fields of a rule; trailing 317 fields can be omitted, and default to the earliest possible value 318 for the missing fields. 319 320 The next line must be a "continuation" line; this has the same 321 form as a zone line except that the string "Zone" and the name 322 are omitted, as the continuation line will place information 323 starting at the time specified as the "until" information in the 324 previous line in the file used by the previous line. 325 Continuation lines may contain "until" information, just as zone 326 lines do, indicating that the next line is a further 327 continuation. 328 329 If a zone changes at the same instant that a rule would otherwise take 330 effect in the earlier zone or continuation line, the rule is ignored. 331 A zone or continuation line L with a named rule set starts with 332 standard time by default: that is, any of L's timestamps preceding L's 333 earliest rule use the rule in effect after L's first transition into 334 standard time. In a single zone it is an error if two rules take 335 effect at the same instant, or if two zone changes take effect at the 336 same instant. 337 338 If a continuation line subtracts N seconds from the UT offset after a 339 transition that would be interpreted to be later if using the 340 continuation line's UT offset and rules, the "until" time of the 341 previous zone or continuation line is interpreted according to the 342 continuation line's UT offset and rules, and any rule that would 343 otherwise take effect in the next N seconds is instead assumed to take 344 effect simultaneously. For example: 345 346 # Rule NAME FROM TO - IN ON AT SAVE LETTER/S 347 Rule US 1967 2006 - Oct lastSun 2:00 0 S 348 Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 349 # Zone NAME STDOFF RULES FORMAT [UNTIL] 350 Zone America/Menominee -5:00 - EST 1973 Apr 29 2:00 351 -6:00 US C%sT 352 353 Here, an incorrect reading would be there were two clock changes on 354 1973-04-29, the first from 02:00 EST (-05) to 01:00 CST (-06), and the 355 second an hour later from 02:00 CST (-06) to 03:00 CDT (-05). However, 356 zic interprets this more sensibly as a single transition from 02:00 CST 357 (-05) to 02:00 CDT (-05). 358 359 A link line has the form 360 361 Link TARGET LINK-NAME 362 363 For example: 364 365 Link Europe/Istanbul Asia/Istanbul 366 367 The TARGET field should appear as the NAME field in some zone line. 368 The LINK-NAME field is used as an alternative name for that zone; it 369 has the same syntax as a zone line's NAME field. 370 371 Except for continuation lines, lines may appear in any order in the 372 input. However, the behavior is unspecified if multiple zone or link 373 lines define the same name, or if the source of one link line is the 374 target of another. 375 376 The file that describes leap seconds can have leap lines and an 377 expiration line. Leap lines have the following form: 378 379 Leap YEAR MONTH DAY HH:MM:SS CORR R/S 380 381 For example: 382 383 Leap 2016 Dec 31 23:59:60 + S 384 385 The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second 386 happened. The CORR field should be "+" if a second was added or "-" if 387 a second was skipped. The R/S field should be (an abbreviation of) 388 "Stationary" if the leap second time given by the other fields should 389 be interpreted as UTC or (an abbreviation of) "Rolling" if the leap 390 second time given by the other fields should be interpreted as local 391 (wall clock) time. 392 393 The expiration line, if present, has the form: 394 395 Expires YEAR MONTH DAY HH:MM:SS 396 397 For example: 398 399 Expires 2020 Dec 28 00:00:00 400 401 The YEAR, MONTH, DAY, and HH:MM:SS fields give the expiration timestamp 402 in UTC for the leap second table; zic outputs this expiration timestamp 403 by truncating the end of the output file to the timestamp. If there is 404 no expiration line, zic also accepts a comment "#expires E ..." where E 405 is the expiration timestamp as a decimal integer count of seconds since 406 the Epoch, not counting leap seconds. However, the "#expires" comment 407 is an obsolescent feature, and the leap second file should use an 408 expiration line instead of relying on a comment. 409 410EXTENDED EXAMPLE 411 Here is an extended example of zic input, intended to illustrate many 412 of its features. In this example, the EU rules are for the European 413 Union and for its predecessor organization, the European Communities. 414 415 # Rule NAME FROM TO - IN ON AT SAVE LETTER/S 416 Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S 417 Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 - 418 Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S 419 Rule EU 1977 only - Sep lastSun 1:00u 0 - 420 Rule EU 1978 only - Oct 1 1:00u 0 - 421 Rule EU 1979 1995 - Sep lastSun 1:00u 0 - 422 Rule EU 1981 max - Mar lastSun 1:00u 1:00 S 423 Rule EU 1996 max - Oct lastSun 1:00u 0 - 424 425 # Zone NAME STDOFF RULES FORMAT [UNTIL] 426 Zone Europe/Zurich 0:34:08 - LMT 1853 Jul 16 427 0:29:45.50 - BMT 1894 Jun 428 1:00 Swiss CE%sT 1981 429 1:00 EU CE%sT 430 431 Link Europe/Zurich Europe/Vaduz 432 433 In this example, the timezone is named Europe/Zurich but it has an 434 alias as Europe/Vaduz. This example says that Zurich was 34 minutes 435 and 8 seconds east of UT until 1853-07-16 at 00:00, when the legal 436 offset was changed to 7<degree>26'22.50'', which works out to 437 0:29:45.50; zic treats this by rounding it to 0:29:46. After 438 1894-06-01 at 00:00 the UT offset became one hour and Swiss daylight 439 saving rules (defined with lines beginning with "Rule Swiss") apply. 440 From 1981 to the present, EU daylight saving rules have applied, and 441 the UTC offset has remained at one hour. 442 443 In 1941 and 1942, daylight saving time applied from the first Monday in 444 May at 01:00 to the first Monday in October at 02:00. The pre-1981 EU 445 daylight-saving rules have no effect here, but are included for 446 completeness. Since 1981, daylight saving has begun on the last Sunday 447 in March at 01:00 UTC. Until 1995 it ended the last Sunday in 448 September at 01:00 UTC, but this changed to the last Sunday in October 449 starting in 1996. 450 451 For purposes of display, "LMT" and "BMT" were initially used, 452 respectively. Since Swiss rules and later EU rules were applied, the 453 time zone abbreviation has been CET for standard time and CEST for 454 daylight saving time. 455 456FILES 457 /etc/localtime 458 Default local timezone file. 459 460 /usr/share/zoneinfo 461 Default timezone information directory. 462 463NOTES 464 For areas with more than two types of local time, you may need to use 465 local standard time in the AT field of the earliest transition time's 466 rule to ensure that the earliest transition time recorded in the 467 compiled file is correct. 468 469 If, for a particular timezone, a clock advance caused by the start of 470 daylight saving coincides with and is equal to a clock retreat caused 471 by a change in UT offset, zic produces a single transition to daylight 472 saving at the new UT offset without any change in local (wall clock) 473 time. To get separate transitions use multiple zone continuation lines 474 specifying transition instants using universal time. 475 476SEE ALSO 477 tzfile(5), zdump(8) 478 479 ZIC(8) 480