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