| blob | e5e71f59e520c7c3103bea65e8e9e70c7849f5e9 |
1 .TH ZIC 8
2 .SH NAME
3 zic \- time zone compiler
4 .SH SYNOPSIS
5 .B zic
6 [
7 .I option
8 \&... ] [
9 .I filename
10 \&... ]
11 .SH DESCRIPTION
12 .ie '\(lq'' .ds lq \&"\"
13 .el .ds lq \(lq\"
14 .ie '\(rq'' .ds rq \&"\"
15 .el .ds rq \(rq\"
16 .de q
17 \\$3\*(lq\\$1\*(rq\\$2
18 ..
19 .ie '\(la'' .ds < <
20 .el .ds < \(la
21 .ie '\(ra'' .ds > >
22 .el .ds > \(ra
23 .ie \n(.g \{\
24 . ds : \:
25 . ds - \f(CW-\fP
26 .\}
27 .el \{\
28 . ds :
29 . ds - \-
30 .\}
31 .I Zic
32 reads text from the file(s) named on the command line
33 and creates the time conversion information files specified in this input.
34 If a
35 .I filename
36 is
37 .q "\*-" ,
38 the standard input is read.
39 .PP
40 These options are available:
41 .TP
42 .BI "\*-\*-version"
43 Output version information and exit.
44 .TP
45 .BI "\*-d " directory
46 Create time conversion information files in the named directory rather than
47 in the standard directory named below.
48 .TP
49 .BI "\*-l " timezone
50 Use the given time zone as local time.
51 .I Zic
52 will act as if the input contained a link line of the form
53 .sp
54 .ti +.5i
55 Link \fItimezone\fP localtime
56 .TP
57 .BI "\*-p " timezone
58 Use the given time zone's rules when handling POSIX-format
59 time zone environment variables.
60 .I Zic
61 will act as if the input contained a link line of the form
62 .sp
63 .ti +.5i
64 Link \fItimezone\fP posixrules
65 .TP
66 .BI "\*-L " leapsecondfilename
67 Read leap second information from the file with the given name.
68 If this option is not used,
69 no leap second information appears in output files.
70 .TP
71 .B \*-v
72 Be more verbose, and complain about the following situations:
73 .RS
74 .PP
75 The input specifies a link to a link.
76 .PP
77 A year that appears in a data file is outside the range
78 of years representable by
79 .IR time (2)
80 values.
81 .PP
82 A time of 24:00 or more appears in the input.
83 Pre-1998 versions of
84 .I zic
85 prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00.
86 .PP
87 A rule goes past the start or end of the month.
88 Pre-2004 versions of
89 .I zic
90 prohibit this.
91 .PP
92 The output file does not contain all the information about the
93 long-term future of a zone, because the future cannot be summarized as
94 an extended POSIX TZ string. For example, as of 2013 this problem
95 occurs for Iran's daylight-saving rules for the predicted future, as
96 these rules are based on the Iranian calendar, which cannot be
97 represented.
98 .PP
99 The output contains data that may not be handled properly by client
100 code designed for older
101 .I zic
102 output formats. These compatibility issues affect only time stamps
103 before 1970 or after the start of 2038.
104 .PP
105 A time zone abbreviation has fewer than 3 characters.
106 POSIX requires at least 3.
107 .PP
108 An output file name contains a byte that is not an ASCII letter,
109 .q "\*-" ,
110 .q "/" ,
111 or
112 .q "_" ;
113 or it contains a file name component that contains more than 14 bytes
114 or that starts with
115 .q "\*-" .
116 .RE
117 .TP
118 .B \*-s
119 Limit time values stored in output files to values that are the same
120 whether they're taken to be signed or unsigned.
121 You can use this option to generate SVVS-compatible files.
122 .PP
123 Input files should be text files, that is, they should be a series of
124 zero or more lines, each ending in a newline byte and containing at
125 most 511 bytes, and without any NUL bytes. The input text's encoding
126 is typically UTF-8 or ASCII; it should have a unibyte representation
127 for the POSIX Portable Character Set (PPCS)
128 \*<http://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
129 and the encoding's non-unibyte characters should consist entirely of
130 non-PPCS bytes. Non-PPCS characters typically occur only in comments:
131 although output file names and time zone abbreviations can contain
132 nearly any character, other software will work better if these are
133 limited to the restricted syntax described under the
134 .B \*-v
135 option.
136 .PP
137 Input lines are made up of fields.
138 Fields are separated from one another by one or more white space characters.
139 The white space characters are space, form feed, carriage return, newline,
140 tab, and vertical tab.
141 Leading and trailing white space on input lines is ignored.
142 An unquoted sharp character (#) in the input introduces a comment which extends
143 to the end of the line the sharp character appears on.
144 White space characters and sharp characters may be enclosed in double quotes
145 (") if they're to be used as part of a field.
146 Any line that is blank (after comment stripping) is ignored.
147 Non-blank lines are expected to be of one of three types:
148 rule lines, zone lines, and link lines.
149 .PP
150 Names (such as month names) must be in English and are case insensitive.
151 Abbreviations, if used, must be unambiguous in context.
152 .PP
153 A rule line has the form
154 .nf
155 .ti +.5i
156 .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
157 .sp
158 Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
159 .sp
160 For example:
161 .ti +.5i
162 .sp
163 Rule US 1967 1973 \*- Apr lastSun 2:00 1:00 D
164 .sp
165 .fi
166 The fields that make up a rule line are:
167 .TP "\w'LETTER/S'u"
168 .B NAME
169 Gives the (arbitrary) name of the set of rules this rule is part of.
170 .TP
171 .B FROM
172 Gives the first year in which the rule applies.
173 Any integer year can be supplied; the proleptic Gregorian calendar is assumed.
174 The word
175 .B minimum
176 (or an abbreviation) means the minimum year representable as an integer.
177 The word
178 .B maximum
179 (or an abbreviation) means the maximum year representable as an integer.
180 Rules can describe times that are not representable as time values,
181 with the unrepresentable times ignored; this allows rules to be portable
182 among hosts with differing time value types.
183 .TP
184 .B TO
185 Gives the final year in which the rule applies.
186 In addition to
187 .B minimum
188 and
189 .B maximum
190 (as above),
191 the word
192 .B only
193 (or an abbreviation)
194 may be used to repeat the value of the
195 .B FROM
196 field.
197 .TP
198 .B TYPE
199 should be
200 .q \*-
201 and is present for compatibility with older versions of
202 .I zic
203 in which it could contain year types.
204 .TP
205 .B IN
206 Names the month in which the rule takes effect.
207 Month names may be abbreviated.
208 .TP
209 .B ON
210 Gives the day on which the rule takes effect.
211 Recognized forms include:
212 .nf
213 .in +.5i
214 .sp
215 .ta \w'Sun<=25\0\0'u
216 5 the fifth of the month
217 lastSun the last Sunday in the month
218 lastMon the last Monday in the month
219 Sun>=8 first Sunday on or after the eighth
220 Sun<=25 last Sunday on or before the 25th
221 .fi
222 .in -.5i
223 .sp
224 Names of days of the week may be abbreviated or spelled out in full.
225 Note that there must be no spaces within the
226 .B ON
227 field.
228 .TP
229 .B AT
230 Gives the time of day at which the rule takes effect.
231 Recognized forms include:
232 .nf
233 .in +.5i
234 .sp
235 .ta \w'1:28:13\0\0'u
236 2 time in hours
237 2:00 time in hours and minutes
238 15:00 24-hour format time (for times after noon)
239 1:28:14 time in hours, minutes, and seconds
240 \*- equivalent to 0
241 .fi
242 .in -.5i
243 .sp
244 where hour 0 is midnight at the start of the day,
245 and hour 24 is midnight at the end of the day.
246 Any of these forms may be followed by the letter
247 .B w
248 if the given time is local
249 .q "wall clock"
250 time,
251 .B s
252 if the given time is local
253 .q "standard"
254 time, or
255 .B u
256 (or
257 .B g
258 or
259 .BR z )
260 if the given time is universal time;
261 in the absence of an indicator,
262 wall clock time is assumed.
263 The intent is that a rule line describes the instants when a
264 clock/calendar set to the type of time specified in the
265 .B AT
266 field would show the specified date and time of day.
267 .TP
268 .B SAVE
269 Gives the amount of time to be added to local standard time when the rule is in
270 effect.
271 This field has the same format as the
272 .B AT
273 field
274 (although, of course, the
275 .B w
276 and
277 .B s
278 suffixes are not used).
279 Only the sum of standard time and this amount matters; for example,
280 .I zic
281 does not distinguish a 10:30 standard time plus an 0:30
282 .B SAVE
283 from a 10:00 standard time plus a 1:00
284 .BR SAVE .
285 .TP
286 .B LETTER/S
287 Gives the
288 .q "variable part"
289 (for example, the
290 .q "S"
291 or
292 .q "D"
293 in
294 .q "EST"
295 or
296 .q "EDT" )
297 of time zone abbreviations to be used when this rule is in effect.
298 If this field is
299 .q \*- ,
300 the variable part is null.
301 .PP
302 A zone line has the form
303 .sp
304 .nf
305 .ti +.5i
306 .ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u
307 Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]]
308 .sp
309 For example:
310 .sp
311 .ti +.5i
312 Zone Australia/Adelaide 9:30 Aus AC%sT 1971 Oct 31 2:00
313 .sp
314 .fi
315 The fields that make up a zone line are:
316 .TP "\w'GMTOFF'u"
317 .B NAME
318 The name of the time zone.
319 This is the name used in creating the time conversion information file for the
320 zone.
321 It should not contain a file name component
322 .q ".\&"
323 or
324 .q ".." ;
325 a file name component is a maximal substring that does not contain
326 .q "/" .
327 .TP
328 .B GMTOFF
329 The amount of time to add to UT to get standard time in this zone.
330 This field has the same format as the
331 .B AT
332 and
333 .B SAVE
334 fields of rule lines;
335 begin the field with a minus sign if time must be subtracted from UT.
336 .TP
337 .B RULES/SAVE
338 The name of the rule(s) that apply in the time zone or,
339 alternately, an amount of time to add to local standard time.
340 If this field is
341 .B \*-
342 then standard time always applies in the time zone.
343 When an amount of time is given, only the sum of standard time and
344 this amount matters.
345 .TP
346 .B FORMAT
347 The format for time zone abbreviations in this time zone.
348 The pair of characters
349 .B %s
350 is used to show where the
351 .q "variable part"
352 of the time zone abbreviation goes.
353 Alternately, a format can use the pair of characters
354 .B %z
355 to stand for the UTC offset in the form
356 .RI \(+- hh ,
357 .RI \(+- hhmm ,
358 or
359 .RI \(+- hhmmss ,
360 using the shortest form that does not lose information, where
361 .IR hh ,
362 .IR mm ,
363 and
364 .I ss
365 are the hours, minutes, and seconds east (+) or west (\(mi) of UTC.
366 Alternately,
367 a slash (/)
368 separates standard and daylight abbreviations.
369 To conform to POSIX, a time zone abbreviation should contain only
370 alphanumeric ASCII characters, "+" and "\*-".
371 .TP
372 .B UNTILYEAR [MONTH [DAY [TIME]]]
373 The time at which the UT offset or the rule(s) change for a location.
374 It is specified as a year, a month, a day, and a time of day.
375 If this is specified,
376 the time zone information is generated from the given UT offset
377 and rule change until the time specified, which is interpreted using
378 the rules in effect just before the transition.
379 The month, day, and time of day have the same format as the IN, ON, and AT
380 fields of a rule; trailing fields can be omitted, and default to the
381 earliest possible value for the missing fields.
382 .IP
383 The next line must be a
384 .q "continuation"
385 line; this has the same form as a zone line except that the
386 string
387 .q "Zone"
388 and the name are omitted, as the continuation line will
389 place information starting at the time specified as the
390 .q "until"
391 information in the previous line in the file used by the previous line.
392 Continuation lines may contain
393 .q "until"
394 information, just as zone lines do, indicating that the next line is a further
395 continuation.
396 .PP
397 If a zone changes at the same instant that a rule would otherwise take
398 effect in the earlier zone or continuation line, the rule is ignored.
399 In a single zone it is an error if two rules take effect at the same
400 instant, or if two zone changes take effect at the same instant.
401 .PP
402 A link line has the form
403 .sp
404 .nf
405 .ti +.5i
406 .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u
407 Link TARGET LINK-NAME
408 .sp
409 For example:
410 .sp
411 .ti +.5i
412 Link Europe/Istanbul Asia/Istanbul
413 .sp
414 .fi
415 The
416 .B TARGET
417 field should appear as the
418 .B NAME
419 field in some zone line.
420 The
421 .B LINK-NAME
422 field is used as an alternate name for that zone;
423 it has the same syntax as a zone line's
424 .B NAME
425 field.
426 .PP
427 Except for continuation lines,
428 lines may appear in any order in the input.
429 However, the behavior is unspecified if multiple zone or link lines
430 define the same name, or if the source of one link line is the target
431 of another.
432 .PP
433 Lines in the file that describes leap seconds have the following form:
434 .nf
435 .ti +.5i
436 .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
437 .sp
438 Leap YEAR MONTH DAY HH:MM:SS CORR R/S
439 .sp
440 For example:
441 .ti +.5i
442 .sp
443 Leap 1974 Dec 31 23:59:60 + S
444 .sp
445 .fi
446 The
447 .BR YEAR ,
448 .BR MONTH ,
449 .BR DAY ,
450 and
451 .B HH:MM:SS
452 fields tell when the leap second happened.
453 The
454 .B CORR
455 field
456 should be
457 .q "+"
458 if a second was added
459 or
460 .q "\*-"
461 if a second was skipped.
462 .\" There's no need to document the following, since it's impossible for more
463 .\" than one leap second to be inserted or deleted at a time.
464 .\" The C Standard is in error in suggesting the possibility.
465 .\" See Terry J Quinn, The BIPM and the accurate measure of time,
466 .\" Proc IEEE 79, 7 (July 1991), 894-905.
467 .\" or
468 .\" .q ++
469 .\" if two seconds were added
470 .\" or
471 .\" .q --
472 .\" if two seconds were skipped.
473 The
474 .B R/S
475 field
476 should be (an abbreviation of)
477 .q "Stationary"
478 if the leap second time given by the other fields should be interpreted as UTC
479 or
480 (an abbreviation of)
481 .q "Rolling"
482 if the leap second time given by the other fields should be interpreted as
483 local wall clock time.
484 .SH "EXTENDED EXAMPLE"
485 Here is an extended example of
486 .I zic
487 input, intended to illustrate many of its features.
488 .br
489 .ne 22
490 .nf
491 .in +2m
492 .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
493 .sp
494 # Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
495 Rule Swiss 1941 1942 \*- May Mon>=1 1:00 1:00 S
496 Rule Swiss 1941 1942 \*- Oct Mon>=1 2:00 0 \*-
497 .sp .5
498 Rule EU 1977 1980 \*- Apr Sun>=1 1:00u 1:00 S
499 Rule EU 1977 only \*- Sep lastSun 1:00u 0 \*-
500 Rule EU 1978 only \*- Oct 1 1:00u 0 \*-
501 Rule EU 1979 1995 \*- Sep lastSun 1:00u 0 \*-
502 Rule EU 1981 max \*- Mar lastSun 1:00u 1:00 S
503 Rule EU 1996 max \*- Oct lastSun 1:00u 0 \*-
504 .sp
505 .ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u
506 # Zone NAME GMTOFF RULES/SAVE FORMAT UNTIL
507 Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16
508 0:29:46 \*- BMT 1894 Jun
509 1:00 Swiss CE%sT 1981
510 1:00 EU CE%sT
511 .sp
512 Link Europe/Zurich Switzerland
513 .sp
514 .in
515 .fi
516 In this example, the zone is named Europe/Zurich but it has an alias
517 as Switzerland. This example says that Zurich was 34 minutes and 8
518 seconds west of UT until 1853-07-16 at 00:00, when the legal offset
519 was changed to 7\(de\|26\(fm\|22.50\(sd; although this works out to
520 0:29:45.50, the input format cannot represent fractional seconds so it
521 is rounded here. After 1894-06-01 at 00:00 Swiss daylight saving rules
522 (defined with lines beginning with "Rule Swiss") apply, and the UT offset
523 became one hour. From 1981 to the present, EU daylight saving rules have
524 applied, and the UTC offset has remained at one hour.
525 .PP
526 In 1941 and 1942, daylight saving time applied from the first Monday
527 in May at 01:00 to the first Monday in October at 02:00.
528 The pre-1981 EU daylight-saving rules have no effect
529 here, but are included for completeness. Since 1981, daylight
530 saving has begun on the last Sunday in March at 01:00 UTC.
531 Until 1995 it ended the last Sunday in September at 01:00 UTC,
532 but this changed to the last Sunday in October starting in 1996.
533 .PP
534 For purposes of
535 display, "LMT" and "BMT" were initially used, respectively. Since
536 Swiss rules and later EU rules were applied, the display name for the
537 time zone has been CET for standard time and CEST for daylight saving
538 time.
539 .SH NOTES
540 For areas with more than two types of local time,
541 you may need to use local standard time in the
542 .B AT
543 field of the earliest transition time's rule to ensure that
544 the earliest transition time recorded in the compiled file is correct.
545 .PP
546 If,
547 for a particular zone,
548 a clock advance caused by the start of daylight saving
549 coincides with and is equal to
550 a clock retreat caused by a change in UT offset,
551 .IR zic
552 produces a single transition to daylight saving at the new UT offset
553 (without any change in wall clock time).
554 To get separate transitions
555 use multiple zone continuation lines
556 specifying transition instants using universal time.
557 .PP
558 Time stamps well before the Big Bang are silently omitted from the output.
559 This works around bugs in software that mishandles large negative time
560 stamps. Call it sour grapes, but pre-Big-Bang time stamps are
561 physically suspect anyway. The pre-Big-Bang cutoff time is
562 approximate and may change in future versions.
563 .SH FILE
564 /usr/local/etc/zoneinfo standard directory used for created files
565 .SH "SEE ALSO"
566 newctime(3), tzfile(5), zdump(8)
567 .\" This file is in the public domain, so clarified as of
568 .\" 2009-05-17 by Arthur David Olson.