mirror of https://github.com/mkerrisk/man-pages
608 lines
16 KiB
Groff
608 lines
16 KiB
Groff
.\" %%%LICENSE_START(PUBLIC_DOMAIN)
|
|
.\" This page is in the public domain
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH ZIC 8 2010-02-25 "" "Linux System Administration"
|
|
.SH NAME
|
|
zic \- timezone compiler
|
|
.SH SYNOPSIS
|
|
.B zic
|
|
[
|
|
.I option
|
|
\&... ] [
|
|
.I filename
|
|
\&... ]
|
|
.SH DESCRIPTION
|
|
.ie '\(lq'' .ds lq \&"\"
|
|
.el .ds lq \(lq\"
|
|
.ie '\(rq'' .ds rq \&"\"
|
|
.el .ds rq \(rq\"
|
|
.de q
|
|
\\$3\*(lq\\$1\*(rq\\$2
|
|
..
|
|
.ie '\(la'' .ds < <
|
|
.el .ds < \(la
|
|
.ie '\(ra'' .ds > >
|
|
.el .ds > \(ra
|
|
.ie \n(.g \{\
|
|
. ds : \:
|
|
. ds - \f(CW-\fP
|
|
.\}
|
|
.el \{\
|
|
. ds :
|
|
. ds - \-
|
|
.\}
|
|
The
|
|
.B zic
|
|
program reads text from the file(s) named on the command line
|
|
and creates the time conversion information files specified in this input.
|
|
If a
|
|
.I filename
|
|
is
|
|
.q "\*-" ,
|
|
standard input is read.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B "\*-\*-version"
|
|
Output version information and exit.
|
|
.TP
|
|
.B \*-\*-help
|
|
Output short usage message and exit.
|
|
.TP
|
|
.BI "\*-d " directory
|
|
Create time conversion information files in the named directory rather than
|
|
in the standard directory named below.
|
|
.TP
|
|
.BI "\*-l " timezone
|
|
Use
|
|
.I timezone
|
|
as local time.
|
|
.B zic
|
|
will act as if the input contained a link line of the form
|
|
.sp
|
|
.ti +.5i
|
|
Link \fItimezone\fP localtime
|
|
.TP
|
|
.BI "\*-p " timezone
|
|
Use
|
|
.IR timezone 's
|
|
rules when handling POSIX-format
|
|
timezone environment variables.
|
|
.B zic
|
|
will act as if the input contained a link line of the form
|
|
.sp
|
|
.ti +.5i
|
|
Link \fItimezone\fP posixrules
|
|
.TP
|
|
.BI "\*-L " 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.
|
|
.TP
|
|
.B \*-v
|
|
Be more verbose, and complain about the following situations:
|
|
.RS
|
|
.PP
|
|
The input specifies a link to a link.
|
|
.PP
|
|
A year that appears in a data file is outside the range
|
|
of years representable by
|
|
.BR time (2)
|
|
values.
|
|
.PP
|
|
A time of 24:00 or more appears in the input.
|
|
Pre-1998 versions of
|
|
.B zic
|
|
prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00.
|
|
.PP
|
|
A rule goes past the start or end of the month.
|
|
Pre-2004 versions of
|
|
.B zic
|
|
prohibit this.
|
|
.PP
|
|
The output file does not contain all the information about the
|
|
long-term future of a timezone, because the future cannot be summarized as
|
|
an extended POSIX TZ string. For example, as of 2013 this problem
|
|
occurs for Iran's daylight-saving rules for the predicted future, as
|
|
these rules are based on the Iranian calendar, which cannot be
|
|
represented.
|
|
.PP
|
|
The output contains data that may not be handled properly by client
|
|
code designed for older
|
|
.B zic
|
|
output formats. These compatibility issues affect only timestamps
|
|
before 1970 or after the start of 2038.
|
|
.PP
|
|
A time zone abbreviation has fewer than 3 characters.
|
|
POSIX requires at least 3.
|
|
.PP
|
|
An output file name contains a byte that is not an ASCII letter,
|
|
.q "\*-" ,
|
|
.q "/" ,
|
|
or
|
|
.q "_" ;
|
|
or it contains a file name component that contains more than 14 bytes
|
|
or that starts with
|
|
.q "\*-" .
|
|
.RE
|
|
.TP
|
|
.B \*-s
|
|
Limit time values stored in output files to values that are the same
|
|
whether they're taken to be signed or unsigned.
|
|
You can use this option to generate SVVS-compatible files.
|
|
.PP
|
|
Input files should be text files, that is, they should be a series of
|
|
zero or more lines, each ending in a newline byte and containing at
|
|
most 511 bytes, and without any NUL bytes. The input text's encoding
|
|
is typically UTF-8 or ASCII; it should have a unibyte representation
|
|
for the POSIX Portable Character Set (PPCS)
|
|
\*<http://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
|
|
and the encoding's non-unibyte characters should consist entirely of
|
|
non-PPCS bytes. Non-PPCS characters typically occur only in comments:
|
|
although output file names and time zone abbreviations can contain
|
|
nearly any character, other software will work better if these are
|
|
limited to the restricted syntax described under the
|
|
.B \*-v
|
|
option.
|
|
.PP
|
|
Input lines are made up of fields.
|
|
Fields are separated from one another by one or more white space characters.
|
|
The white space characters are space, form feed, carriage return, newline,
|
|
tab, and vertical tab.
|
|
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're to be used as part of a field.
|
|
Any line that is blank (after comment stripping) is ignored.
|
|
Nonblank lines are expected to be of one of three types:
|
|
rule lines, zone lines, and link lines.
|
|
.PP
|
|
Names must be in English and are case insensitive.
|
|
They appear in several contexts, and include month and weekday names
|
|
and keywords such as
|
|
.BR "maximum" ,
|
|
.BR "only" ,
|
|
.BR "Rolling" ,
|
|
and
|
|
.BR "Zone" .
|
|
A name can be abbreviated by omitting all but an initial prefix; any
|
|
abbreviation must be unambiguous in context.
|
|
.PP
|
|
A rule line has the form
|
|
.nf
|
|
.ti +.5i
|
|
.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:00w\0\0'u +\w'1:00d\0\0'u
|
|
.sp
|
|
Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
|
|
.sp
|
|
For example:
|
|
.ti +.5i
|
|
.sp
|
|
Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00 D
|
|
.sp
|
|
.fi
|
|
The fields that make up a rule line are:
|
|
.TP "\w'LETTER/S'u"
|
|
.B NAME
|
|
Gives the name of the rule set that contains this line.
|
|
The name must start with a character that is neither
|
|
an ASCII digit nor
|
|
.q \*-
|
|
nor
|
|
.q + .
|
|
To allow for future extensions,
|
|
an unquoted name should not contain characters from the set
|
|
.q !$%&'()*,/:;<=>?@[\e]^`{|}~ .
|
|
.TP
|
|
.B FROM
|
|
Gives the first year in which the rule applies.
|
|
Any signed integer year can be supplied; the proleptic Gregorian calendar
|
|
is assumed, with year 0 preceding year 1.
|
|
The word
|
|
.B minimum
|
|
(or an abbreviation) means the indefinite past.
|
|
The word
|
|
.B maximum
|
|
(or an abbreviation) means the indefinite future.
|
|
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.
|
|
.TP
|
|
.B TO
|
|
Gives the final year in which the rule applies.
|
|
In addition to
|
|
.B minimum
|
|
and
|
|
.B maximum
|
|
(as above),
|
|
the word
|
|
.B only
|
|
(or an abbreviation)
|
|
may be used to repeat the value of the
|
|
.B FROM
|
|
field.
|
|
.TP
|
|
.B TYPE
|
|
should be
|
|
.q \*-
|
|
and is present for compatibility with older versions of
|
|
.B zic
|
|
in which it could contain year types.
|
|
.TP
|
|
.B IN
|
|
Names the month in which the rule takes effect.
|
|
Month names may be abbreviated.
|
|
.TP
|
|
.B ON
|
|
Gives the day on which the rule takes effect.
|
|
Recognized forms include:
|
|
.nf
|
|
.in +.5i
|
|
.sp
|
|
.ta \w'Sun<=25\0\0'u
|
|
5 the fifth of the month
|
|
lastSun the last Sunday in the month
|
|
lastMon the last Monday in the month
|
|
Sun>=8 first Sunday on or after the eighth
|
|
Sun<=25 last Sunday on or before the 25th
|
|
.fi
|
|
.in -.5i
|
|
.sp
|
|
A weekday name (e.g.,
|
|
.BR "Sunday" )
|
|
or a weekday name preceded by
|
|
.q "last"
|
|
(e.g.,
|
|
.BR "lastSunday" )
|
|
may be abbreviated or spelled out in full.
|
|
Note that there must be no spaces within the
|
|
.B ON
|
|
field.
|
|
.TP
|
|
.B AT
|
|
Gives the time of day at which the rule takes effect.
|
|
Recognized forms include:
|
|
.nf
|
|
.in +.5i
|
|
.sp
|
|
.ta \w'00:19:32.13\0\0'u
|
|
2 time in hours
|
|
2:00 time in hours and minutes
|
|
01:28:14 time in hours, minutes, and seconds
|
|
15:00 24-hour format time (for times after noon)
|
|
260:00 260 hours after 00:00
|
|
\*-2:30 2.5 hours before 00:00
|
|
\*- equivalent to 0
|
|
.fi
|
|
.in -.5i
|
|
.sp
|
|
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
|
|
.B w
|
|
if the given time is local
|
|
.q "wall clock"
|
|
time,
|
|
.B s
|
|
if the given time is local
|
|
.q "standard"
|
|
time, or
|
|
.B u
|
|
(or
|
|
.B g
|
|
or
|
|
.BR z )
|
|
if the given time is universal time;
|
|
in the absence of an indicator,
|
|
wall clock time is assumed.
|
|
The intent is that a rule line describes the instants when a
|
|
clock/calendar set to the type of time specified in the
|
|
.B AT
|
|
field would show the specified date and time of day.
|
|
.TP
|
|
.B SAVE
|
|
Gives 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
|
|
.B AT
|
|
field
|
|
(although, of course, the
|
|
.B w
|
|
and
|
|
.B s
|
|
suffixes are not used).
|
|
Negative offsets are allowed; in Ireland, for example, daylight saving
|
|
time is observed in winter and has a negative offset relative to
|
|
Irish Standard Time.
|
|
The offset is merely added to standard time; for example,
|
|
.B zic
|
|
does not distinguish a 10:30 standard time plus an 0:30
|
|
.B SAVE
|
|
from a 10:00 standard time plus a 1:00
|
|
.BR SAVE .
|
|
.TP
|
|
.B LETTER/S
|
|
Gives the
|
|
.q "variable part"
|
|
(for example, the
|
|
.q "S"
|
|
or
|
|
.q "D"
|
|
in
|
|
.q "EST"
|
|
or
|
|
.q "EDT" )
|
|
of time zone abbreviations to be used when this rule is in effect.
|
|
If this field is
|
|
.q \*- ,
|
|
the variable part is null.
|
|
.PP
|
|
A zone line has the form
|
|
.sp
|
|
.nf
|
|
.ti +.5i
|
|
.ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'UTOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u
|
|
Zone NAME UTOFF RULES FORMAT [UNTIL]
|
|
.sp
|
|
For example:
|
|
.sp
|
|
.ti +.5i
|
|
Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00
|
|
.sp
|
|
.fi
|
|
The fields that make up a zone line are:
|
|
.TP "\w'UTOFF'u"
|
|
.B NAME
|
|
The name of the timezone.
|
|
This is the name used in creating the time conversion information file for the
|
|
timezone.
|
|
It should not contain a file name component
|
|
.q ".\&"
|
|
or
|
|
.q ".." ;
|
|
a file name component is a maximal substring that does not contain
|
|
.q "/" .
|
|
.TP
|
|
.B UTOFF
|
|
The amount of time to add to UT to get standard time.
|
|
This field has the same format as the
|
|
.B AT
|
|
and
|
|
.B SAVE
|
|
fields of rule lines;
|
|
begin the field with a minus sign if time must be subtracted from UT.
|
|
.TP
|
|
.B RULES
|
|
The name of the rules that apply in the timezone or,
|
|
alternatively, a field in the same format as a rule-line SAVE column,
|
|
giving of the amount of time to be added to local standard time
|
|
effect, and whether the resulting time is standard or daylight saving.
|
|
If this field is
|
|
.B \*-
|
|
then standard time always applies.
|
|
When an amount of time is given, only the sum of standard time and
|
|
this amount matters.
|
|
.TP
|
|
.B FORMAT
|
|
The format for time zone abbreviations.
|
|
The pair of characters
|
|
.B %s
|
|
is used to show where the
|
|
.q "variable part"
|
|
of the time zone abbreviation goes.
|
|
Alternatively, a format can use the pair of characters
|
|
.B %z
|
|
to stand for the UT offset in the form
|
|
.RI \(+- hh ,
|
|
.RI \(+- hhmm ,
|
|
or
|
|
.RI \(+- hhmmss ,
|
|
using the shortest form that does not lose information, where
|
|
.IR hh ,
|
|
.IR mm ,
|
|
and
|
|
.I ss
|
|
are the hours, minutes, and seconds east (+) or west (\(mi) of UT.
|
|
Alternatively,
|
|
a slash (/)
|
|
separates standard and daylight abbreviations.
|
|
To conform to POSIX, a time zone abbreviation should contain only
|
|
alphanumeric ASCII characters,
|
|
.q "+"
|
|
and
|
|
.q "\*-".
|
|
.TP
|
|
.B UNTIL
|
|
The time at which the UT offset or the rule(s) change for a location.
|
|
It takes the form of YEAR [MONTH [DAY [TIME]]].
|
|
If this is specified,
|
|
the time zone information is generated from the given UT offset
|
|
and rule change until the time specified, which is interpreted using
|
|
the rules in effect just before the transition.
|
|
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.
|
|
.IP
|
|
The next line must be a
|
|
.q "continuation"
|
|
line; this has the same form as a zone line except that the
|
|
string
|
|
.q "Zone"
|
|
and the name are omitted, as the continuation line will
|
|
place information starting at the time specified as the
|
|
.q "until"
|
|
information in the previous line in the file used by the previous line.
|
|
Continuation lines may contain
|
|
.q "until"
|
|
information, just as zone lines do, indicating that the next line is a further
|
|
continuation.
|
|
.PP
|
|
If a zone changes at the same instant that a rule would otherwise take
|
|
effect in the earlier zone or continuation line, the rule is ignored.
|
|
In a single zone it is an error if two rules take effect at the same
|
|
instant, or if two zone changes take effect at the same instant.
|
|
.PP
|
|
A link line has the form
|
|
.sp
|
|
.nf
|
|
.ti +.5i
|
|
.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u
|
|
Link TARGET LINK-NAME
|
|
.sp
|
|
For example:
|
|
.sp
|
|
.ti +.5i
|
|
Link Europe/Istanbul Asia/Istanbul
|
|
.sp
|
|
.fi
|
|
The
|
|
.B TARGET
|
|
field should appear as the
|
|
.B NAME
|
|
field in some zone line.
|
|
The
|
|
.B LINK-NAME
|
|
field is used as an alternative name for that zone;
|
|
it has the same syntax as a zone line's
|
|
.B NAME
|
|
field.
|
|
.PP
|
|
Except for continuation lines,
|
|
lines may appear in any order in the input.
|
|
However, the behavior is unspecified if multiple zone or link lines
|
|
define the same name, or if the source of one link line is the target
|
|
of another.
|
|
.PP
|
|
Lines in the file that describes leap seconds have the following form:
|
|
.nf
|
|
.ti +.5i
|
|
.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
|
|
.sp
|
|
Leap YEAR MONTH DAY HH:MM:SS CORR R/S
|
|
.sp
|
|
For example:
|
|
.ti +.5i
|
|
.sp
|
|
Leap 2016 Dec 31 23:59:60 + S
|
|
.sp
|
|
.fi
|
|
The
|
|
.BR YEAR ,
|
|
.BR MONTH ,
|
|
.BR DAY ,
|
|
and
|
|
.B HH:MM:SS
|
|
fields tell when the leap second happened.
|
|
The
|
|
.B CORR
|
|
field
|
|
should be
|
|
.q "+"
|
|
if a second was added
|
|
or
|
|
.q "\*-"
|
|
if a second was skipped.
|
|
The
|
|
.B R/S
|
|
field
|
|
should be (an abbreviation of)
|
|
.q "Stationary"
|
|
if the leap second time given by the other fields should be interpreted as UTC
|
|
or
|
|
(an abbreviation of)
|
|
.q "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
|
|
.B zic
|
|
input, intended to illustrate many of its features.
|
|
In this example, the EU rules are for the European Union
|
|
and for its predecessor organization, the European Communities.
|
|
.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 1941 1942 \*- May Mon>=1 1:00 1:00 S
|
|
Rule Swiss 1941 1942 \*- Oct Mon>=1 2: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\0\0'u +\w'FORMAT\0\0'u
|
|
# Zone NAME UTOFF RULES FORMAT [UNTIL]
|
|
Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16
|
|
0:29:46 \*- BMT 1894 Jun
|
|
1:00 Swiss CE%sT 1981
|
|
1:00 EU CE%sT
|
|
.sp
|
|
Link Europe/Zurich Europe/Vaduz
|
|
.sp
|
|
.in
|
|
.fi
|
|
In this example, the timezone is named Europe/Zurich but it has an alias
|
|
as Europe/Vaduz. This example says that Zurich was 34 minutes and 8
|
|
seconds east of UT until 1853-07-16 at 00:00, when the legal offset
|
|
was changed to 7\(de\|26\(fm\|22.50\(sd; although this works out to
|
|
0:29:45.50, the input format cannot represent fractional seconds so it
|
|
is rounded here. After 1894-06-01 at 00:00 the UT offset became one hour
|
|
and Swiss daylight saving rules (defined with lines beginning with
|
|
.q "Rule Swiss")
|
|
apply. From 1981 to the present, EU daylight saving rules have
|
|
applied, and the UTC offset has remained at one hour.
|
|
.PP
|
|
In 1941 and 1942, daylight saving time applied from the first Monday
|
|
in May at 01:00 to the first Monday in October at 02: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,
|
|
.q "LMT"
|
|
and
|
|
.q "BMT"
|
|
were initially used, respectively. Since
|
|
Swiss rules and later EU rules were applied, the time zone abbreviation
|
|
has been CET for standard time and CEST for daylight saving
|
|
time.
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/localtime
|
|
Default local timezone file.
|
|
.TP
|
|
.I /usr/share/zoneinfo
|
|
Default timezone information directory.
|
|
.SH NOTES
|
|
For areas with more than two types of local time,
|
|
you may need to use local standard time in the
|
|
.B 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 timezone,
|
|
a clock advance caused by the start of daylight saving
|
|
coincides with and is equal to
|
|
a clock retreat caused by a change in UT offset,
|
|
.B zic
|
|
produces a single transition to daylight saving at the new UT offset
|
|
(without any change in wall clock time).
|
|
To get separate transitions
|
|
use multiple zone continuation lines
|
|
specifying transition instants using universal time.
|
|
.SH SEE ALSO
|
|
.BR tzfile (5),
|
|
.BR zdump (8)
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 2009-05-17 by Arthur David Olson.
|