Commit | Line | Data |
---|---|---|
984263bc | 1 | .\" $FreeBSD: src/usr.sbin/zic/zic.8,v 1.11.2.4 2003/03/11 22:31:35 trhodes Exp $ |
803871a5 | 2 | .Dd March 22, 2016 |
984263bc MD |
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 | |
0e2a9149 | 61 | .No "Link timezone localtime" |
984263bc MD |
62 | .Ed |
63 | (Note that this action has no effect on | |
9bb2a92d | 64 | .Dx , |
984263bc MD |
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 | |
0e2a9149 | 84 | .No "Link timezone posixrules" |
984263bc MD |
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 | |
402c9c91 SW |
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 | |
b56521cf | 98 | .Xr time 3 |
984263bc | 99 | values. |
402c9c91 SW |
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 | |
984263bc MD |
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. | |
402c9c91 | 144 | Fields are separated from one another by one or more white space characters. |
984263bc MD |
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 | |
5756332b SW |
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 | |
984263bc | 157 | A rule line has the form: |
9f3fc534 | 158 | .Dl "Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S" |
984263bc | 159 | For example: |
0e2a9149 | 160 | .Dl "Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D" |
984263bc MD |
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 | |
0e2a9149 SW |
248 | .It - |
249 | equivalent to 0 | |
984263bc MD |
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: | |
0e2a9149 | 300 | .Dl "Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]]" |
984263bc | 301 | For example: |
0e2a9149 | 302 | .Dl "Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00" |
984263bc MD |
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 | |
402c9c91 | 310 | The amount of time to add to UT to get standard time in this zone. |
984263bc MD |
311 | This field has the same format as the |
312 | .Em AT | |
313 | and | |
314 | .Em SAVE | |
315 | fields of rule lines; | |
402c9c91 | 316 | begin the field with a minus sign if time must be subtracted from UT. |
984263bc MD |
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. | |
803871a5 SW |
333 | To conform to POSIX, a time zone abbreviation should contain only |
334 | alphanumeric ASCII characters, | |
335 | .Dq + | |
336 | and | |
337 | .Dq - . | |
0e2a9149 | 338 | .It UNTILYEAR [MONTH [DAY [TIME]]] |
402c9c91 | 339 | The time at which the UT offset or the rule(s) change for a location. |
984263bc MD |
340 | It is specified as a year, a month, a day, and a time of day. |
341 | If this is specified, | |
402c9c91 | 342 | the time zone information is generated from the given UT offset |
984263bc MD |
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 | |
0e2a9149 SW |
345 | fields of a rule; trailing fields can be omitted, and default to the |
346 | earliest possible value for the missing fields. | |
984263bc MD |
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 | |
0e2a9149 SW |
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 | |
984263bc MD |
360 | continuation. |
361 | .El | |
362 | .Pp | |
363 | A link line has the form | |
0e2a9149 | 364 | .Dl "Link LINK-FROM LINK-TO" |
984263bc | 365 | For example: |
0e2a9149 | 366 | .Dl "Link Europe/Istanbul Asia/Istanbul" |
984263bc MD |
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. | |
402c9c91 SW |
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. | |
984263bc MD |
381 | .Pp |
382 | Lines in the file that describes leap seconds have the following form: | |
0e2a9149 | 383 | .Dl "Leap YEAR MONTH DAY HH:MM:SS CORR R/S" |
984263bc | 384 | For example: |
0e2a9149 | 385 | .Dl "Leap 1974 Dec 31 23:59:60 + S" |
984263bc MD |
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. | |
984263bc MD |
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. | |
5a394c59 FF |
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 | |
ec9265c3 | 418 | .Sh EXAMPLES |
0e2a9149 SW |
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 | |
402c9c91 SW |
424 | Rule Swiss 1941 1942 - May Mon>=1 1:00 1:00 S |
425 | Rule Swiss 1941 1942 - Oct Mon>=1 2:00 0 - | |
0e2a9149 SW |
426 | |
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 - | |
433 | ||
402c9c91 SW |
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 | |
0e2a9149 SW |
439 | |
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. | |
402c9c91 SW |
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. | |
0e2a9149 SW |
449 | After 1894-06-01 at 00:00 Swiss daylight saving rules (defined |
450 | with lines beginning with | |
451 | .Dq Rule Swiss ) | |
402c9c91 | 452 | apply, and the UT offset became one hour. |
0e2a9149 SW |
453 | From 1981 to the present, EU daylight saving rules have |
454 | applied, and the UTC offset has remained at one hour. | |
455 | .Pp | |
0e2a9149 | 456 | In 1941 and 1942, daylight saving time applied |
402c9c91 SW |
457 | from the first Monday in May at 01:00 to the first Monday in October |
458 | at 02:00. | |
0e2a9149 SW |
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 | |
984263bc MD |
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. | |
0e2a9149 SW |
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 | |
402c9c91 | 487 | a clock retreat caused by a change in UT offset, |
0e2a9149 | 488 | .Nm |
402c9c91 | 489 | produces a single transition to daylight saving at the new UT offset |
0e2a9149 SW |
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. | |
ec9265c3 | 494 | .Sh SEE ALSO |
984263bc MD |
495 | .Xr ctime 3 , |
496 | .Xr tzfile 5 , | |
497 | .Xr zdump 8 |