Debian Codegraph @

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