| blob | 851b47d6ed935569bd26d68c454e0d9e81e7c4b0 |
1 .\" $NetBSD: zic.8,v 1.21 2013/09/20 19:06:54 christos Exp $
2 .Dd September 20, 2013
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 data 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 .El
84 .It Fl y Ar command
85 Use the given
86 .Ar command
87 rather than
88 .Em yearistype
89 when checking year types (see below).
90 .Pp
91 Input lines are made up of fields.
92 Fields are separated from one another by one or more white space characters.
93 Leading and trailing white space on input lines is ignored.
94 An unquoted sharp character (#) in the input introduces a comment which extends
95 to the end of the line the sharp character appears on.
96 White space characters and sharp characters may be enclosed in double
97 quotes
98 .Pq \&"
99 .\" XXX "
100 if they're to be used as part of a field.
101 Any line that is blank (after comment stripping) is ignored.
102 Non-blank lines are expected to be of one of three types:
103 rule lines, zone lines, and link lines.
104 .Pp
105 Names (such as month names) must be in English and are case insensitive.
106 Abbreviations, if used, must be unambiguous in context.
107 .Pp
108 A rule line has the form
109 .Dl Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
110 For example:
111 .Dl Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D
112 The fields that make up a rule line are:
113 .Bl -tag -width "LETTER/S" -compact
114 .It NAME
115 Gives the (arbitrary) name of the set of rules this rule is part of.
116 .It FROM
117 Gives the first year in which the rule applies.
118 Any integer year can be supplied; the Gregorian calendar is assumed.
119 The word
120 .Em minimum
121 (or an abbreviation) means the minimum year representable as an integer.
122 The word
123 .Em maximum
124 (or an abbreviation) means the maximum year representable as an integer.
125 Rules can describe times that are not representable as time values,
126 with the unrepresentable times ignored; this allows rules to be portable
127 among hosts with differing time value types.
128 .It TO
129 Gives the final year in which the rule applies.
130 In addition to
131 .Em minimum
132 and
133 .Em maximum
134 (as above),
135 the word
136 .Em only
137 (or an abbreviation)
138 may be used to repeat the value of the
139 .Em FROM
140 field.
141 .It TYPE
142 Gives the type of year in which the rule applies.
143 If
144 .Em TYPE
145 is
146 .Em \&-
147 then the rule applies in all years between
148 .Em FROM
149 and
150 .Em TO
151 inclusive.
152 If
153 .Em TYPE
154 is something else, then
155 .Nm
156 executes the command
157 .Pp
158 .Ic yearistype Ar year type
159 .Pp
160 to check the type of a year:
161 an exit status of zero is taken to mean that the year is of the given type;
162 an exit status of one is taken to mean that the year is not of the given type.
163 .It IN
164 Names the month in which the rule takes effect.
165 Month names may be abbreviated.
166 .It ON
167 Gives the day on which the rule takes effect.
168 Recognized forms include:
169 .Bl -tag -width lastSun -compact -offset indent
170 .It 5
171 the fifth of the month
172 .It lastSun
173 the last Sunday in the month
174 .It lastMon
175 the last Monday in the month
176 .It Sun\*[Ge]8
177 first Sunday on or after the eighth
178 .It Sun\*[Le]25
179 last Sunday on or before the 25th
180 .El
181 Names of days of the week may be abbreviated or spelled out in full.
182 Note that there must be no spaces within the
183 .Em ON
184 field.
185 .It AT
186 Gives the time of day at which the rule takes effect.
187 Recognized forms include:
188 .Bl -tag -width "1X28X14" -compact -offset indent
189 .It 2
190 time in hours
191 .It 2:00
192 time in hours and minutes
193 .It 15:00
194 24-hour format time (for times after noon)
195 .It 1:28:14
196 time in hours, minutes, and seconds
197 .It \-
198 equivalent to 0
199 .El
200 where hour 0 is midnight at the start of the day,
201 and hour 24 is midnight at the end of the day.
202 Any of these forms may be followed by the letter
203 .Em w
204 if the given time is local
205 .Dq wall clock
206 time,
207 .Em s
208 if the given time is local
209 .Dq standard
210 time, or
211 .Em u
212 (or
213 .Em g
214 or
215 .Em z )
216 if the given time is universal time;
217 in the absence of an indicator,
218 wall clock time is assumed.
219 .It SAVE
220 Gives the amount of time to be added to local standard time when the rule is in
221 effect.
222 This field has the same format as the
223 .Em AT
224 field
225 (although, of course, the
226 .Em w
227 and
228 .Em s
229 suffixes are not used).
230 .It LETTER/S
231 Gives the
232 .Dq variable part
233 (for example, the
234 .Dq S
235 or
236 .Dq D
237 in
238 .Dq EST
239 or
240 .Dq EDT )
241 of time zone abbreviations to be used when this rule is in effect.
242 If this field is
243 .Em \&- ,
244 the variable part is null.
245 .El
246 .Pp
247 A zone line has the form
248 .sp
249 .Dl Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]]
250 For example:
251 .Dl Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00
252 The fields that make up a zone line are:
253 .Bl -tag -width "RULES/SAVE" -compact
254 .It NAME
255 The name of the time zone.
256 This is the name used in creating the time conversion information file for the
257 zone.
258 .It GMTOFF
259 The amount of time to add to UT to get standard time in this zone.
260 This field has the same format as the
261 .Em AT
262 and
263 .Em SAVE
264 fields of rule lines;
265 begin the field with a minus sign if time must be subtracted from UT.
266 .It RULES/SAVE
267 The name of the rule(s) that apply in the time zone or,
268 alternatively, an amount of time to add to local standard time.
269 If this field is
270 .Em \&-
271 then standard time always applies in the time zone.
272 .It FORMAT
273 The format for time zone abbreviations in this time zone.
274 The pair of characters
275 .Em %s
276 is used to show where the
277 .Dq variable part
278 of the time zone abbreviation goes.
279 Alternatively,
280 a slash
281 .Pq \&/
282 separates standard and daylight abbreviations.
283 .It UNTILYEAR [MONTH [DAY [TIME]]]
284 The time at which the UT offset or the rule(s) change for a location.
285 It is specified as a year, a month, a day, and a time of day.
286 If this is specified,
287 the time zone information is generated from the given UT offset
288 and rule change until the time specified.
289 The month, day, and time of day have the same format as the IN, ON, and AT
290 fields of a rule; trailing fields can be omitted, and default to the
291 earliest possible value for the missing fields.
292 .El
293 The next line must be a
294 .Dq continuation
295 line; this has the same form as a zone line except that the
296 string
297 .Dq Zone
298 and the name are omitted, as the continuation line will
299 place information starting at the time specified as the
300 .Em until
301 information in the previous line in the file used by the previous line.
302 Continuation lines may contain
303 .Em until
304 information, just as zone lines do, indicating that the next line is a further
305 continuation.
306 .Pp
307 A link line has the form
308 .Dl Link LINK-FROM LINK-TO
309 For example:
310 .Dl Link Europe/Istanbul Asia/Istanbul
311 The
312 .Em LINK-FROM
313 field should appear as the
314 .Em NAME
315 field in some zone line;
316 the
317 .Em LINK-TO
318 field is used as an alternative name for that zone.
319 .Pp
320 Except for continuation lines,
321 lines may appear in any order in the input.
322 However, the behavior is unspecified if multiple zone or link lines
323 define the same name, or if the source of one link line is the target
324 of another.
325 .Pp
326 Lines in the file that describes leap seconds have the following form:
327 .Dl Leap YEAR MONTH DAY HH:MM:SS CORR R/S
328 For example:
329 .Dl Leap 1974 Dec 31 23:59:60 + S
330 The
331 .Em YEAR ,
332 .Em MONTH ,
333 .Em DAY ,
334 and
335 .Em HH:MM:SS
336 fields tell when the leap second happened.
337 The
338 .Em CORR
339 field
340 should be
341 .Dq \&+
342 if a second was added
343 or
344 .Dq \&-
345 if a second was skipped.
346 .\" There's no need to document the following, since it's impossible for more
347 .\" than one leap second to be inserted or deleted at a time.
348 .\" The C Standard is in error in suggesting the possibility.
349 .\" See Terry J Quinn, The BIPM and the accurate measure of time,
350 .\" Proc IEEE 79, 7 (July 1991), 894-905.
351 .\" or
352 .\" .Dq ++
353 .\" if two seconds were added
354 .\" or
355 .\" .Dq --
356 .\" if two seconds were skipped.
357 The
358 .Em R/S
359 field
360 should be (an abbreviation of)
361 .Dq Stationary
362 if the leap second time given by the other fields should be interpreted as UTC
363 or
364 (an abbreviation of)
365 .Dq Rolling
366 if the leap second time given by the other fields should be interpreted as
367 local wall clock time.
368 .El
369 .Sh EXTENDED EXAMPLE
370 Here is an extended example of
371 .Ic zic
372 input, intended to illustrate many of its features.
373 .Bl -column -compact "# Rule" "Swiss" "FROM" "1995" "TYPE" "Oct" "lastSun" "1:00u" "SAVE" "LETTER/S"
374 .It # Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
375 .It Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S
376 .It Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 -
377 .Pp
378 .It Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S
379 .It Rule EU 1977 only - Sep lastSun 1:00u 0 -
380 .It Rule EU 1978 only - Oct 1 1:00u 0 -
381 .It Rule EU 1979 1995 - Sep lastSun 1:00u 0 -
382 .It Rule EU 1981 max - Mar lastSun 1:00u 1:00 S
383 .It Rule EU 1996 max - Oct lastSun 1:00u 0 -
384 .El
385 .Pp
386 .Bl -column -compact "# Zone" "Europe/Zurich" "0:34:08" "RULES/SAVE" "FORMAT" "UNTIL"
387 .It # Zone NAME GMTOFF RULES/SAVE FORMAT UNTIL
388 .It Zone Europe/Zurich 0:34:08 - LMT 1853 Jul 16
389 .It 0:29:44 - BMT 1894 Jun
390 .It 1:00 Swiss CE%sT 1981
391 .It 1:00 EU CE%sT
392 .It Link Europe/Zurich Switzerland
393 .El
394 .Pp
395 In this example, the zone is named Europe/Zurich but it has an alias
396 as Switzerland.
397 This example says that Zurich was 34 minutes and 8
398 seconds west of UT until 1853-07-16 at 00:00, when the legal offset
399 was changed to 7\(de\|26\(fm\|22.50\(sd; although this works out to
400 0:29:45.50, the input format cannot represent fractional seconds so it
401 is rounded here.
402 After 1894-06-01 at 00:00 Swiss daylight saving rules
403 (defined with lines beginning with "Rule Swiss") apply, and the UT offset
404 became one hour.
405 From 1981 to the present, EU daylight saving rules have
406 applied, and the UTC offset has remained at one hour.
407 .Pp
408 In 1941 and 1942, daylight saving time applied from the first Monday
409 in May at 01:00 to the first Monday in October at 02:00.
410 The pre-1981 EU daylight-saving rules have no effect
411 here, but are included for completeness.
412 Since 1981, daylight
413 saving has begun on the last Sunday in March at 01:00 UTC.
414 Until 1995 it ended the last Sunday in September at 01:00 UTC,
415 but this changed to the last Sunday in October starting in 1996.
416 .Pp
417 For purposes of
418 display, "LMT" and "BMT" were initially used, respectively.
419 Since
420 Swiss rules and later EU rules were applied, the display name for the
421 timezone has been CET for standard time and CEST for daylight saving
422 time.
423 .Sh NOTES
424 For areas with more than two types of local time,
425 you may need to use local standard time in the
426 .Em AT
427 field of the earliest transition time's rule to ensure that
428 the earliest transition time recorded in the compiled file is correct.
429 .Pp
430 If,
431 for a particular zone,
432 a clock advance caused by the start of daylight saving
433 coincides with and is equal to
434 a clock retreat caused by a change in UT offset,
435 .Ic zic
436 produces a single transition to daylight saving at the new UT offset
437 (without any change in wall clock time).
438 To get separate transitions
439 use multiple zone continuation lines
440 specifying transition instants using universal time.
441 .Sh FILES
442 .Pa /usr/share/zoneinfo
443 - standard directory used for created files
444 .Sh SEE ALSO
445 .Xr ctime 3 ,
446 .Xr tzfile 5 ,
447 .Xr zdump 8
448 .\" @(#)zic.8 8.6
449 .\" This file is in the public domain, so clarified as of
450 .\" 2009-05-17 by Arthur David Olson.