1zic(8) System Manager's Manual zic(8)
2
6 zic - timezone compiler
7
9 zic [ option ... ] [ filename ... ]
10
12 The zic program reads text from the file(s) named on the command line
13 and creates the timezone information format (TZif) files specified in
14 this input. If a filename is “-”, standard input is read.
15
17 --version
18 Output version information and exit.
19 --help Output short usage message and exit.
21 -b bloat
23 Output backward-compatibility data as specified by bloat. If
24 bloat is fat, generate additional data entries that work around
25 potential bugs or incompatibilities in older software, such as
26 software that mishandles the 64-bit generated data. If bloat is
27 slim, keep the output files small; this can help check for the
28 bugs and incompatibilities. The default is slim, as software
29 that mishandles 64-bit data typically mishandles timestamps af‐
30 ter the year 2038 anyway. Also see the -r option for another
31 way to alter output size.
32 -d directory
34 Create time conversion information files in the named directory
35 rather than in the standard directory named below.
36 -l timezone
38 Use timezone as local time. zic will act as if the input con‐
39 tained a link line of the form
40 Link timezone localtime
42 If timezone is -, any already-existing link is removed.
44 -L leapsecondfilename
46 Read leap second information from the file with the given name.
47 If this option is not used, no leap second information appears
48 in output files.
49 -p timezone
51 Use timezone's rules when handling nonstandard TZ strings like
52 "EET-2EEST" that lack transition rules. zic will act as if the
53 input contained a link line of the form
54 Link timezone posixrules
56 Unless timezone is “-”, this option is obsolete and poorly sup‐
58 ported. Among other things it should not be used for timestamps
59 after the year 2037, and it should not be combined with -b slim
60 if timezone's transitions are at standard time or Universal Time
61 (UT) instead of local time.
62 If timezone is -, any already-existing link is removed.
64 -r [@lo][/@hi]
66 Limit the applicability of output files to timestamps in the
67 range from lo (inclusive) to hi (exclusive), where lo and hi are
68 possibly signed decimal counts of seconds since the Epoch
69 (1970-01-01 00:00:00 UTC). Omitted counts default to extreme
70 values. The output files use UT offset 0 and abbreviation “-00”
71 in place of the omitted timestamp data. For example, “zic -r
72 @0” omits data intended for negative timestamps (i.e., before
73 the Epoch), and “zic -r @0/@2147483648” outputs data intended
74 only for nonnegative timestamps that fit into 31-bit signed in‐
75 tegers. On platforms with GNU date, “zic -r @$(date +%s)” omits
76 data intended for past timestamps. Although this option typi‐
77 cally reduces the output file's size, the size can increase due
78 to the need to represent the timestamp range boundaries, partic‐
79 ularly if hi causes a TZif file to contain explicit entries for
80 pre-hi transitions rather than concisely representing them with
81 an extended POSIX TZ string. Also see the -b slim option for
82 another way to shrink output size.
83 -R @hi Generate redundant trailing explicit transitions for timestamps
85 that occur less than hi seconds since the Epoch, even though the
86 transitions could be more concisely represented via the extended
87 POSIX TZ string. This option does not affect the represented
88 timestamps. Although it accommodates nonstandard TZif readers
89 that ignore the extended POSIX TZ string, it increases the size
90 of the altered output files.
91 -t file
93 When creating local time information, put the configuration link
94 in the named file rather than in the standard location.
95 -v Be more verbose, and complain about the following situations:
97 The input specifies a link to a link, something not supported by
99 some older parsers, including zic itself through release 2022e.
100 A year that appears in a data file is outside the range of rep‐
102 resentable years.
103 A time of 24:00 or more appears in the input. Pre-1998 versions
105 of zic prohibit 24:00, and pre-2007 versions prohibit times
106 greater than 24:00.
107 A rule goes past the start or end of the month. Pre-2004 ver‐
109 sions of zic prohibit this.
110 A time zone abbreviation uses a %z format. Pre-2015 versions of
112 zic do not support this.
113 A timestamp contains fractional seconds. Pre-2018 versions of
115 zic do not support this.
116 The input contains abbreviations that are mishandled by pre-2018
118 versions of zic due to a longstanding coding bug. These abbre‐
119 viations include “L” for “Link”, “mi” for “min”, “Sa” for “Sat”,
120 and “Su” for “Sun”.
121 The output file does not contain all the information about the
123 long-term future of a timezone, because the future cannot be
124 summarized as an extended POSIX TZ string. For example, as of
125 2023 this problem occurs for Morocco's daylight-saving rules, as
126 these rules are based on predictions for when Ramadan will be
127 observed, something that an extended POSIX TZ string cannot rep‐
128 resent.
129 The output contains data that may not be handled properly by
131 client code designed for older zic output formats. These com‐
132 patibility issues affect only timestamps before 1970 or after
133 the start of 2038.
134 The output contains a truncated leap second table, which can
136 cause some older TZif readers to misbehave. This can occur if
137 the -L option is used, and either an Expires line is present or
138 the -r option is also used.
139 The output file contains more than 1200 transitions, which may
141 be mishandled by some clients. The current reference client
142 supports at most 2000 transitions; pre-2014 versions of the ref‐
143 erence client support at most 1200 transitions.
144 A time zone abbreviation has fewer than 3 or more than 6 charac‐
146 ters. POSIX requires at least 3, and requires implementations
147 to support at least 6.
148 An output file name contains a byte that is not an ASCII letter,
150 “-”, “/”, or “_”; or it contains a file name component that con‐
151 tains more than 14 bytes or that starts with “-”.
152
154 Input files use the format described in this section; output files use
155 tzfile(5) format.
156 Input files should be text files, that is, they should be a series of
158 zero or more lines, each ending in a newline byte and containing at
159 most 2048 bytes counting the newline, and without any NUL bytes. The
160 input text's encoding is typically UTF-8 or ASCII; it should have a
161 unibyte representation for the POSIX Portable Character Set (PPCS)
162 ⟨https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06
163 .html⟩ and the encoding's non-unibyte characters should consist en‐
164 tirely of non-PPCS bytes. Non-PPCS characters typically occur only in
165 comments: although output file names and time zone abbreviations can
166 contain nearly any character, other software will work better if these
167 are limited to the restricted syntax described under the -v option.
168 Input lines are made up of fields. Fields are separated from one an‐
170 other by one or more white space characters. The white space charac‐
171 ters are space, form feed, carriage return, newline, tab, and vertical
172 tab. Leading and trailing white space on input lines is ignored. An
173 unquoted sharp character (#) in the input introduces a comment which
174 extends to the end of the line the sharp character appears on. White
175 space characters and sharp characters may be enclosed in double quotes
176 (") if they're to be used as part of a field. Any line that is blank
177 (after comment stripping) is ignored. Nonblank lines are expected to
178 be of one of three types: rule lines, zone lines, and link lines.
179 Names must be in English and are case insensitive. They appear in sev‐
181 eral contexts, and include month and weekday names and keywords such as
182 maximum, only, Rolling, and Zone. A name can be abbreviated by omit‐
183 ting all but an initial prefix; any abbreviation must be unambiguous in
184 context.
185 A rule line has the form
187 Rule NAME FROM TO - IN ON AT SAVE LETTER/S
189 For example:
191 Rule US 1967 1973 - Apr lastSun 2:00w 1:00d D
193 The fields that make up a rule line are:
195 NAME Gives the name of the rule set that contains this line. The
197 name must start with a character that is neither an ASCII digit
198 nor “-” nor “+”. To allow for future extensions, an unquoted
199 name should not contain characters from the set
200 “!$%&'()*,/:;<=>?@[\]^`{|}~”.
201 FROM Gives the first year in which the rule applies. Any signed in‐
203 teger year can be supplied; the proleptic Gregorian calendar is
204 assumed, with year 0 preceding year 1. The word minimum (or an
205 abbreviation) means the indefinite past. The word maximum (or
206 an abbreviation) means the indefinite future. Rules can de‐
207 scribe times that are not representable as time values, with
208 the unrepresentable times ignored; this allows rules to be por‐
209 table among hosts with differing time value types.
210 TO Gives the final year in which the rule applies. In addition to
212 minimum and maximum (as above), the word only (or an abbrevia‐
213 tion) may be used to repeat the value of the FROM field.
214 - Is a reserved field and should always contain “-” for compati‐
216 bility with older versions of zic. It was previously known as
217 the TYPE field, which could contain values to allow a separate
218 script to further restrict in which “types” of years the rule
219 would apply.
220 IN Names the month in which the rule takes effect. Month names
222 may be abbreviated.
223 ON Gives the day on which the rule takes effect. Recognized forms
225 include:
226 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 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 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 in‐
243 clude:
244 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 Although zic rounds times to the nearest integer second (break‐
257 ing ties to the even integer), the fractions may be useful to
258 other applications requiring greater precision. The source
259 format does not specify any maximum precision. Any of these
260 forms may be followed by the letter w if the given time is lo‐
261 cal or “wall clock” time, s if the given time is standard time
262 without any adjustment for daylight saving, or u (or g or z) if
263 the given time is universal time; in the absence of an indica‐
264 tor, local (wall clock) time is assumed. These forms ignore
265 leap seconds; for example, if a leap second occurs at 00:59:60
266 local time, “1:00” stands for 3601 seconds after local midnight
267 instead of the usual 3600 seconds. The intent is that a rule
268 line describes the instants when a clock/calendar set to the
269 type of time specified in the AT field would show the specified
270 date and time of day.
271 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 Ire‐
279 land, for example, daylight saving time is observed in winter
280 and has a negative offset relative to Irish Standard Time. The
281 offset is merely added to standard time; for example, zic does
282 not distinguish a 10:30 standard time plus an 0:30 SAVE from a
283 10:00 standard time plus a 1:00 SAVE.
284 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 A zone line has the form
291 Zone NAME STDOFF RULES FORMAT [UNTIL]
293 For example:
295 Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00
297 The fields that make up a zone line are:
299 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 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 sub‐
310 tracted from UT.
311 RULES The name of the rules that apply in the timezone or, alterna‐
313 tively, a field in the same format as a rule-line SAVE column,
314 giving the amount of time to be added to local standard time and
315 whether the resulting time is standard or daylight saving. If
316 this field is - then standard time always applies. When an
317 amount of time is given, only the sum of standard time and this
318 amount matters.
319 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 ab‐
323 breviation goes. Alternatively, a format can use the pair of
324 characters %z to stand for the UT offset in the form ±hh, ±hhmm,
325 or ±hhmmss, using the shortest form that does not lose informa‐
326 tion, where hh, mm, and ss are the hours, minutes, and seconds
327 east (+) or west (-) of UT. Alternatively, a slash (/) separates
328 standard and daylight abbreviations. To conform to POSIX, a time
329 zone abbreviation should contain only alphanumeric ASCII charac‐
330 ters, “+” and “-”. By convention, the time zone abbreviation
331 “-00” is a placeholder that means local time is unspecified.
332 UNTIL The time at which the UT offset or the rule(s) change for a loca‐
334 tion. It takes the form of one to four fields YEAR [MONTH [DAY
335 [TIME]]]. If this is specified, the time zone information is
336 generated from the given UT offset and rule change until the time
337 specified, which is interpreted using the rules in effect just
338 before the transition. The month, day, and time of day have the
339 same format as the IN, ON, and AT fields of a rule; trailing
340 fields can be omitted, and default to the earliest possible value
341 for the missing fields.
342 The next line must be a “continuation” line; this has the same
344 form as a zone line except that the string “Zone” and the name
345 are omitted, as the continuation line will place information
346 starting at the time specified as the “until” information in the
347 previous line in the file used by the previous line. Continua‐
348 tion lines may contain “until” information, just as zone lines
349 do, indicating that the next line is a further continuation.
350 If a zone changes at the same instant that a rule would otherwise take
352 effect in the earlier zone or continuation line, the rule is ignored.
353 A zone or continuation line L with a named rule set starts with stan‐
354 dard time by default: that is, any of L's timestamps preceding L's ear‐
355 liest rule use the rule in effect after L's first transition into stan‐
356 dard time. In a single zone it is an error if two rules take effect at
357 the same instant, or if two zone changes take effect at the same in‐
358 stant.
359 If a continuation line subtracts N seconds from the UT offset after a
361 transition that would be interpreted to be later if using the continua‐
362 tion line's UT offset and rules, the “until” time of the previous zone
363 or continuation line is interpreted according to the continuation
364 line's UT offset and rules, and any rule that would otherwise take ef‐
365 fect in the next N seconds is instead assumed to take effect simultane‐
366 ously. For example:
367 # Rule NAME FROM TO - IN ON AT SAVE LETTER/S
369 Rule US 1967 2006 - Oct lastSun 2:00 0 S
370 Rule US 1967 1973 - Apr lastSun 2:00 1:00 D
371 # Zone NAME STDOFF RULES FORMAT [UNTIL]
372 Zone America/Menominee -5:00 - EST 1973 Apr 29 2:00
373 -6:00 US C%sT
374 Here, an incorrect reading would be there were two clock changes on
376 1973-04-29, the first from 02:00 EST (-05) to 01:00 CST (-06), and the
377 second an hour later from 02:00 CST (-06) to 03:00 CDT (-05). However,
378 zic interprets this more sensibly as a single transition from 02:00 CST
379 (-05) to 02:00 CDT (-05).
380 A link line has the form
382 Link TARGET LINK-NAME
384 For example:
386 Link Europe/Istanbul Asia/Istanbul
388 The TARGET field should appear as the NAME field in some zone line or
390 as the LINK-NAME field in some link line. The LINK-NAME field is used
391 as an alternative name for that zone; it has the same syntax as a zone
392 line's NAME field. Links can chain together, although the behavior is
393 unspecified if a chain of one or more links does not terminate in a
394 Zone name. A link line can appear before the line that defines the
395 link target. For example:
396 Link Greenwich G_M_T
398 Link Etc/GMT Greenwich
399 Zone Etc/GMT 0 - GMT
400 The two links are chained together, and G_M_T, Greenwich, and Etc/GMT
402 all name the same zone.
403 Except for continuation lines, lines may appear in any order in the in‐
405 put. However, the behavior is unspecified if multiple zone or link
406 lines define the same name.
407 The file that describes leap seconds can have leap lines and an expira‐
409 tion line. Leap lines have the following form:
410 Leap YEAR MONTH DAY HH:MM:SS CORR R/S
412 For example:
414 Leap 2016 Dec 31 23:59:60 + S
416 The YEAR, MONTH, DAY, and HH:MM:SS fields tell when the leap second
418 happened. The CORR field should be “+” if a second was added or “-” if
419 a second was skipped. The R/S field should be (an abbreviation of)
420 “Stationary” if the leap second time given by the other fields should
421 be interpreted as UTC or (an abbreviation of) “Rolling” if the leap
422 second time given by the other fields should be interpreted as local
423 (wall clock) time.
424 Rolling leap seconds were implemented back when it was not clear
426 whether common practice was rolling or stationary, with concerns that
427 one would see Times Square ball drops where there'd be a “3... 2...
428 1... leap... Happy New Year” countdown, placing the leap second at mid‐
429 night New York time rather than midnight UTC. However, this countdown
430 style does not seem to have caught on, which means rolling leap seconds
431 are not used in practice; also, they are not supported if the -r option
432 is used.
433 The expiration line, if present, has the form:
435 Expires YEAR MONTH DAY HH:MM:SS
437 For example:
439 Expires 2020 Dec 28 00:00:00
441 The YEAR, MONTH, DAY, and HH:MM:SS fields give the expiration timestamp
443 in UTC for the leap second table.
444
446 Here is an extended example of zic input, intended to illustrate many
447 of its features.
448 # Rule NAME FROM TO - IN ON AT SAVE LETTER/S
450 Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S
451 Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 -
452 Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S
453 Rule EU 1977 only - Sep lastSun 1:00u 0 -
454 Rule EU 1978 only - Oct 1 1:00u 0 -
455 Rule EU 1979 1995 - Sep lastSun 1:00u 0 -
456 Rule EU 1981 max - Mar lastSun 1:00u 1:00 S
457 Rule EU 1996 max - Oct lastSun 1:00u 0 -
458 # Zone NAME STDOFF RULES FORMAT [UNTIL]
460 Zone Europe/Zurich 0:34:08 - LMT 1853 Jul 16
461 0:29:45.50 - BMT 1894 Jun
462 1:00 Swiss CE%sT 1981
463 1:00 EU CE%sT
464 Link Europe/Zurich Europe/Vaduz
466 In this example, the EU rules are for the European Union and for its
468 predecessor organization, the European Communities. The timezone is
469 named Europe/Zurich and it has the alias Europe/Vaduz. This example
470 says that Zurich was 34 minutes and 8 seconds east of UT until
471 1853-07-16 at 00:00, when the legal offset was changed to 7 degrees 26
472 minutes 22.50 seconds, which works out to 0:29:45.50; zic treats this
473 by rounding it to 0:29:46. After 1894-06-01 at 00:00 the UT offset be‐
474 came one hour and Swiss daylight saving rules (defined with lines be‐
475 ginning with “Rule Swiss”) apply. From 1981 to the present, EU day‐
476 light saving rules have applied, and the UTC offset has remained at one
477 hour.
478 In 1941 and 1942, daylight saving time applied from the first Monday in
480 May at 01:00 to the first Monday in October at 02:00. The pre-1981 EU
481 daylight-saving rules have no effect here, but are included for com‐
482 pleteness. Since 1981, daylight saving has begun on the last Sunday in
483 March at 01:00 UTC. Until 1995 it ended the last Sunday in September
484 at 01:00 UTC, but this changed to the last Sunday in October starting
485 in 1996.
486 For purposes of display, “LMT” and “BMT” were initially used, respec‐
488 tively. Since Swiss rules and later EU rules were applied, the time
489 zone abbreviation has been CET for standard time and CEST for daylight
490 saving time.
491
493 /etc/localtime
494 Default local timezone file.
495 /usr/share/zoneinfo
497 Default timezone information directory.
498
500 For areas with more than two types of local time, you may need to use
501 local standard time in the AT field of the earliest transition time's
502 rule to ensure that the earliest transition time recorded in the com‐
503 piled file is correct.
504 If, for a particular timezone, a clock advance caused by the start of
506 daylight saving coincides with and is equal to a clock retreat caused
507 by a change in UT offset, zic produces a single transition to daylight
508 saving at the new UT offset without any change in local (wall clock)
509 time. To get separate transitions use multiple zone continuation lines
510 specifying transition instants using universal time.
511
513 tzfile(5), zdump(8)
514Time Zone Database zic(8)