]>
Commit | Line | Data |
---|---|---|
1349d7ca AC |
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" | |
fea681da | 4 | .SH NAME |
5b0dc1ba | 5 | zic \- timezone compiler |
fea681da | 6 | .SH SYNOPSIS |
5355e20f PE |
7 | .B zic |
8 | [ | |
9 | .I option | |
10 | \&... ] [ | |
11 | .I filename | |
12 | \&... ] | |
fea681da | 13 | .SH DESCRIPTION |
1349d7ca AC |
14 | .ie '\(lq'' .ds lq \&"\" |
15 | .el .ds lq \(lq\" | |
16 | .ie '\(rq'' .ds rq \&"\" | |
17 | .el .ds rq \(rq\" | |
fea681da MK |
18 | .de q |
19 | \\$3\*(lq\\$1\*(rq\\$2 | |
20 | .. | |
5355e20f PE |
21 | .ie '\(la'' .ds < < |
22 | .el .ds < \(la | |
23 | .ie '\(ra'' .ds > > | |
24 | .el .ds > \(ra | |
25 | .ie \n(.g \{\ | |
26 | . ds : \: | |
1349d7ca | 27 | . ds - \f(CR-\fP |
5355e20f PE |
28 | .\} |
29 | .el \{\ | |
30 | . ds : | |
31 | . ds - \- | |
32 | .\} | |
1349d7ca AC |
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 | .\} | |
fff3db33 MK |
45 | The |
46 | .B zic | |
47 | program reads text from the file(s) named on the command line | |
1349d7ca AC |
48 | and creates the timezone information format (TZif) files |
49 | specified in this input. | |
fea681da MK |
50 | If a |
51 | .I filename | |
52 | is | |
5355e20f | 53 | .q "\*-" , |
02af2073 | 54 | standard input is read. |
5355e20f | 55 | .SH OPTIONS |
fea681da | 56 | .TP |
5355e20f PE |
57 | .B "\*-\*-version" |
58 | Output version information and exit. | |
59 | .TP | |
60 | .B \*-\*-help | |
61 | Output short usage message and exit. | |
62 | .TP | |
24e14ed0 MK |
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. | |
1349d7ca AC |
79 | The default is |
80 | .BR slim , | |
81 | as software that mishandles 64-bit data typically | |
24e14ed0 MK |
82 | mishandles timestamps after the year 2038 anyway. |
83 | Also see the | |
84 | .B \*-r | |
1349d7ca | 85 | option for another way to alter output size. |
24e14ed0 | 86 | .TP |
5355e20f | 87 | .BI "\*-d " directory |
fea681da MK |
88 | Create time conversion information files in the named directory rather than |
89 | in the standard directory named below. | |
90 | .TP | |
5355e20f PE |
91 | .BI "\*-l " timezone |
92 | Use | |
93 | .I timezone | |
94 | as local time. | |
fff3db33 | 95 | .B zic |
fea681da | 96 | will act as if the input contained a link line of the form |
5355e20f | 97 | .sp |
79bd8a7a | 98 | .ti +2 |
24e14ed0 | 99 | .ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u |
fea681da | 100 | Link \fItimezone\fP localtime |
1349d7ca AC |
101 | .sp |
102 | If | |
103 | .I timezone | |
104 | is | |
105 | .BR \*- , | |
106 | any already-existing link is removed. | |
fea681da | 107 | .TP |
24e14ed0 MK |
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 | |
5355e20f PE |
113 | .BI "\*-p " timezone |
114 | Use | |
115 | .IR timezone 's | |
24e14ed0 MK |
116 | rules when handling nonstandard |
117 | TZ strings like "EET\*-2EEST" that lack transition rules. | |
fff3db33 | 118 | .B zic |
fea681da | 119 | will act as if the input contained a link line of the form |
5355e20f | 120 | .sp |
79bd8a7a | 121 | .ti +2 |
fea681da | 122 | Link \fItimezone\fP posixrules |
24e14ed0 | 123 | .sp |
79bd8a7a AC |
124 | If |
125 | .I timezone | |
126 | is | |
127 | .q "\*-" | |
128 | (the default), any already-existing link is removed. | |
129 | .sp | |
1349d7ca AC |
130 | Unless |
131 | .I timezone is | |
132 | .q "\*-" , | |
133 | this option is obsolete and poorly supported. | |
24e14ed0 MK |
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. | |
fea681da | 140 | .TP |
24e14ed0 | 141 | .BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]" |
1349d7ca | 142 | Limit the applicability of output files |
24e14ed0 MK |
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 | |
1349d7ca | 151 | are possibly signed decimal counts of seconds since the Epoch |
24e14ed0 MK |
152 | (1970-01-01 00:00:00 UTC). |
153 | Omitted counts default to extreme values. | |
1349d7ca AC |
154 | The output files use UT offset 0 and abbreviation |
155 | .q "\*-00" | |
156 | in place of the omitted timestamp data. | |
24e14ed0 MK |
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 , | |
1349d7ca | 165 | .q "zic \*-r @$(date +%s)" |
24e14ed0 | 166 | omits data intended for past timestamps. |
1349d7ca AC |
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 | |
79bd8a7a | 174 | with an extended POSIX.1-2017 TZ string. |
24e14ed0 MK |
175 | Also see the |
176 | .B "\*-b slim" | |
177 | option for another way to shrink output size. | |
178 | .TP | |
1349d7ca AC |
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 | |
79bd8a7a | 184 | more concisely represented via the extended POSIX.1-2017 TZ string. |
1349d7ca AC |
185 | This option does not affect the represented timestamps. |
186 | Although it accommodates nonstandard TZif readers | |
79bd8a7a | 187 | that ignore the extended POSIX.1-2017 TZ string, |
1349d7ca AC |
188 | it increases the size of the altered output files. |
189 | .TP | |
24e14ed0 MK |
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. | |
fea681da | 193 | .TP |
5355e20f PE |
194 | .B \*-v |
195 | Be more verbose, and complain about the following situations: | |
196 | .RS | |
79bd8a7a | 197 | .PP |
1349d7ca AC |
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. | |
79bd8a7a | 202 | .PP |
5355e20f | 203 | A year that appears in a data file is outside the range |
24e14ed0 | 204 | of representable years. |
79bd8a7a | 205 | .PP |
5355e20f PE |
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. | |
79bd8a7a | 210 | .PP |
5355e20f PE |
211 | A rule goes past the start or end of the month. |
212 | Pre-2004 versions of | |
213 | .B zic | |
214 | prohibit this. | |
79bd8a7a | 215 | .PP |
24e14ed0 MK |
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. | |
79bd8a7a | 222 | .PP |
24e14ed0 MK |
223 | A timestamp contains fractional seconds. |
224 | Pre-2018 versions of | |
225 | .B zic | |
226 | do not support this. | |
79bd8a7a | 227 | .PP |
24e14ed0 MK |
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 . | |
79bd8a7a | 245 | .PP |
5355e20f PE |
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 | |
79bd8a7a | 248 | an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem |
1349d7ca AC |
249 | occurs for Morocco's daylight-saving rules, as these rules are based |
250 | on predictions for when Ramadan will be observed, something that | |
79bd8a7a AC |
251 | an extended POSIX.1-2017 TZ string cannot represent. |
252 | .PP | |
5355e20f PE |
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. | |
79bd8a7a | 258 | .PP |
1349d7ca AC |
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. | |
79bd8a7a | 267 | .PP |
24e14ed0 MK |
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. | |
79bd8a7a | 273 | .PP |
24e14ed0 MK |
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. | |
79bd8a7a | 277 | .PP |
5355e20f PE |
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 | |
24e14ed0 MK |
287 | .SH FILES |
288 | Input files use the format described in this section; output files use | |
c8863be9 | 289 | .BR tzfile (5) |
24e14ed0 | 290 | format. |
79bd8a7a | 291 | .PP |
5355e20f PE |
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 | |
1349d7ca AC |
294 | most 2048 bytes counting the newline, and without any NUL bytes. |
295 | The input text's encoding | |
5355e20f PE |
296 | is typically UTF-8 or ASCII; it should have a unibyte representation |
297 | for the POSIX Portable Character Set (PPCS) | |
1349d7ca | 298 | \*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*> |
5355e20f PE |
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. | |
79bd8a7a | 306 | .PP |
fea681da | 307 | Input lines are made up of fields. |
5355e20f PE |
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. | |
fea681da MK |
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. | |
44732c9c | 317 | Nonblank lines are expected to be of one of three types: |
fea681da | 318 | rule lines, zone lines, and link lines. |
79bd8a7a | 319 | .PP |
5355e20f PE |
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. | |
79bd8a7a | 330 | .PP |
fea681da MK |
331 | A rule line has the form |
332 | .nf | |
79bd8a7a | 333 | .ti +2 |
1349d7ca | 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 |
5355e20f | 335 | .sp |
1349d7ca | 336 | Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S |
5355e20f | 337 | .sp |
fea681da | 338 | For example: |
79bd8a7a | 339 | .ti +2 |
5355e20f | 340 | .sp |
24e14ed0 | 341 | Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D |
5355e20f | 342 | .sp |
fea681da MK |
343 | .fi |
344 | The fields that make up a rule line are: | |
79bd8a7a | 345 | .TP |
fea681da | 346 | .B NAME |
5355e20f PE |
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 | |
1349d7ca AC |
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]^`{|}~ . | |
fea681da MK |
358 | .TP |
359 | .B FROM | |
360 | Gives the first year in which the rule applies. | |
5355e20f PE |
361 | Any signed integer year can be supplied; the proleptic Gregorian calendar |
362 | is assumed, with year 0 preceding year 1. | |
fea681da MK |
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. | |
79bd8a7a | 369 | The word |
5355e20f | 370 | .B maximum |
79bd8a7a | 371 | (or an abbreviation) means the indefinite future, and the word |
5355e20f | 372 | .B only |
fea681da MK |
373 | (or an abbreviation) |
374 | may be used to repeat the value of the | |
375 | .B FROM | |
376 | field. | |
377 | .TP | |
1349d7ca AC |
378 | .B \*- |
379 | Is a reserved field and should always contain | |
5355e20f | 380 | .q \*- |
1349d7ca AC |
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. | |
fea681da MK |
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 | |
79bd8a7a | 398 | .in +2 |
5355e20f | 399 | .sp |
fea681da MK |
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 | |
79bd8a7a | 407 | .in |
5355e20f PE |
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. | |
24e14ed0 | 416 | There must be no white space characters within the |
fea681da MK |
417 | .B ON |
418 | field. | |
24e14ed0 MK |
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. | |
fea681da MK |
428 | .TP |
429 | .B AT | |
24e14ed0 MK |
430 | Gives the time of day at which the rule takes effect, |
431 | relative to 00:00, the start of a calendar day. | |
fea681da MK |
432 | Recognized forms include: |
433 | .nf | |
79bd8a7a | 434 | .in +2 |
5355e20f PE |
435 | .sp |
436 | .ta \w'00:19:32.13\0\0'u | |
fea681da MK |
437 | 2 time in hours |
438 | 2:00 time in hours and minutes | |
5355e20f | 439 | 01:28:14 time in hours, minutes, and seconds |
24e14ed0 MK |
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 | |
5355e20f PE |
444 | 260:00 260 hours after 00:00 |
445 | \*-2:30 2.5 hours before 00:00 | |
446 | \*- equivalent to 0 | |
fea681da | 447 | .fi |
79bd8a7a | 448 | .in |
5355e20f | 449 | .sp |
24e14ed0 MK |
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. | |
fea681da | 456 | Any of these forms may be followed by the letter |
5355e20f | 457 | .B w |
24e14ed0 | 458 | if the given time is local or |
fea681da MK |
459 | .q "wall clock" |
460 | time, | |
5355e20f | 461 | .B s |
24e14ed0 MK |
462 | if the given time is standard time without any adjustment for daylight saving, |
463 | or | |
5355e20f | 464 | .B u |
fea681da | 465 | (or |
5355e20f | 466 | .B g |
fea681da | 467 | or |
5355e20f | 468 | .BR z ) |
fea681da MK |
469 | if the given time is universal time; |
470 | in the absence of an indicator, | |
24e14ed0 MK |
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. | |
5355e20f PE |
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. | |
fea681da MK |
480 | .TP |
481 | .B SAVE | |
482 | Gives the amount of time to be added to local standard time when the rule is in | |
24e14ed0 | 483 | effect, and whether the resulting time is standard or daylight saving. |
fea681da MK |
484 | This field has the same format as the |
485 | .B AT | |
486 | field | |
24e14ed0 | 487 | except with a different set of suffix letters: |
5355e20f | 488 | .B s |
24e14ed0 MK |
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. | |
5355e20f PE |
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 . | |
fea681da MK |
506 | .TP |
507 | .B LETTER/S | |
508 | Gives the | |
509 | .q "variable part" | |
510 | (for example, the | |
5355e20f | 511 | .q "S" |
fea681da | 512 | or |
5355e20f | 513 | .q "D" |
fea681da | 514 | in |
5355e20f | 515 | .q "EST" |
fea681da | 516 | or |
5355e20f PE |
517 | .q "EDT" ) |
518 | of time zone abbreviations to be used when this rule is in effect. | |
fea681da | 519 | If this field is |
5355e20f | 520 | .q \*- , |
fea681da | 521 | the variable part is null. |
79bd8a7a | 522 | .PP |
fea681da | 523 | A zone line has the form |
5355e20f | 524 | .sp |
fea681da | 525 | .nf |
79bd8a7a | 526 | .ti +2 |
24e14ed0 MK |
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] | |
5355e20f | 529 | .sp |
fea681da | 530 | For example: |
5355e20f | 531 | .sp |
79bd8a7a | 532 | .ti +2 |
5355e20f PE |
533 | Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 |
534 | .sp | |
fea681da MK |
535 | .fi |
536 | The fields that make up a zone line are: | |
79bd8a7a | 537 | .TP |
fea681da | 538 | .B NAME |
5b0dc1ba | 539 | The name of the timezone. |
fea681da | 540 | This is the name used in creating the time conversion information file for the |
5355e20f PE |
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 "/" . | |
fea681da | 548 | .TP |
24e14ed0 MK |
549 | .B STDOFF |
550 | The amount of time to add to UT to get standard time, | |
551 | without any adjustment for daylight saving. | |
fea681da MK |
552 | This field has the same format as the |
553 | .B AT | |
554 | and | |
555 | .B SAVE | |
1349d7ca | 556 | fields of rule lines, except without suffix letters; |
5355e20f | 557 | begin the field with a minus sign if time must be subtracted from UT. |
fea681da | 558 | .TP |
5355e20f PE |
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, | |
1349d7ca AC |
562 | giving the amount of time to be added to local standard time |
563 | and whether the resulting time is standard or daylight saving. | |
fea681da | 564 | If this field is |
5355e20f PE |
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. | |
fea681da MK |
569 | .TP |
570 | .B FORMAT | |
5355e20f | 571 | The format for time zone abbreviations. |
fea681da MK |
572 | The pair of characters |
573 | .B %s | |
574 | is used to show where the | |
575 | .q "variable part" | |
5355e20f PE |
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 | |
1349d7ca | 589 | are the hours, minutes, and seconds east (+) or west (\-) of UT. |
5355e20f | 590 | Alternatively, |
fea681da MK |
591 | a slash (/) |
592 | separates standard and daylight abbreviations. | |
5355e20f PE |
593 | To conform to POSIX, a time zone abbreviation should contain only |
594 | alphanumeric ASCII characters, | |
595 | .q "+" | |
596 | and | |
597 | .q "\*-". | |
1349d7ca AC |
598 | By convention, the time zone abbreviation |
599 | .q "\*-00" | |
600 | is a placeholder that means local time is unspecified. | |
fea681da MK |
601 | .TP |
602 | .B UNTIL | |
5355e20f | 603 | The time at which the UT offset or the rule(s) change for a location. |
24e14ed0 | 604 | It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]]. |
fea681da | 605 | If this is specified, |
5355e20f PE |
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. | |
fea681da | 609 | The month, day, and time of day have the same format as the IN, ON, and AT |
5355e20f PE |
610 | fields of a rule; trailing fields can be omitted, and default to the |
611 | earliest possible value for the missing fields. | |
fea681da MK |
612 | .IP |
613 | The next line must be a | |
5355e20f | 614 | .q "continuation" |
fea681da MK |
615 | line; this has the same form as a zone line except that the |
616 | string | |
5355e20f | 617 | .q "Zone" |
fea681da MK |
618 | and the name are omitted, as the continuation line will |
619 | place information starting at the time specified as the | |
5355e20f PE |
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 | |
fea681da | 625 | continuation. |
79bd8a7a | 626 | .PP |
5355e20f PE |
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. | |
24e14ed0 MK |
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. | |
5355e20f PE |
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. | |
79bd8a7a | 641 | .PP |
1349d7ca AC |
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 | |
79bd8a7a | 657 | .in +2 |
1349d7ca AC |
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 | |
79bd8a7a AC |
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 | |
1349d7ca AC |
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). | |
79bd8a7a | 677 | .PP |
5355e20f PE |
678 | A link line has the form |
679 | .sp | |
fea681da | 680 | .nf |
79bd8a7a | 681 | .ti +2 |
fea681da | 682 | .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u |
5355e20f PE |
683 | Link TARGET LINK-NAME |
684 | .sp | |
fea681da | 685 | For example: |
5355e20f | 686 | .sp |
79bd8a7a | 687 | .ti +2 |
fea681da | 688 | Link Europe/Istanbul Asia/Istanbul |
5355e20f | 689 | .sp |
fea681da MK |
690 | .fi |
691 | The | |
5355e20f | 692 | .B TARGET |
fea681da MK |
693 | field should appear as the |
694 | .B NAME | |
1349d7ca AC |
695 | field in some zone line or as the |
696 | .B LINK-NAME | |
697 | field in some link line. | |
5355e20f PE |
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. | |
1349d7ca AC |
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 | |
79bd8a7a | 711 | .in +2 |
1349d7ca AC |
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. | |
79bd8a7a | 721 | .PP |
fea681da MK |
722 | Except for continuation lines, |
723 | lines may appear in any order in the input. | |
5355e20f | 724 | However, the behavior is unspecified if multiple zone or link lines |
1349d7ca | 725 | define the same name. |
79bd8a7a | 726 | .PP |
24e14ed0 MK |
727 | The file that describes leap seconds can have leap lines and an |
728 | expiration line. | |
729 | Leap lines have the following form: | |
fea681da | 730 | .nf |
79bd8a7a | 731 | .ti +2 |
fea681da | 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 |
5355e20f | 733 | .sp |
fea681da | 734 | Leap YEAR MONTH DAY HH:MM:SS CORR R/S |
5355e20f | 735 | .sp |
fea681da | 736 | For example: |
79bd8a7a | 737 | .ti +2 |
5355e20f PE |
738 | .sp |
739 | Leap 2016 Dec 31 23:59:60 + S | |
740 | .sp | |
fea681da MK |
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 | |
5355e20f | 753 | .q "+" |
fea681da MK |
754 | if a second was added |
755 | or | |
5355e20f | 756 | .q "\*-" |
fea681da | 757 | if a second was skipped. |
fea681da MK |
758 | The |
759 | .B R/S | |
760 | field | |
761 | should be (an abbreviation of) | |
5355e20f | 762 | .q "Stationary" |
fea681da MK |
763 | if the leap second time given by the other fields should be interpreted as UTC |
764 | or | |
765 | (an abbreviation of) | |
5355e20f | 766 | .q "Rolling" |
fea681da | 767 | if the leap second time given by the other fields should be interpreted as |
24e14ed0 | 768 | local (wall clock) time. |
79bd8a7a | 769 | .PP |
1349d7ca AC |
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. | |
79bd8a7a | 782 | .PP |
24e14ed0 MK |
783 | The expiration line, if present, has the form: |
784 | .nf | |
79bd8a7a | 785 | .ti +2 |
24e14ed0 MK |
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: | |
79bd8a7a | 791 | .ti +2 |
24e14ed0 MK |
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 | |
1349d7ca AC |
802 | fields give the expiration timestamp in UTC for the leap second table. |
803 | .br | |
804 | .ne 22 | |
5355e20f PE |
805 | .SH "EXTENDED EXAMPLE" |
806 | Here is an extended example of | |
807 | .B zic | |
808 | input, intended to illustrate many of its features. | |
5355e20f | 809 | .nf |
79bd8a7a | 810 | .in +2 |
1349d7ca | 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 |
5355e20f | 812 | .sp |
1349d7ca | 813 | # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S |
5355e20f PE |
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 | |
24e14ed0 MK |
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] | |
5355e20f | 826 | Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16 |
24e14ed0 | 827 | 0:29:45.50 \*- BMT 1894 Jun |
5355e20f PE |
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 | |
1349d7ca AC |
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 | |
5355e20f | 839 | seconds east of UT until 1853-07-16 at 00:00, when the legal offset |
24e14ed0 | 840 | was changed to |
1349d7ca | 841 | 7\*d\*_26\*m\*_22.50\*s, |
24e14ed0 MK |
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 | |
5355e20f PE |
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. | |
79bd8a7a | 850 | .PP |
5355e20f PE |
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. | |
79bd8a7a | 858 | .PP |
5355e20f PE |
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. | |
2b2581ee | 867 | .SH FILES |
ef43b7cd | 868 | .TP |
5355e20f PE |
869 | .I /etc/localtime |
870 | Default local timezone file. | |
871 | .TP | |
872 | .I /usr/share/zoneinfo | |
873 | Default timezone information directory. | |
19c98696 | 874 | .SH NOTES |
fea681da MK |
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. | |
79bd8a7a | 880 | .PP |
5355e20f PE |
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 | |
24e14ed0 | 888 | without any change in local (wall clock) time. |
5355e20f PE |
889 | To get separate transitions |
890 | use multiple zone continuation lines | |
891 | specifying transition instants using universal time. | |
47297adb | 892 | .SH SEE ALSO |
ad4fa959 MK |
893 | .BR tzfile (5), |
894 | .BR zdump (8) |