1.\" $NetBSD: zic.8,v 1.14 2003/12/20 00:12:05 kleink Exp $ 2.\" @(#)zic.8 7.22 3.Dd December 20, 2003 4.Os 5.Dt ZIC 8 6.Sh NAME 7.Nm zic 8.Nd time zone compiler 9.Sh SYNOPSIS 10.Nm 11.Op Fl \-version 12.Op Fl d Ar directory 13.Op Fl L Ar leapsecondfilename 14.Op Fl l Ar localtime 15.Op Fl p Ar posixrules 16.Op Fl s 17.Op Fl v 18.Op Fl y Ar command 19.Op Ar Filename ... 20.Sh DESCRIPTION 21.Nm 22reads text from the file(s) named on the command line 23and creates the time conversion information files specified in this input. 24If a 25.Ar filename 26is 27.Ar \&- , 28the standard input is read. 29.Pp 30These options are available: 31.Bl -tag -width XXXXXXXXXX -compact 32.It Fl \-version 33Output version information and exit. 34.It Fl d Ar directory 35Create time conversion information files in the named directory rather than 36in the standard directory named below. 37.It Fl L Ar leapsecondfilename 38Read leap second information from the file with the given name. 39If this option is not used, 40no leap second information appears in output files. 41.It Fl l Ar timezone 42Use the given time zone as local time. 43.Nm 44will act as if the input contained a link line of the form 45.Dl Link timezone localtime 46.It Fl p Ar timezone 47Use the given time zone's rules when handling POSIX-format 48time zone environment variables. 49.Nm 50will act as if the input contained a link line of the form 51.Dl Link timezone posixrules 52.It Fl s 53Limit time values stored in output files to values that are the same 54whether they're taken to be signed or unsigned. 55You can use this option to generate SVVS-compatible files. 56.It Fl v 57Complain if a year that appears in a data file is outside the range 58of years representable by 59.Xr time 3 60values. 61Also complain if a time of 24:00 62.Pq which cannot be handled by pre-1998 versions of Nm 63appears in the input. 64.It Fl y Ar command 65Use the given 66.Ar command 67rather than 68.Em yearistype 69when checking year types (see below). 70.Pp 71Input lines are made up of fields. 72Fields are separated from one another by any number of white space characters. 73Leading and trailing white space on input lines is ignored. 74An unquoted sharp character (#) in the input introduces a comment which extends 75to the end of the line the sharp character appears on. 76White space characters and sharp characters may be enclosed in double 77quotes 78.Pq \&" 79.\" XXX " 80if they're to be used as part of a field. 81Any line that is blank (after comment stripping) is ignored. 82Non-blank lines are expected to be of one of three types: 83rule lines, zone lines, and link lines. 84.Pp 85A rule line has the form 86.Dl Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 87For example: 88.Dl Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D 89The fields that make up a rule line are: 90.Bl -tag -width "LETTER/S" -compact 91.It NAME 92Gives the (arbitrary) name of the set of rules this rule is part of. 93.It FROM 94Gives the first year in which the rule applies. 95Any integer year can be supplied; the Gregorian calendar is assumed. 96The word 97.Em minimum 98(or an abbreviation) means the minimum year representable as an integer. 99The word 100.Em maximum 101(or an abbreviation) means the maximum year representable as an integer. 102Rules can describe times that are not representable as time values, 103with the unrepresentable times ignored; this allows rules to be portable 104among hosts with differing time value types. 105.It TO 106Gives the final year in which the rule applies. 107In addition to 108.Em minimum 109and 110.Em maximum 111(as above), 112the word 113.Em only 114(or an abbreviation) 115may be used to repeat the value of the 116.Em FROM 117field. 118.It TYPE 119Gives the type of year in which the rule applies. 120If 121.Em TYPE 122is 123.Em \&- 124then the rule applies in all years between 125.Em FROM 126and 127.Em TO 128inclusive. 129If 130.Em TYPE 131is something else, then 132.Nm 133executes the command 134.Pp 135.Ic yearistype Ar year type 136.Pp 137to check the type of a year: 138an exit status of zero is taken to mean that the year is of the given type; 139an exit status of one is taken to mean that the year is not of the given type. 140.It IN 141Names the month in which the rule takes effect. 142Month names may be abbreviated. 143.It ON 144Gives the day on which the rule takes effect. 145Recognized forms include: 146.Bl -tag -width lastSun -compact -offset indent 147.It 5 148the fifth of the month 149.It lastSun 150the last Sunday in the month 151.It lastMon 152the last Monday in the month 153.It Sun\*[Ge]8 154first Sunday on or after the eighth 155.It Sun\*[Le]25 156last Sunday on or before the 25th 157.El 158Names of days of the week may be abbreviated or spelled out in full. 159Note that there must be no spaces within the 160.Em ON 161field. 162.It AT 163Gives the time of day at which the rule takes effect. 164Recognized forms include: 165.Bl -tag -width "1X28X14" -compact -offset indent 166.It 2 167time in hours 168.It 2:00 169time in hours and minutes 170.It 15:00 17124-hour format time (for times after noon) 172.It 1:28:14 173time in hours, minutes, and seconds 174.It \- 175equivalent to 0 176.El 177where hour 0 is midnight at the start of the day, 178and hour 24 is midnight at the end of the day. 179Any of these forms may be followed by the letter 180.Em w 181if the given time is local 182.Dq wall clock 183time, 184.Em s 185if the given time is local 186.Dq standard 187time, or 188.Em u 189(or 190.Em g 191or 192.Em z ) 193if the given time is universal time; 194in the absence of an indicator, 195wall clock time is assumed. 196.It SAVE 197Gives the amount of time to be added to local standard time when the rule is in 198effect. 199This field has the same format as the 200.Em AT 201field 202(although, of course, the 203.Em w 204and 205.Em s 206suffixes are not used). 207.It LETTER/S 208Gives the 209.Dq variable part 210(for example, the 211.Dq S 212or 213.Dq D 214in 215.Dq EST 216or 217.Dq EDT ) 218of time zone abbreviations to be used when this rule is in effect. 219If this field is 220.Em \&- , 221the variable part is null. 222.El 223.Pp 224A zone line has the form 225.Dl Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] 226For example: 227.Dl Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 228The fields that make up a zone line are: 229.Bl -tag -width "RULES/SAVE" -compact 230.It NAME 231The name of the time zone. 232This is the name used in creating the time conversion information file for the 233zone. 234.It GMTOFF 235The amount of time to add to UTC to get standard time in this zone. 236This field has the same format as the 237.Em AT 238and 239.Em SAVE 240fields of rule lines; 241begin the field with a minus sign if time must be subtracted from UTC. 242.It RULES/SAVE 243The name of the rule(s) that apply in the time zone or, 244alternatively, an amount of time to add to local standard time. 245If this field is 246.Em \&- 247then standard time always applies in the time zone. 248.It FORMAT 249The format for time zone abbreviations in this time zone. 250The pair of characters 251.Em %s 252is used to show where the 253.Dq variable part 254of the time zone abbreviation goes. 255Alternatively, 256a slash 257.Pq \&/ 258separates standard and daylight abbreviations. 259.It UNTIL 260The time at which the UTC offset or the rule(s) change for a location. 261It is specified as a year, a month, a day, and a time of day. 262If this is specified, 263the time zone information is generated from the given UTC offset 264and rule change until the time specified. 265The month, day, and time of day have the same format as the IN, ON, and AT 266columns of a rule; trailing columns can be omitted, and default to the 267earliest possible value for the missing columns. 268.El 269The next line must be a 270.Dq continuation 271line; this has the same form as a zone line except that the 272string 273.Dq Zone 274and the name are omitted, as the continuation line will 275place information starting at the time specified as the 276.Em UNTIL 277field in the previous line in the file used by the previous line. 278Continuation lines may contain an 279.Em UNTIL 280field, just as zone lines do, indicating that the next line is a further 281continuation. 282.Pp 283A link line has the form 284.Dl Link LINK-FROM LINK-TO 285For example: 286.Dl Link Europe/Istanbul Asia/Istanbul 287The 288.Em LINK-FROM 289field should appear as the 290.Em NAME 291field in some zone line; 292the 293.Em LINK-TO 294field is used as an alternative name for that zone. 295.Pp 296Except for continuation lines, 297lines may appear in any order in the input. 298.Pp 299Lines in the file that describes leap seconds have the following form: 300.Dl Leap YEAR MONTH DAY HH:MM:SS CORR R/S 301For example: 302.Dl Leap 1974 Dec 31 23:59:60 + S 303The 304.Em YEAR , 305.Em MONTH , 306.Em DAY , 307and 308.Em HH:MM:SS 309fields tell when the leap second happened. 310The 311.Em CORR 312field 313should be 314.Dq \&+ 315if a second was added 316or 317.Dq \&- 318if a second was skipped. 319.\" There's no need to document the following, since it's impossible for more 320.\" than one leap second to be inserted or deleted at a time. 321.\" The C Standard is in error in suggesting the possibility. 322.\" See Terry J Quinn, The BIPM and the accurate measure of time, 323.\" Proc IEEE 79, 7 (July 1991), 894-905. 324.\" or 325.\" .Dq ++ 326.\" if two seconds were added 327.\" or 328.\" .Dq -- 329.\" if two seconds were skipped. 330The 331.Em R/S 332field 333should be (an abbreviation of) 334.Dq Stationary 335if the leap second time given by the other fields should be interpreted as UTC 336or 337(an abbreviation of) 338.Dq Rolling 339if the leap second time given by the other fields should be interpreted as 340local wall clock time. 341.El 342.Sh NOTES 343For areas with more than two types of local time, 344you may need to use local standard time in the 345.Em AT 346field of the earliest transition time's rule to ensure that 347the earliest transition time recorded in the compiled file is correct. 348.Sh FILES 349.Pa /usr/share/zoneinfo 350- standard directory used for created files 351.Sh SEE ALSO 352.Xr ctime 3 , 353.Xr tzfile 5 , 354.Xr zdump 8 355