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