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