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