Debian Codegraph @

upstream/debian-trixie/man8/zic.8

raw
1 .\" This file is in the public domain, so clarified as of
2 .\" 2009-05-17 by Arthur David Olson.
3 .TH zic 8 "" "Time Zone Database"
4 .SH NAME
5 zic \- timezone compiler
6 .SH SYNOPSIS
7 .B zic
8 [
9 .I option
10 \&... ] [
11 .I filename
12 \&... ]
13 .SH DESCRIPTION
14 .ie '\(lq'' .ds lq \&"\"
15 .el .ds lq \(lq\"
16 .ie '\(rq'' .ds rq \&"\"
17 .el .ds rq \(rq\"
18 .de q
19 \\$3\*(lq\\$1\*(rq\\$2
20 ..
21 .ie '\(la'' .ds < <
22 .el .ds < \(la
23 .ie '\(ra'' .ds > >
24 .el .ds > \(ra
25 .ie \n(.g \{\
26 . ds : \:
27 . ds - \f(CR-\fP
28 .\}
29 .el \{\
30 . ds :
31 . ds - \-
32 .\}
33 .ds d " degrees
34 .ds m " minutes
35 .ds s " seconds
36 .ds _ " \&
37 .if t \{\
38 . if \n(.g .if c \(de .if c \(fm .if c \(sd \{\
39 . ds d \(de
40 . ds m \(fm
41 . ds s \(sd
42 . ds _ \|
43 . \}
44 .\}
45 The
46 .B zic
47 program reads text from the file(s) named on the command line
48 and creates the timezone information format (TZif) files
49 specified in this input.
50 If a
51 .I filename
52 is
53 .q "\*-" ,
54 standard input is read.
55 .SH OPTIONS
56 .TP
57 .B "\*-\*-version"
58 Output version information and exit.
59 .TP
60 .B \*-\*-help
61 Output short usage message and exit.
62 .TP
63 .BI "\*-b " bloat
64 Output backward-compatibility data as specified by
65 .IR bloat .
66 If
67 .I bloat
68 is
69 .BR fat ,
70 generate additional data entries that work around potential bugs or
71 incompatibilities in older software, such as software that mishandles
72 the 64-bit generated data.
73 If
74 .I bloat
75 is
76 .BR slim ,
77 keep the output files small; this can help check for the bugs
78 and incompatibilities.
79 The default is
80 .BR slim ,
81 as software that mishandles 64-bit data typically
82 mishandles timestamps after the year 2038 anyway.
83 Also see the
84 .B \*-r
85 option for another way to alter output size.
86 .TP
87 .BI "\*-d " directory
88 Create time conversion information files in the named directory rather than
89 in the standard directory named below.
90 .TP
91 .BI "\*-l " timezone
92 Use
93 .I timezone
94 as local time.
95 .B zic
96 will act as if the input contained a link line of the form
97 .sp
98 .ti +2
99 .ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u
100 Link \fItimezone\fP localtime
101 .sp
102 If
103 .I timezone
104 is
105 .BR \*- ,
106 any already-existing link is removed.
107 .TP
108 .BI "\*-L " leapsecondfilename
109 Read leap second information from the file with the given name.
110 If this option is not used,
111 no leap second information appears in output files.
112 .TP
113 .BI "\*-p " timezone
114 Use
115 .IR timezone 's
116 rules when handling nonstandard
117 TZ strings like "EET\*-2EEST" that lack transition rules.
118 .B zic
119 will act as if the input contained a link line of the form
120 .sp
121 .ti +2
122 Link \fItimezone\fP posixrules
123 .sp
124 If
125 .I timezone
126 is
127 .q "\*-"
128 (the default), any already-existing link is removed.
129 .sp
130 Unless
131 .I timezone is
132 .q "\*-" ,
133 this option is obsolete and poorly supported.
134 Among other things it should not be used for timestamps after the year 2037,
135 and it should not be combined with
136 .B "\*-b slim"
137 if
138 .IR timezone 's
139 transitions are at standard time or Universal Time (UT) instead of local time.
140 .TP
141 .BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]"
142 Limit the applicability of output files
143 to timestamps in the range from
144 .I lo
145 (inclusive) to
146 .I hi
147 (exclusive), where
148 .I lo
149 and
150 .I hi
151 are possibly signed decimal counts of seconds since the Epoch
152 (1970-01-01 00:00:00 UTC).
153 Omitted counts default to extreme values.
154 The output files use UT offset 0 and abbreviation
155 .q "\*-00"
156 in place of the omitted timestamp data.
157 For example,
158 .q "zic \*-r @0"
159 omits data intended for negative timestamps (i.e., before the Epoch), and
160 .q "zic \*-r @0/@2147483648"
161 outputs data intended only for nonnegative timestamps that fit into
162 31-bit signed integers.
163 On platforms with GNU
164 .BR date ,
165 .q "zic \*-r @$(date +%s)"
166 omits data intended for past timestamps.
167 Although this option typically reduces the output file's size,
168 the size can increase due to the need to represent the timestamp range
169 boundaries, particularly if
170 .I hi
171 causes a TZif file to contain explicit entries for
172 .RI pre- hi
173 transitions rather than concisely representing them
174 with an extended POSIX.1-2017 TZ string.
175 Also see the
176 .B "\*-b slim"
177 option for another way to shrink output size.
178 .TP
179 .BI "\*-R @" hi
180 Generate redundant trailing explicit transitions for timestamps
181 that occur less than
182 .I hi
183 seconds since the Epoch, even though the transitions could be
184 more concisely represented via the extended POSIX.1-2017 TZ string.
185 This option does not affect the represented timestamps.
186 Although it accommodates nonstandard TZif readers
187 that ignore the extended POSIX.1-2017 TZ string,
188 it increases the size of the altered output files.
189 .TP
190 .BI "\*-t " file
191 When creating local time information, put the configuration link in
192 the named file rather than in the standard location.
193 .TP
194 .B \*-v
195 Be more verbose, and complain about the following situations:
196 .RS
197 .PP
198 The input specifies a link to a link,
199 something not supported by some older parsers, including
200 .B zic
201 itself through release 2022e.
202 .PP
203 A year that appears in a data file is outside the range
204 of representable years.
205 .PP
206 A time of 24:00 or more appears in the input.
207 Pre-1998 versions of
208 .B zic
209 prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00.
210 .PP
211 A rule goes past the start or end of the month.
212 Pre-2004 versions of
213 .B zic
214 prohibit this.
215 .PP
216 A time zone abbreviation uses a
217 .B %z
218 format.
219 Pre-2015 versions of
220 .B zic
221 do not support this.
222 .PP
223 A timestamp contains fractional seconds.
224 Pre-2018 versions of
225 .B zic
226 do not support this.
227 .PP
228 The input contains abbreviations that are mishandled by pre-2018 versions of
229 .B zic
230 due to a longstanding coding bug.
231 These abbreviations include
232 .q L
233 for
234 .q Link ,
235 .q mi
236 for
237 .q min ,
238 .q Sa
239 for
240 .q Sat ,
241 and
242 .q Su
243 for
244 .q Sun .
245 .PP
246 The output file does not contain all the information about the
247 long-term future of a timezone, because the future cannot be summarized as
248 an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem
249 occurs for Morocco's daylight-saving rules, as these rules are based
250 on predictions for when Ramadan will be observed, something that
251 an extended POSIX.1-2017 TZ string cannot represent.
252 .PP
253 The output contains data that may not be handled properly by client
254 code designed for older
255 .B zic
256 output formats. These compatibility issues affect only timestamps
257 before 1970 or after the start of 2038.
258 .PP
259 The output contains a truncated leap second table,
260 which can cause some older TZif readers to misbehave.
261 This can occur if the
262 .B "\*-L"
263 option is used, and either an Expires line is present or
264 the
265 .B "\*-r"
266 option is also used.
267 .PP
268 The output file contains more than 1200 transitions,
269 which may be mishandled by some clients.
270 The current reference client supports at most 2000 transitions;
271 pre-2014 versions of the reference client support at most 1200
272 transitions.
273 .PP
274 A time zone abbreviation has fewer than 3 or more than 6 characters.
275 POSIX requires at least 3, and requires implementations to support
276 at least 6.
277 .PP
278 An output file name contains a byte that is not an ASCII letter,
279 .q "\*-" ,
280 .q "/" ,
281 or
282 .q "_" ;
283 or it contains a file name component that contains more than 14 bytes
284 or that starts with
285 .q "\*-" .
286 .RE
287 .SH FILES
288 Input files use the format described in this section; output files use
289 .BR tzfile (5)
290 format.
291 .PP
292 Input files should be text files, that is, they should be a series of
293 zero or more lines, each ending in a newline byte and containing at
294 most 2048 bytes counting the newline, and without any NUL bytes.
295 The input text's encoding
296 is typically UTF-8 or ASCII; it should have a unibyte representation
297 for the POSIX Portable Character Set (PPCS)
298 \*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
299 and the encoding's non-unibyte characters should consist entirely of
300 non-PPCS bytes. Non-PPCS characters typically occur only in comments:
301 although output file names and time zone abbreviations can contain
302 nearly any character, other software will work better if these are
303 limited to the restricted syntax described under the
304 .B \*-v
305 option.
306 .PP
307 Input lines are made up of fields.
308 Fields are separated from one another by one or more white space characters.
309 The white space characters are space, form feed, carriage return, newline,
310 tab, and vertical tab.
311 Leading and trailing white space on input lines is ignored.
312 An unquoted sharp character (#) in the input introduces a comment which extends
313 to the end of the line the sharp character appears on.
314 White space characters and sharp characters may be enclosed in double quotes
315 (") if they're to be used as part of a field.
316 Any line that is blank (after comment stripping) is ignored.
317 Nonblank lines are expected to be of one of three types:
318 rule lines, zone lines, and link lines.
319 .PP
320 Names must be in English and are case insensitive.
321 They appear in several contexts, and include month and weekday names
322 and keywords such as
323 .BR "maximum" ,
324 .BR "only" ,
325 .BR "Rolling" ,
326 and
327 .BR "Zone" .
328 A name can be abbreviated by omitting all but an initial prefix; any
329 abbreviation must be unambiguous in context.
330 .PP
331 A rule line has the form
332 .nf
333 .ti +2
334 .ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u
335 .sp
336 Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S
337 .sp
338 For example:
339 .ti +2
340 .sp
341 Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D
342 .sp
343 .fi
344 The fields that make up a rule line are:
345 .TP
346 .B NAME
347 Gives the name of the rule set that contains this line.
348 The name must start with a character that is neither
349 an ASCII digit nor
350 .q \*-
351 nor
352 .q + .
353 To allow for future extensions,
354 an unquoted name should not contain characters from the set
355 .ie \n(.g .q \f(CR!$%&\(aq()*,/:;<=>?@[\e]\(ha\(ga{|}\(ti\fP .
356 .el .ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP .
357 .el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ .
358 .TP
359 .B FROM
360 Gives the first year in which the rule applies.
361 Any signed integer year can be supplied; the proleptic Gregorian calendar
362 is assumed, with year 0 preceding year 1.
363 Rules can describe times that are not representable as time values,
364 with the unrepresentable times ignored; this allows rules to be portable
365 among hosts with differing time value types.
366 .TP
367 .B TO
368 Gives the final year in which the rule applies.
369 The word
370 .B maximum
371 (or an abbreviation) means the indefinite future, and the word
372 .B only
373 (or an abbreviation)
374 may be used to repeat the value of the
375 .B FROM
376 field.
377 .TP
378 .B \*-
379 Is a reserved field and should always contain
380 .q \*-
381 for compatibility with older versions of
382 .BR zic .
383 It was previously known as the
384 .B TYPE
385 field, which could contain values to allow a
386 separate script to further restrict in which
387 .q types
388 of years the rule would apply.
389 .TP
390 .B IN
391 Names the month in which the rule takes effect.
392 Month names may be abbreviated.
393 .TP
394 .B ON
395 Gives the day on which the rule takes effect.
396 Recognized forms include:
397 .nf
398 .in +2
399 .sp
400 .ta \w'Sun<=25\0\0'u
401 5 the fifth of the month
402 lastSun the last Sunday in the month
403 lastMon the last Monday in the month
404 Sun>=8 first Sunday on or after the eighth
405 Sun<=25 last Sunday on or before the 25th
406 .fi
407 .in
408 .sp
409 A weekday name (e.g.,
410 .BR "Sunday" )
411 or a weekday name preceded by
412 .q "last"
413 (e.g.,
414 .BR "lastSunday" )
415 may be abbreviated or spelled out in full.
416 There must be no white space characters within the
417 .B ON
418 field.
419 The
420 .q <=
421 and
422 .q >=
423 constructs can result in a day in the neighboring month;
424 for example, the IN-ON combination
425 .q "Oct Sun>=31"
426 stands for the first Sunday on or after October 31,
427 even if that Sunday occurs in November.
428 .TP
429 .B AT
430 Gives the time of day at which the rule takes effect,
431 relative to 00:00, the start of a calendar day.
432 Recognized forms include:
433 .nf
434 .in +2
435 .sp
436 .ta \w'00:19:32.13\0\0'u
437 2 time in hours
438 2:00 time in hours and minutes
439 01:28:14 time in hours, minutes, and seconds
440 00:19:32.13 time with fractional seconds
441 12:00 midday, 12 hours after 00:00
442 15:00 3 PM, 15 hours after 00:00
443 24:00 end of day, 24 hours after 00:00
444 260:00 260 hours after 00:00
445 \*-2:30 2.5 hours before 00:00
446 \*- equivalent to 0
447 .fi
448 .in
449 .sp
450 Although
451 .B zic
452 rounds times to the nearest integer second
453 (breaking ties to the even integer), the fractions may be useful
454 to other applications requiring greater precision.
455 The source format does not specify any maximum precision.
456 Any of these forms may be followed by the letter
457 .B w
458 if the given time is local or
459 .q "wall clock"
460 time,
461 .B s
462 if the given time is standard time without any adjustment for daylight saving,
463 or
464 .B u
465 (or
466 .B g
467 or
468 .BR z )
469 if the given time is universal time;
470 in the absence of an indicator,
471 local (wall clock) time is assumed.
472 These forms ignore leap seconds; for example,
473 if a leap second occurs at 00:59:60 local time,
474 .q "1:00"
475 stands for 3601 seconds after local midnight instead of the usual 3600 seconds.
476 The intent is that a rule line describes the instants when a
477 clock/calendar set to the type of time specified in the
478 .B AT
479 field would show the specified date and time of day.
480 .TP
481 .B SAVE
482 Gives the amount of time to be added to local standard time when the rule is in
483 effect, and whether the resulting time is standard or daylight saving.
484 This field has the same format as the
485 .B AT
486 field
487 except with a different set of suffix letters:
488 .B s
489 for standard time and
490 .B d
491 for daylight saving time.
492 The suffix letter is typically omitted, and defaults to
493 .B s
494 if the offset is zero and to
495 .B d
496 otherwise.
497 Negative offsets are allowed; in Ireland, for example, daylight saving
498 time is observed in winter and has a negative offset relative to
499 Irish Standard Time.
500 The offset is merely added to standard time; for example,
501 .B zic
502 does not distinguish a 10:30 standard time plus an 0:30
503 .B SAVE
504 from a 10:00 standard time plus a 1:00
505 .BR SAVE .
506 .TP
507 .B LETTER/S
508 Gives the
509 .q "variable part"
510 (for example, the
511 .q "S"
512 or
513 .q "D"
514 in
515 .q "EST"
516 or
517 .q "EDT" )
518 of time zone abbreviations to be used when this rule is in effect.
519 If this field is
520 .q \*- ,
521 the variable part is null.
522 .PP
523 A zone line has the form
524 .sp
525 .nf
526 .ti +2
527 .ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u
528 Zone NAME STDOFF RULES FORMAT [UNTIL]
529 .sp
530 For example:
531 .sp
532 .ti +2
533 Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00
534 .sp
535 .fi
536 The fields that make up a zone line are:
537 .TP
538 .B NAME
539 The name of the timezone.
540 This is the name used in creating the time conversion information file for the
541 timezone.
542 It should not contain a file name component
543 .q ".\&"
544 or
545 .q ".." ;
546 a file name component is a maximal substring that does not contain
547 .q "/" .
548 .TP
549 .B STDOFF
550 The amount of time to add to UT to get standard time,
551 without any adjustment for daylight saving.
552 This field has the same format as the
553 .B AT
554 and
555 .B SAVE
556 fields of rule lines, except without suffix letters;
557 begin the field with a minus sign if time must be subtracted from UT.
558 .TP
559 .B RULES
560 The name of the rules that apply in the timezone or,
561 alternatively, a field in the same format as a rule-line SAVE column,
562 giving the amount of time to be added to local standard time
563 and whether the resulting time is standard or daylight saving.
564 If this field is
565 .B \*-
566 then standard time always applies.
567 When an amount of time is given, only the sum of standard time and
568 this amount matters.
569 .TP
570 .B FORMAT
571 The format for time zone abbreviations.
572 The pair of characters
573 .B %s
574 is used to show where the
575 .q "variable part"
576 of the time zone abbreviation goes.
577 Alternatively, a format can use the pair of characters
578 .B %z
579 to stand for the UT offset in the form
580 .RI \(+- hh ,
581 .RI \(+- hhmm ,
582 or
583 .RI \(+- hhmmss ,
584 using the shortest form that does not lose information, where
585 .IR hh ,
586 .IR mm ,
587 and
588 .I ss
589 are the hours, minutes, and seconds east (+) or west (\-) of UT.
590 Alternatively,
591 a slash (/)
592 separates standard and daylight abbreviations.
593 To conform to POSIX, a time zone abbreviation should contain only
594 alphanumeric ASCII characters,
595 .q "+"
596 and
597 .q "\*-".
598 By convention, the time zone abbreviation
599 .q "\*-00"
600 is a placeholder that means local time is unspecified.
601 .TP
602 .B UNTIL
603 The time at which the UT offset or the rule(s) change for a location.
604 It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]].
605 If this is specified,
606 the time zone information is generated from the given UT offset
607 and rule change until the time specified, which is interpreted using
608 the rules in effect just before the transition.
609 The month, day, and time of day have the same format as the IN, ON, and AT
610 fields of a rule; trailing fields can be omitted, and default to the
611 earliest possible value for the missing fields.
612 .IP
613 The next line must be a
614 .q "continuation"
615 line; this has the same form as a zone line except that the
616 string
617 .q "Zone"
618 and the name are omitted, as the continuation line will
619 place information starting at the time specified as the
620 .q "until"
621 information in the previous line in the file used by the previous line.
622 Continuation lines may contain
623 .q "until"
624 information, just as zone lines do, indicating that the next line is a further
625 continuation.
626 .PP
627 If a zone changes at the same instant that a rule would otherwise take
628 effect in the earlier zone or continuation line, the rule is ignored.
629 A zone or continuation line
630 .I L
631 with a named rule set starts with standard time by default:
632 that is, any of
633 .IR L 's
634 timestamps preceding
635 .IR L 's
636 earliest rule use the rule in effect after
637 .IR L 's
638 first transition into standard time.
639 In a single zone it is an error if two rules take effect at the same
640 instant, or if two zone changes take effect at the same instant.
641 .PP
642 If a continuation line subtracts
643 .I N
644 seconds from the UT offset after a transition that would be
645 interpreted to be later if using the continuation line's UT offset and
646 rules, the
647 .q "until"
648 time of the previous zone or continuation line is interpreted
649 according to the continuation line's UT offset and rules, and any rule
650 that would otherwise take effect in the next
651 .I N
652 seconds is instead assumed to take effect simultaneously.
653 For example:
654 .br
655 .ne 7
656 .nf
657 .in +2
658 .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
659 .sp
660 # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S
661 Rule US 1967 2006 - Oct lastSun 2:00 0 S
662 Rule US 1967 1973 - Apr lastSun 2:00 1:00 D
663 .ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u
664 # Zone NAME STDOFF RULES FORMAT [UNTIL]
665 Zone America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00
666 \*-6:00 US C%sT
667 .sp
668 .in
669 .fi
670 Here, an incorrect reading would be there were two clock changes on 1973-04-29,
671 the first from 02:00 EST (\*-05) to 01:00 CST (\*-06),
672 and the second an hour later from 02:00 CST (\*-06) to 03:00 CDT (\*-05).
673 However,
674 .B zic
675 interprets this more sensibly as a single transition from 02:00 CST (\*-05) to
676 02:00 CDT (\*-05).
677 .PP
678 A link line has the form
679 .sp
680 .nf
681 .ti +2
682 .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u
683 Link TARGET LINK-NAME
684 .sp
685 For example:
686 .sp
687 .ti +2
688 Link Europe/Istanbul Asia/Istanbul
689 .sp
690 .fi
691 The
692 .B TARGET
693 field should appear as the
694 .B NAME
695 field in some zone line or as the
696 .B LINK-NAME
697 field in some link line.
698 The
699 .B LINK-NAME
700 field is used as an alternative name for that zone;
701 it has the same syntax as a zone line's
702 .B NAME
703 field.
704 Links can chain together, although the behavior is unspecified if a
705 chain of one or more links does not terminate in a Zone name.
706 A link line can appear before the line that defines the link target.
707 For example:
708 .sp
709 .ne 3
710 .nf
711 .in +2
712 .ta \w'Zone\0\0'u +\w'Greenwich\0\0'u
713 Link Greenwich G_M_T
714 Link Etc/GMT Greenwich
715 Zone Etc/GMT\0\00\0\0\*-\0\0GMT
716 .sp
717 .in
718 .fi
719 The two links are chained together, and G_M_T, Greenwich, and Etc/GMT
720 all name the same zone.
721 .PP
722 Except for continuation lines,
723 lines may appear in any order in the input.
724 However, the behavior is unspecified if multiple zone or link lines
725 define the same name.
726 .PP
727 The file that describes leap seconds can have leap lines and an
728 expiration line.
729 Leap lines have the following form:
730 .nf
731 .ti +2
732 .ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u
733 .sp
734 Leap YEAR MONTH DAY HH:MM:SS CORR R/S
735 .sp
736 For example:
737 .ti +2
738 .sp
739 Leap 2016 Dec 31 23:59:60 + S
740 .sp
741 .fi
742 The
743 .BR YEAR ,
744 .BR MONTH ,
745 .BR DAY ,
746 and
747 .B HH:MM:SS
748 fields tell when the leap second happened.
749 The
750 .B CORR
751 field
752 should be
753 .q "+"
754 if a second was added
755 or
756 .q "\*-"
757 if a second was skipped.
758 The
759 .B R/S
760 field
761 should be (an abbreviation of)
762 .q "Stationary"
763 if the leap second time given by the other fields should be interpreted as UTC
764 or
765 (an abbreviation of)
766 .q "Rolling"
767 if the leap second time given by the other fields should be interpreted as
768 local (wall clock) time.
769 .PP
770 Rolling leap seconds were implemented back when it was not
771 clear whether common practice was rolling or stationary,
772 with concerns that one would see
773 Times Square ball drops where there'd be a
774 .q "3... 2... 1... leap... Happy New Year"
775 countdown, placing the leap second at
776 midnight New York time rather than midnight UTC.
777 However, this countdown style does not seem to have caught on,
778 which means rolling leap seconds are not used in practice;
779 also, they are not supported if the
780 .B \*-r
781 option is used.
782 .PP
783 The expiration line, if present, has the form:
784 .nf
785 .ti +2
786 .ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u
787 .sp
788 Expires YEAR MONTH DAY HH:MM:SS
789 .sp
790 For example:
791 .ti +2
792 .sp
793 Expires 2020 Dec 28 00:00:00
794 .sp
795 .fi
796 The
797 .BR YEAR ,
798 .BR MONTH ,
799 .BR DAY ,
800 and
801 .B HH:MM:SS
802 fields give the expiration timestamp in UTC for the leap second table.
803 .br
804 .ne 22
805 .SH "EXTENDED EXAMPLE"
806 Here is an extended example of
807 .B zic
808 input, intended to illustrate many of its features.
809 .nf
810 .in +2
811 .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
812 .sp
813 # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S
814 Rule Swiss 1941 1942 \*- May Mon>=1 1:00 1:00 S
815 Rule Swiss 1941 1942 \*- Oct Mon>=1 2:00 0 \*-
816 .sp .5
817 Rule EU 1977 1980 \*- Apr Sun>=1 1:00u 1:00 S
818 Rule EU 1977 only \*- Sep lastSun 1:00u 0 \*-
819 Rule EU 1978 only \*- Oct 1 1:00u 0 \*-
820 Rule EU 1979 1995 \*- Sep lastSun 1:00u 0 \*-
821 Rule EU 1981 max \*- Mar lastSun 1:00u 1:00 S
822 Rule EU 1996 max \*- Oct lastSun 1:00u 0 \*-
823 .sp
824 .ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:29:45.50\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u
825 # Zone NAME STDOFF RULES FORMAT [UNTIL]
826 Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16
827 0:29:45.50 \*- BMT 1894 Jun
828 1:00 Swiss CE%sT 1981
829 1:00 EU CE%sT
830 .sp
831 Link Europe/Zurich Europe/Vaduz
832 .sp
833 .in
834 .fi
835 In this example, the EU rules are for the European Union
836 and for its predecessor organization, the European Communities.
837 The timezone is named Europe/Zurich and it has the alias Europe/Vaduz.
838 This example says that Zurich was 34 minutes and 8
839 seconds east of UT until 1853-07-16 at 00:00, when the legal offset
840 was changed to
841 7\*d\*_26\*m\*_22.50\*s,
842 which works out to 0:29:45.50;
843 .B zic
844 treats this by rounding it to 0:29:46.
845 After 1894-06-01 at 00:00 the UT offset became one hour
846 and Swiss daylight saving rules (defined with lines beginning with
847 .q "Rule Swiss")
848 apply. From 1981 to the present, EU daylight saving rules have
849 applied, and the UTC offset has remained at one hour.
850 .PP
851 In 1941 and 1942, daylight saving time applied from the first Monday
852 in May at 01:00 to the first Monday in October at 02:00.
853 The pre-1981 EU daylight-saving rules have no effect
854 here, but are included for completeness. Since 1981, daylight
855 saving has begun on the last Sunday in March at 01:00 UTC.
856 Until 1995 it ended the last Sunday in September at 01:00 UTC,
857 but this changed to the last Sunday in October starting in 1996.
858 .PP
859 For purposes of display,
860 .q "LMT"
861 and
862 .q "BMT"
863 were initially used, respectively. Since
864 Swiss rules and later EU rules were applied, the time zone abbreviation
865 has been CET for standard time and CEST for daylight saving
866 time.
867 .SH FILES
868 .TP
869 .I /etc/localtime
870 Default local timezone file.
871 .TP
872 .I /usr/share/zoneinfo
873 Default timezone information directory.
874 .SH NOTES
875 For areas with more than two types of local time,
876 you may need to use local standard time in the
877 .B AT
878 field of the earliest transition time's rule to ensure that
879 the earliest transition time recorded in the compiled file is correct.
880 .PP
881 If,
882 for a particular timezone,
883 a clock advance caused by the start of daylight saving
884 coincides with and is equal to
885 a clock retreat caused by a change in UT offset,
886 .B zic
887 produces a single transition to daylight saving at the new UT offset
888 without any change in local (wall clock) time.
889 To get separate transitions
890 use multiple zone continuation lines
891 specifying transition instants using universal time.
892 .SH SEE ALSO
893 .BR tzfile (5),
894 .BR zdump (8)