diff options
Diffstat (limited to 'zic.8')
| -rw-r--r-- | zic.8 | 599 |
1 files changed, 599 insertions, 0 deletions
diff --git a/zic.8 b/zic.8 new file mode 100644 index 000000000000..d105b24002cc --- /dev/null +++ b/zic.8 @@ -0,0 +1,599 @@ +.TH ZIC 8 +.SH NAME +zic \- time zone 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 - \- +.\} +.I Zic +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 "\*-" , +the standard input is read. +.PP +These options are available: +.TP +.BI "\*-\*-version" +Output version information 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 the given time zone as local time. +.I 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 the given time zone's rules when handling POSIX-format +time zone environment variables. +.I Zic +will act as if the input contained a link line of the form +.sp +.ti +.5i +Link \fItimezone\fP posixrules +.TP +.BI "\*-t " file +When creating local time information, put the configuration link in +the named file rather than in the standard location. +.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 +.IR time (2) +values. +.PP +A time of 24:00 or more appears in the input. +Pre-1998 versions of +.I 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 +.I zic +prohibit this. +.PP +The output file does not contain all the information about the +long-term future of a zone, 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 +.I zic +output formats. These compatibility issues affect only time stamps +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. +Non-blank 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:00s\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:00s 1:00d D +.sp +.fi +The fields that make up a rule line are: +.TP "\w'LETTER/S'u" +.B NAME +Gives the (arbitrary) name of the set of rules this rule is part of. +.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 +.I 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 +00:19:32.13 time with fractional 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. +Although +.I zic +rounds times to the nearest integer second +(breaking ties to the even integer), the fractions may be useful +to other applications requiring greater precision. +The source format does not specify any maximum precision. +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, and whether the resulting time is standard or daylight saving. +This field has the same format as the +.B AT +field +except with a different set of suffix letters: +.B s +for standard time and +.B d +for daylight saving time. +The suffix letter is typically omitted, and defaults to +.B s +if the offset is zero and to +.B d +otherwise. +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, +.I 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'GMTOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u +Zone NAME GMTOFF 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'GMTOFF'u" +.B NAME +The name of the time zone. +This is the name used in creating the time conversion information file for the +zone. +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 GMTOFF +The amount of time to add to UT to get standard time in this zone. +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 time zone 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 in the time zone. +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 in this time zone. +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, "+" and "\*-". +.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 +.I 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'GMTOFF\0\0'u +\w'0:34:08\0\0'u +\w'FORMAT\0\0'u +# Zone NAME GMTOFF 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 zone 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 "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, "LMT" and "BMT" were initially used, respectively. Since +Swiss rules and later EU rules were applied, the display name for the +time zone 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 +.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 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 UT offset, +.IR 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. +.PP +Time stamps well before the Big Bang are silently omitted from the output. +This works around bugs in software that mishandles large negative time +stamps. Call it sour grapes, but pre-Big-Bang time stamps are +physically suspect anyway. The pre-Big-Bang cutoff time is +approximate and may change in future versions. +.SH FILES +.ta \w'/usr/share/zoneinfo\0\0'u +/etc/localtime default local time zone file +/usr/share/zoneinfo default time zone information directory +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8) +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. |