466 lines
13 KiB
Groff
466 lines
13 KiB
Groff
.\" $FreeBSD$
|
|
.Dd June 20, 2004
|
|
.Dt ZIC 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm zic
|
|
.Nd timezone compiler
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl -version
|
|
.Op Fl Dsv
|
|
.Op Fl d Ar directory
|
|
.Op Fl g Ar group
|
|
.Op Fl L Ar leapsecondfilename
|
|
.Op Fl l Ar localtime
|
|
.Op Fl m Ar mode
|
|
.Op Fl p Ar posixrules
|
|
.Op Fl u Ar user
|
|
.Op Fl y Ar command
|
|
.Op Ar filename ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility reads text from the file(s) named on the command line
|
|
and creates the time conversion information files specified in this input.
|
|
If a
|
|
.Ar filename
|
|
is
|
|
.Em - ,
|
|
the standard input is read.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl -version
|
|
Output version information and exit.
|
|
.It Fl D
|
|
Do not automatically create directories.
|
|
If the input file(s) specify
|
|
an output file in a directory which does not already exist, the
|
|
default behavior is to attempt to create the directory.
|
|
If
|
|
.Fl D
|
|
is specified,
|
|
.Nm
|
|
will instead error out immediately.
|
|
.It Fl d Ar directory
|
|
Create time conversion information files in the named directory rather than
|
|
in the standard directory named below.
|
|
.It Fl g Ar group
|
|
After creating each output file, change its group ownership to the
|
|
specified
|
|
.Ar group
|
|
(which can be either a name or a numeric group ID).
|
|
.It Fl L Ar leapsecondfilename
|
|
Read leap second information from the file with the given name.
|
|
If this option is not used,
|
|
no leap second information appears in output files.
|
|
.It Fl l Ar timezone
|
|
Use the given
|
|
.Ar time zone
|
|
as local time.
|
|
The
|
|
.Nm
|
|
utility will act as if the input contained a link line of the form
|
|
.Pp
|
|
.D1 No "Link timezone localtime"
|
|
.Pp
|
|
(Note that this action has no effect on
|
|
.Fx ,
|
|
since the local time zone is specified in
|
|
.Pa /etc/localtime
|
|
and not
|
|
.Pa /usr/share/zoneinfo/localtime . )
|
|
.It Fl m Ar mode
|
|
After creating each output file, change its access mode to
|
|
.Ar mode .
|
|
Both numeric and alphabetic modes are accepted
|
|
(see
|
|
.Xr chmod 1 ) .
|
|
.It Fl p Ar timezone
|
|
Use the given
|
|
.Ar "time zone" Ns 's
|
|
rules when handling POSIX-format
|
|
time zone environment variables.
|
|
The
|
|
.Nm
|
|
utility will act as if the input contained a link line of the form
|
|
.Pp
|
|
.D1 No "Link timezone posixrules"
|
|
.It Fl u Ar user
|
|
After creating each output file, change its owner to
|
|
.Ar user
|
|
(which can be either a name or a numeric user ID).
|
|
.It Fl v
|
|
Complain if a year that appears in a data file is outside the range
|
|
of years representable by
|
|
.Xr time 3
|
|
values.
|
|
.It Fl s
|
|
Limit time values stored in output files to values that are the same
|
|
whether they are taken to be signed or unsigned.
|
|
You can use this option to generate SVVS-compatible files.
|
|
.It Fl y Ar command
|
|
Use the given
|
|
.Ar command
|
|
rather than
|
|
.Em yearistype
|
|
when checking year types (see below).
|
|
.El
|
|
.Pp
|
|
Input lines are made up of fields.
|
|
Fields are separated from one another by any number of white space characters.
|
|
Leading and trailing white space on input lines is ignored.
|
|
An unquoted sharp character (#) in the input introduces a comment which extends
|
|
to the end of the line the sharp character appears on.
|
|
White space characters and sharp characters may be enclosed in double quotes
|
|
(") if they are to be used as part of a field.
|
|
Any line that is blank (after comment stripping) is ignored.
|
|
Non-blank lines are expected to be of one of three types:
|
|
rule lines, zone lines, and link lines.
|
|
.Pp
|
|
A rule line has the form:
|
|
.Dl "Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
|
|
For example:
|
|
.Dl "Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D
|
|
.Pp
|
|
The fields that make up a rule line are:
|
|
.Bl -tag -width "LETTER/S" -offset indent
|
|
.It NAME
|
|
Give the (arbitrary) name of the set of rules this rule is part of.
|
|
.It FROM
|
|
Give the first year in which the rule applies.
|
|
Any integer year can be supplied; the Gregorian calendar is assumed.
|
|
The word
|
|
.Em minimum
|
|
(or an abbreviation) means the minimum year representable as an integer.
|
|
The word
|
|
.Em maximum
|
|
(or an abbreviation) means the maximum year representable as an integer.
|
|
Rules can describe times that are not representable as time values,
|
|
with the unrepresentable times ignored; this allows rules to be portable
|
|
among hosts with differing time value types.
|
|
.It TO
|
|
Give the final year in which the rule applies.
|
|
In addition to
|
|
.Em minimum
|
|
and
|
|
.Em maximum
|
|
(as above),
|
|
the word
|
|
.Em only
|
|
(or an abbreviation)
|
|
may be used to repeat the value of the
|
|
.Em FROM
|
|
field.
|
|
.It TYPE
|
|
Give the type of year in which the rule applies.
|
|
If
|
|
.Em TYPE
|
|
is
|
|
.Em \-
|
|
then the rule applies in all years between
|
|
.Em FROM
|
|
and
|
|
.Em TO
|
|
inclusive.
|
|
If
|
|
.Em TYPE
|
|
is something else, then
|
|
.Nm
|
|
executes the command
|
|
.Li yearistype Ar year Ar type
|
|
to check the type of a year:
|
|
an exit status of zero is taken to mean that the year is of the given type;
|
|
an exit status of one is taken to mean that the year is not of the given type.
|
|
.It IN
|
|
Name the month in which the rule takes effect.
|
|
Month names may be abbreviated.
|
|
.It ON
|
|
Give the day on which the rule takes effect.
|
|
Recognized forms include:
|
|
.Pp
|
|
.Bl -tag -width lastSun -compact -offset indent
|
|
.It \&5
|
|
the fifth of the month
|
|
.It lastSun
|
|
the last Sunday in the month
|
|
.It lastMon
|
|
the last Monday in the month
|
|
.It Sun>=8
|
|
first Sunday on or after the eighth
|
|
.It Sun<=25
|
|
last Sunday on or before the 25th
|
|
.El
|
|
.Pp
|
|
Names of days of the week may be abbreviated or spelled out in full.
|
|
Note that there must be no spaces within the
|
|
.Em ON
|
|
field.
|
|
.It AT
|
|
Give the time of day at which the rule takes effect.
|
|
Recognized forms include:
|
|
.Pp
|
|
.Bl -tag -width "\&1:28:14" -offset indent -compact
|
|
.It 2
|
|
time in hours
|
|
.It 2:00
|
|
time in hours and minutes
|
|
.It 15:00
|
|
24-hour format time (for times after noon)
|
|
.It 1:28:14
|
|
time in hours, minutes, and seconds
|
|
.El
|
|
.Pp
|
|
where hour 0 is midnight at the start of the day,
|
|
and hour 24 is midnight at the end of the day.
|
|
Any of these forms may be followed by the letter
|
|
.Sq Li w
|
|
if the given time is local
|
|
.Dq "wall clock"
|
|
time,
|
|
.Sq Li s
|
|
if the given time is local
|
|
.Dq standard
|
|
time, or
|
|
.Sq Li u
|
|
(or
|
|
.Sq Li g
|
|
or
|
|
.Sq Li z )
|
|
if the given time is universal time;
|
|
in the absence of an indicator,
|
|
wall clock time is assumed.
|
|
.It SAVE
|
|
Give the amount of time to be added to local standard time when the rule is in
|
|
effect.
|
|
This field has the same format as the
|
|
.Em AT
|
|
field
|
|
(although, of course, the
|
|
.Sq Li w
|
|
and
|
|
.Sq Li s
|
|
suffixes are not used).
|
|
.It LETTER/S
|
|
Give the
|
|
.Dq "variable part"
|
|
(for example, the
|
|
.Dq S
|
|
or
|
|
.Dq D
|
|
in
|
|
.Dq EST
|
|
or
|
|
.Dq EDT )
|
|
of time zone abbreviations to be used when this rule is in effect.
|
|
If this field is
|
|
.Em \- ,
|
|
the variable part is null.
|
|
.El
|
|
.Pp
|
|
A zone line has the form:
|
|
.Dl "Zone NAME GMTOFF RULES/SAVE FORMAT [UNTILYEAR [MONTH [DAY [TIME]]]]
|
|
For example:
|
|
.Dl "Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00
|
|
The fields that make up a zone line are:
|
|
.Bl -tag -width indent
|
|
.It NAME
|
|
The name of the time zone.
|
|
This is the name used in creating the time conversion information file for the
|
|
zone.
|
|
.It GMTOFF
|
|
The amount of time to add to UTC to get standard time in this zone.
|
|
This field has the same format as the
|
|
.Em AT
|
|
and
|
|
.Em SAVE
|
|
fields of rule lines;
|
|
begin the field with a minus sign if time must be subtracted from UTC.
|
|
.It RULES/SAVE
|
|
The name of the rule(s) that apply in the time zone or,
|
|
alternately, an amount of time to add to local standard time.
|
|
If this field is
|
|
.Em \-
|
|
then standard time always applies in the time zone.
|
|
.It FORMAT
|
|
The format for time zone abbreviations in this time zone.
|
|
The pair of characters
|
|
.Em %s
|
|
is used to show where the
|
|
.Dq "variable part"
|
|
of the time zone abbreviation goes.
|
|
Alternately,
|
|
a slash (/)
|
|
separates standard and daylight abbreviations.
|
|
.It UNTILYEAR [MONTH [DAY [TIME]]]
|
|
The time at which the UTC offset or the rule(s) change for a location.
|
|
It is specified as a year, a month, a day, and a time of day.
|
|
If this is specified,
|
|
the time zone information is generated from the given UTC offset
|
|
and rule change until the time specified.
|
|
The month, day, and time of day have the same format as the IN, ON, and AT
|
|
fields of a rule; trailing fields can be omitted, and default to the
|
|
earliest possible value for the missing fields.
|
|
.Pp
|
|
The next line must be a
|
|
.Dq continuation
|
|
line; this has the same form as a zone line except that the
|
|
string
|
|
.Dq Zone
|
|
and the name are omitted, as the continuation line will
|
|
place information starting at the time specified as the
|
|
.Em until
|
|
information in the previous line in the file used by the previous line.
|
|
Continuation lines may contain
|
|
.Em until
|
|
information, just as zone lines do, indicating that the next line is a further
|
|
continuation.
|
|
.El
|
|
.Pp
|
|
A link line has the form
|
|
.Dl "Link LINK-FROM LINK-TO
|
|
For example:
|
|
.Dl "Link Europe/Istanbul Asia/Istanbul
|
|
The
|
|
.Em LINK-FROM
|
|
field should appear as the
|
|
.Em NAME
|
|
field in some zone line;
|
|
the
|
|
.Em LINK-TO
|
|
field is used as an alternate name for that zone.
|
|
.Pp
|
|
Except for continuation lines,
|
|
lines may appear in any order in the input.
|
|
.Pp
|
|
Lines in the file that describes leap seconds have the following form:
|
|
.Dl "Leap YEAR MONTH DAY HH:MM:SS CORR R/S
|
|
For example:
|
|
.Dl "Leap 1974 Dec 31 23:59:60 + S
|
|
The
|
|
.Em YEAR ,
|
|
.Em MONTH ,
|
|
.Em DAY ,
|
|
and
|
|
.Em HH:MM:SS
|
|
fields tell when the leap second happened.
|
|
The
|
|
.Em CORR
|
|
field
|
|
should be
|
|
.Dq +
|
|
if a second was added
|
|
or
|
|
.Dq -
|
|
if a second was skipped.
|
|
.\" There's no need to document the following, since it's impossible for more
|
|
.\" than one leap second to be inserted or deleted at a time.
|
|
.\" The C Standard is in error in suggesting the possibility.
|
|
.\" See Terry J Quinn, The BIPM and the accurate measure of time,
|
|
.\" Proc IEEE 79, 7 (July 1991), 894-905.
|
|
.\" or
|
|
.\" .q ++
|
|
.\" if two seconds were added
|
|
.\" or
|
|
.\" .q --
|
|
.\" if two seconds were skipped.
|
|
The
|
|
.Em R/S
|
|
field
|
|
should be (an abbreviation of)
|
|
.Dq Stationary
|
|
if the leap second time given by the other fields should be interpreted as UTC
|
|
or
|
|
(an abbreviation of)
|
|
.Dq Rolling
|
|
if the leap second time given by the other fields should be interpreted as
|
|
local wall clock time.
|
|
.Sh "EXTENDED EXAMPLE"
|
|
Here is an extended example of
|
|
.Nm
|
|
input, intended to illustrate many of its features.
|
|
.br
|
|
.ne 22
|
|
.nf
|
|
.in +2m
|
|
.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
|
|
.sp
|
|
# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
|
|
Rule Swiss 1940 only - Nov 2 0:00 1:00 S
|
|
Rule Swiss 1940 only - Dec 31 0:00 0 -
|
|
Rule Swiss 1941 1942 - May Sun>=1 2:00 1:00 S
|
|
Rule Swiss 1941 1942 - Oct Sun>=1 0:00 0
|
|
.sp .5
|
|
Rule EU 1977 1980 - Apr Sun>=1 1:00u 1:00 S
|
|
Rule EU 1977 only - Sep lastSun 1:00u 0 -
|
|
Rule EU 1978 only - Oct 1 1:00u 0 -
|
|
Rule EU 1979 1995 - Sep lastSun 1:00u 0 -
|
|
Rule EU 1981 max - Mar lastSun 1:00u 1:00 S
|
|
Rule EU 1996 max - Oct lastSun 1:00u 0 -
|
|
.sp
|
|
.ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:34:08\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u
|
|
# Zone NAME GMTOFF RULES FORMAT UNTIL
|
|
Zone Europe/Zurich 0:34:08 - LMT 1848 Sep 12
|
|
0:29:44 - BMT 1894 Jun
|
|
1:00 Swiss CE%sT 1981
|
|
1:00 EU CE%sT
|
|
.sp
|
|
Link Europe/Zurich Switzerland
|
|
.sp
|
|
.in
|
|
.fi
|
|
In this example, the zone is named Europe/Zurich but it has an alias
|
|
as Switzerland.
|
|
Zurich was 34 minutes and 8 seconds west of GMT until 1848-09-12
|
|
at 00:00, when the offset changed to 29 minutes and 44 seconds.
|
|
After 1894-06-01 at 00:00 Swiss daylight saving rules (defined with
|
|
lines beginning with "Rule Swiss") apply, and the GMT offset became
|
|
one hour.
|
|
From 1981 to the present, EU daylight saving rules have applied,
|
|
and the UTC offset has remained at one hour.
|
|
.Pp
|
|
In 1940, daylight saving time applied from November 2 at 00:00 to
|
|
December 31 at 00:00.
|
|
In 1941 and 1942, daylight saving time applied from the first Sunday
|
|
in May at 02:00 to the first Sunday in October at 00:00.
|
|
The pre-1981 EU daylight-saving rules have no effect here, but are
|
|
included for completeness.
|
|
Since 1981, daylight saving has begun on the last Sunday in March
|
|
at 01:00 UTC.
|
|
Until 1995 it ended the last Sunday in September at 01:00 UTC, but
|
|
this changed to the last Sunday in October starting in 1996.
|
|
.Pp
|
|
For purposes of display, "LMT" and "BMT" were initially used,
|
|
respectively.
|
|
Since Swiss rules and later EU rules were applied, the display name
|
|
for the timezone has been CET for standard time and CEST for daylight
|
|
saving time.
|
|
.Sh NOTES
|
|
For areas with more than two types of local time,
|
|
you may need to use local standard time in the
|
|
.Em AT
|
|
field of the earliest transition time's rule to ensure that
|
|
the earliest transition time recorded in the compiled file is correct.
|
|
.Pp
|
|
If, for a particular zone, a clock advance caused by the start of
|
|
daylight saving coincides with and is equal to a clock retreat
|
|
caused by a change in UTC offset,
|
|
.Nm
|
|
produces a single transition to daylight saving at the new UTC offset
|
|
(without any change in wall clock time).
|
|
To get separate transitions use multiple zone continuation lines
|
|
specifying transition instants using universal time.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/zoneinfo -compact
|
|
.It /usr/share/zoneinfo
|
|
standard directory used for created files
|
|
.El
|
|
.Sh "SEE ALSO"
|
|
.Xr ctime 3 ,
|
|
.Xr tzfile 5 ,
|
|
.Xr zdump 8
|
|
.\" @(#)zic.8 8.5
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 2009-05-17 by Arthur David Olson.
|