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