diff options
Diffstat (limited to 'system_cmds/zic.tproj/zic.8')
| -rw-r--r-- | system_cmds/zic.tproj/zic.8 | 468 |
1 files changed, 468 insertions, 0 deletions
diff --git a/system_cmds/zic.tproj/zic.8 b/system_cmds/zic.tproj/zic.8 new file mode 100644 index 0000000..a84e563 --- /dev/null +++ b/system_cmds/zic.tproj/zic.8 @@ -0,0 +1,468 @@ +.\" $FreeBSD: head/contrib/tzcode/zic/zic.8 214411 2010-10-27 07:14:46Z edwin $ +.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 +Names (such as month names) must be in English and are case insensitive. +Abbreviations, if used, must be unambiguous in context. +.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.6 +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. |