| blob | daf6d58403e8920655b56b70663d7103c2913143 |
1 .\" $FreeBSD: src/usr.sbin/zic/zic.8,v 1.11.2.4 2003/03/11 22:31:35 trhodes Exp $
2 .Dd March 22, 2016
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 To conform to POSIX, a time zone abbreviation should contain only
334 alphanumeric ASCII characters,
335 .Dq +
336 and
337 .Dq - .
338 .It UNTILYEAR [MONTH [DAY [TIME]]]
339 The time at which the UT offset or the rule(s) change for a location.
340 It is specified as a year, a month, a day, and a time of day.
341 If this is specified,
342 the time zone information is generated from the given UT offset
343 and rule change until the time specified.
344 The month, day, and time of day have the same format as the IN, ON, and AT
345 fields of a rule; trailing fields can be omitted, and default to the
346 earliest possible value for the missing fields.
347 .Pp
348 The next line must be a
349 .Dq continuation
350 line; this has the same form as a zone line except that the
351 string
352 .Dq Zone
353 and the name are omitted, as the continuation line will
354 place information starting at the time specified as the
355 .Dq until
356 information in the previous line in the file used by the previous line.
357 Continuation lines may contain
358 .Dq until
359 information, just as zone lines do, indicating that the next line is a further
360 continuation.
361 .El
362 .Pp
363 A link line has the form
364 .Dl "Link LINK-FROM LINK-TO"
365 For example:
366 .Dl "Link Europe/Istanbul Asia/Istanbul"
367 The
368 .Em LINK-FROM
369 field should appear as the
370 .Em NAME
371 field in some zone line;
372 the
373 .Em LINK-TO
374 field is used as an alternate name for that zone.
375 .Pp
376 Except for continuation lines,
377 lines may appear in any order in the input.
378 However, the behavior is unspecified if multiple zone or link
379 lines define the same name, or if the source of one link line is the
380 target of another.
381 .Pp
382 Lines in the file that describes leap seconds have the following form:
383 .Dl "Leap YEAR MONTH DAY HH:MM:SS CORR R/S"
384 For example:
385 .Dl "Leap 1974 Dec 31 23:59:60 + S"
386 The
387 .Em YEAR ,
388 .Em MONTH ,
389 .Em DAY ,
390 and
391 .Em HH:MM:SS
392 fields tell when the leap second happened.
393 The
394 .Em CORR
395 field
396 should be
397 .Dq +
398 if a second was added
399 or
400 .Dq -
401 if a second was skipped.
402 The
403 .Em R/S
404 field
405 should be (an abbreviation of)
406 .Dq Stationary
407 if the leap second time given by the other fields should be interpreted as UTC
408 or
409 (an abbreviation of)
410 .Dq Rolling
411 if the leap second time given by the other fields should be interpreted as
412 local wall clock time.
413 .Sh FILES
414 .Bl -tag -width ".Pa /usr/share/zoneinfo" -compact
415 .It Pa /usr/share/zoneinfo
416 standard directory used for created files
417 .El
418 .Sh EXAMPLES
419 Here is an extended example of
420 .Nm
421 input, intended to illustrate many of its features.
422 .Bd -literal
423 # Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
424 Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S
425 Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 -
427 Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S
428 Rule EU 1977 only - Sep lastSun 1:00u 0 -
429 Rule EU 1978 only - Oct 1 1:00u 0 -
430 Rule EU 1979 1995 - Sep lastSun 1:00u 0 -
431 Rule EU 1981 max - Mar lastSun 1:00u 1:00 S
432 Rule EU 1996 max - Oct lastSun 1:00u 0 -
434 # Zone NAME GMTOFF RULES/SAVE FORMAT UNTIL
435 Zone Europe/Zurich 0:34:08 - LMT 1853 Jul 16
436 0:29:46 - BMT 1894 Jun
437 1:00 Swiss CE%sT 1981
438 1:00 EU CE%sT
440 Link Europe/Zurich Switzerland
441 .Ed
442 .Pp
443 In this example, the zone is named Europe/Zurich but it has an alias
444 as Switzerland.
445 Zurich was 34 minutes and 8 seconds west of UT until
446 1853-07-16 at 00:00, when the offset changed to 7o26'22.50'';
447 although this works out to 0:29:45.50, the
448 input format cannot represent fractional seconds so it is rounded here.
449 After 1894-06-01 at 00:00 Swiss daylight saving rules (defined
450 with lines beginning with
451 .Dq Rule Swiss )
452 apply, and the UT offset became one hour.
453 From 1981 to the present, EU daylight saving rules have
454 applied, and the UTC offset has remained at one hour.
455 .Pp
456 In 1941 and 1942, daylight saving time applied
457 from the first Monday in May at 01:00 to the first Monday in October
458 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,
468 .Dq LMT
469 and
470 .Dq BMT
471 were initially used, respectively.
472 Since
473 Swiss rules and later EU rules were applied, the display name for the
474 timezone has been CET for standard time and CEST for daylight saving
475 time.
476 .Sh NOTES
477 For areas with more than two types of local time,
478 you may need to use local standard time in the
479 .Em AT
480 field of the earliest transition time's rule to ensure that
481 the earliest transition time recorded in the compiled file is correct.
482 .Pp
483 If,
484 for a particular zone,
485 a clock advance caused by the start of daylight saving
486 coincides with and is equal to
487 a clock retreat caused by a change in UT offset,
488 .Nm
489 produces a single transition to daylight saving at the new UT offset
490 (without any change in wall clock time).
491 To get separate transitions
492 use multiple zone continuation lines
493 specifying transition instants using universal time.
494 .Sh SEE ALSO
495 .Xr ctime 3 ,
496 .Xr tzfile 5 ,
497 .Xr zdump 8