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