| blob | 8bbdce839b3144af22c573eb875f515f9ef00e12 |
1 .TH ZIC 8
2 .SH NAME
3 zic \- time zone compiler
4 .SH SYNOPSIS
5 .B zic
6 [
7 .B \-\-version
8 ]
9 [
10 .B \-v
11 ] [
12 .B \-d
13 .I directory
14 ] [
15 .B \-l
16 .I localtime
17 ] [
18 .B \-p
19 .I posixrules
20 ] [
21 .B \-L
22 .I leapsecondfilename
23 ] [
24 .B \-s
25 ] [
26 .B \-y
27 .I command
28 ] [
29 .I filename
30 \&... ]
31 .SH DESCRIPTION
32 .if t .ds lq ``
33 .if t .ds rq ''
34 .if n .ds lq \&"\"
35 .if n .ds rq \&"\"
36 .de q
37 \\$3\*(lq\\$1\*(rq\\$2
38 ..
39 .I Zic
40 reads text from the file(s) named on the command line
41 and creates the time conversion information files specified in this input.
42 If a
43 .I filename
44 is
45 .BR \- ,
46 the standard input is read.
47 .PP
48 These options are available:
49 .TP
50 .BI "\-\-version"
51 Output version information and exit.
52 .TP
53 .BI "\-d " directory
54 Create time conversion information files in the named directory rather than
55 in the standard directory named below.
56 .TP
57 .BI "\-l " timezone
58 Use the given time zone as local time.
59 .I Zic
60 will act as if the input contained a link line of the form
61 .sp
62 .ti +.5i
63 Link \fItimezone\fP localtime
64 .TP
65 .BI "\-p " timezone
66 Use the given time zone's rules when handling POSIX-format
67 time zone environment variables.
68 .I Zic
69 will act as if the input contained a link line of the form
70 .sp
71 .ti +.5i
72 Link \fItimezone\fP posixrules
73 .TP
74 .BI "\-L " leapsecondfilename
75 Read leap second information from the file with the given name.
76 If this option is not used,
77 no leap second information appears in output files.
78 .TP
79 .B \-v
80 Complain if a year that appears in a data file is outside the range
81 of years representable by
82 .IR time (2)
83 values.
84 Also complain if a time of 24:00
85 (which cannot be handled by pre-1998 versions of
86 .IR zic )
87 appears in the input.
88 .TP
89 .B \-s
90 Limit time values stored in output files to values that are the same
91 whether they're taken to be signed or unsigned.
92 You can use this option to generate SVVS-compatible files.
93 .TP
94 .BI "\-y " command
95 Use the given
96 .I command
97 rather than
98 .B yearistype
99 when checking year types (see below).
100 .PP
101 Input lines are made up of fields.
102 Fields are separated from one another by any number of white space characters.
103 Leading and trailing white space on input lines is ignored.
104 An unquoted sharp character (#) in the input introduces a comment which extends
105 to the end of the line the sharp character appears on.
106 White space characters and sharp characters may be enclosed in double quotes
107 (") if they're to be used as part of a field.
108 Any line that is blank (after comment stripping) is ignored.
109 Non-blank lines are expected to be of one of three types:
110 rule lines, zone lines, and link lines.
111 .PP
112 A rule line has the form
113 .nf
114 .ti +.5i
115 .ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'TYPE\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
116 .sp
117 Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
118 .sp
119 For example:
120 .ti +.5i
121 .sp
122 Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D
123 .sp
124 .fi
125 The fields that make up a rule line are:
126 .TP "\w'LETTER/S'u"
127 .B NAME
128 Gives the (arbitrary) name of the set of rules this rule is part of.
129 .TP
130 .B FROM
131 Gives the first year in which the rule applies.
132 Any integer year can be supplied; the Gregorian calendar is assumed.
133 The word
134 .B minimum
135 (or an abbreviation) means the minimum year representable as an integer.
136 The word
137 .B maximum
138 (or an abbreviation) means the maximum year representable as an integer.
139 Rules can describe times that are not representable as time values,
140 with the unrepresentable times ignored; this allows rules to be portable
141 among hosts with differing time value types.
142 .TP
143 .B TO
144 Gives the final year in which the rule applies.
145 In addition to
146 .B minimum
147 and
148 .B maximum
149 (as above),
150 the word
151 .B only
152 (or an abbreviation)
153 may be used to repeat the value of the
154 .B FROM
155 field.
156 .TP
157 .B TYPE
158 Gives the type of year in which the rule applies.
159 If
160 .B TYPE
161 is
162 .B \-
163 then the rule applies in all years between
164 .B FROM
165 and
166 .B TO
167 inclusive.
168 If
169 .B TYPE
170 is something else, then
171 .I zic
172 executes the command
173 .ti +.5i
174 \fByearistype\fP \fIyear\fP \fItype\fP
175 .br
176 to check the type of a year:
177 an exit status of zero is taken to mean that the year is of the given type;
178 an exit status of one is taken to mean that the year is not of the given type.
179 .TP
180 .B IN
181 Names the month in which the rule takes effect.
182 Month names may be abbreviated.
183 .TP
184 .B ON
185 Gives the day on which the rule takes effect.
186 Recognized forms include:
187 .nf
188 .in +.5i
189 .sp
190 .ta \w'Sun<=25\0\0'u
191 5 the fifth of the month
192 lastSun the last Sunday in the month
193 lastMon the last Monday in the month
194 Sun>=8 first Sunday on or after the eighth
195 Sun<=25 last Sunday on or before the 25th
196 .fi
197 .in -.5i
198 .sp
199 Names of days of the week may be abbreviated or spelled out in full.
200 Note that there must be no spaces within the
201 .B ON
202 field.
203 .TP
204 .B AT
205 Gives the time of day at which the rule takes effect.
206 Recognized forms include:
207 .nf
208 .in +.5i
209 .sp
210 .ta \w'1:28:13\0\0'u
211 2 time in hours
212 2:00 time in hours and minutes
213 15:00 24-hour format time (for times after noon)
214 1:28:14 time in hours, minutes, and seconds
215 \- equivalent to 0
216 .fi
217 .in -.5i
218 .sp
219 where hour 0 is midnight at the start of the day,
220 and hour 24 is midnight at the end of the day.
221 Any of these forms may be followed by the letter
222 .B w
223 if the given time is local
224 .q "wall clock"
225 time,
226 .B s
227 if the given time is local
228 .q standard
229 time, or
230 .B u
231 (or
232 .B g
233 or
234 .BR z )
235 if the given time is universal time;
236 in the absence of an indicator,
237 wall clock time is assumed.
238 .TP
239 .B SAVE
240 Gives the amount of time to be added to local standard time when the rule is in
241 effect.
242 This field has the same format as the
243 .B AT
244 field
245 (although, of course, the
246 .B w
247 and
248 .B s
249 suffixes are not used).
250 .TP
251 .B LETTER/S
252 Gives the
253 .q "variable part"
254 (for example, the
255 .q S
256 or
257 .q D
258 in
259 .q EST
260 or
261 .q EDT )
262 of time zone abbreviations to be used when this rule is in effect.
263 If this field is
264 .BR \- ,
265 the variable part is null.
266 .PP
267 A zone line has the form
268 .sp
269 .nf
270 .ti +.5i
271 .ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u
272 Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL]
273 .sp
274 For example:
275 .sp
276 .ti +.5i
277 Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00
278 .sp
279 .fi
280 The fields that make up a zone line are:
281 .TP "\w'GMTOFF'u"
282 .B NAME
283 The name of the time zone.
284 This is the name used in creating the time conversion information file for the
285 zone.
286 .TP
287 .B GMTOFF
288 The amount of time to add to UTC to get standard time in this zone.
289 This field has the same format as the
290 .B AT
291 and
292 .B SAVE
293 fields of rule lines;
294 begin the field with a minus sign if time must be subtracted from UTC.
295 .TP
296 .B RULES/SAVE
297 The name of the rule(s) that apply in the time zone or,
298 alternately, an amount of time to add to local standard time.
299 If this field is
300 .B \-
301 then standard time always applies in the time zone.
302 .TP
303 .B FORMAT
304 The format for time zone abbreviations in this time zone.
305 The pair of characters
306 .B %s
307 is used to show where the
308 .q "variable part"
309 of the time zone abbreviation goes.
310 Alternately,
311 a slash (/)
312 separates standard and daylight abbreviations.
313 .TP
314 .B UNTIL
315 The time at which the UTC offset or the rule(s) change for a location.
316 It is specified as a year, a month, a day, and a time of day.
317 If this is specified,
318 the time zone information is generated from the given UTC offset
319 and rule change until the time specified.
320 The month, day, and time of day have the same format as the IN, ON, and AT
321 columns of a rule; trailing columns can be omitted, and default to the
322 earliest possible value for the missing columns.
323 .IP
324 The next line must be a
325 .q continuation
326 line; this has the same form as a zone line except that the
327 string
328 .q Zone
329 and the name are omitted, as the continuation line will
330 place information starting at the time specified as the
331 .B UNTIL
332 field in the previous line in the file used by the previous line.
333 Continuation lines may contain an
334 .B UNTIL
335 field, just as zone lines do, indicating that the next line is a further
336 continuation.
337 .PP
338 A link line has the form
339 .sp
340 .nf
341 .ti +.5i
342 .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u
343 Link LINK-FROM LINK-TO
344 .sp
345 For example:
346 .sp
347 .ti +.5i
348 Link Europe/Istanbul Asia/Istanbul
349 .sp
350 .fi
351 The
352 .B LINK-FROM
353 field should appear as the
354 .B NAME
355 field in some zone line;
356 the
357 .B LINK-TO
358 field is used as an alternate name for that zone.
359 .PP
360 Except for continuation lines,
361 lines may appear in any order in the input.
362 .PP
363 Lines in the file that describes leap seconds have the following form:
364 .nf
365 .ti +.5i
366 .ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u
367 .sp
368 Leap YEAR MONTH DAY HH:MM:SS CORR R/S
369 .sp
370 For example:
371 .ti +.5i
372 .sp
373 Leap 1974 Dec 31 23:59:60 + S
374 .sp
375 .fi
376 The
377 .BR YEAR ,
378 .BR MONTH ,
379 .BR DAY ,
380 and
381 .B HH:MM:SS
382 fields tell when the leap second happened.
383 The
384 .B CORR
385 field
386 should be
387 .q +
388 if a second was added
389 or
390 .q -
391 if a second was skipped.
392 .\" There's no need to document the following, since it's impossible for more
393 .\" than one leap second to be inserted or deleted at a time.
394 .\" The C Standard is in error in suggesting the possibility.
395 .\" See Terry J Quinn, The BIPM and the accurate measure of time,
396 .\" Proc IEEE 79, 7 (July 1991), 894-905.
397 .\" or
398 .\" .q ++
399 .\" if two seconds were added
400 .\" or
401 .\" .q --
402 .\" if two seconds were skipped.
403 The
404 .B R/S
405 field
406 should be (an abbreviation of)
407 .q Stationary
408 if the leap second time given by the other fields should be interpreted as UTC
409 or
410 (an abbreviation of)
411 .q Rolling
412 if the leap second time given by the other fields should be interpreted as
413 local wall clock time.
414 .SH NOTES
415 For areas with more than two types of local time,
416 you may need to use local standard time in the
417 .B AT
418 field of the earliest transition time's rule to ensure that
419 the earliest transition time recorded in the compiled file is correct.
420 .PP
421 If,
422 for a particular zone,
423 a clock advance caused by the start of daylight saving
424 coincides with and is equal to
425 a clock retreat caused by a change in UTC offset,
426 .IR zic
427 produces a single transition to daylight saving at the new UTC offset
428 (without any change in wall clock time).
429 To get separate transitions
430 use multiple zone continuation lines
431 specifying transition instants using universal time.
432 .SH FILE
433 /usr/share/zoneinfo standard directory used for created files
434 .SH "SEE ALSO"
435 newctime(3), tzfile(5), zdump(8)
436 .\" @(#)zic.8 7.24