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