logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zic.8 (24783B)


  1. .\" This file is in the public domain, so clarified as of
  2. .\" 2009-05-17 by Arthur David Olson.
  3. .TH zic 8 "" "Time Zone Database"
  4. .SH NAME
  5. zic \- timezone compiler
  6. .SH SYNOPSIS
  7. .B zic
  8. [
  9. .I option
  10. \&... ] [
  11. .I filename
  12. \&... ]
  13. .SH DESCRIPTION
  14. .ie '\(lq'' .ds lq \&"\"
  15. .el .ds lq \(lq\"
  16. .ie '\(rq'' .ds rq \&"\"
  17. .el .ds rq \(rq\"
  18. .de q
  19. \\$3\*(lq\\$1\*(rq\\$2
  20. ..
  21. .ie '\(la'' .ds < <
  22. .el .ds < \(la
  23. .ie '\(ra'' .ds > >
  24. .el .ds > \(ra
  25. .ie \n(.g .ds : \:
  26. .el .ds : .
  27. .ds d " degrees
  28. .ds m " minutes
  29. .ds s " seconds
  30. .ds _ " \&
  31. .if t \{\
  32. . if \n(.g .if c \(de .if c \(fm .if c \(sd \{\
  33. . ds d \(de
  34. . ds m \(fm
  35. . ds s \(sd
  36. . ds _ \|
  37. . \}
  38. .\}
  39. The
  40. .B zic
  41. program reads text from the file(s) named on the command line
  42. and creates the timezone information format (TZif) files
  43. specified in this input.
  44. If a
  45. .I filename
  46. is
  47. .q "\-" ,
  48. standard input is read.
  49. .SH OPTIONS
  50. .TP
  51. .B "\-\-version"
  52. Output version information and exit.
  53. .TP
  54. .B \-\-help
  55. Output short usage message and exit.
  56. .TP
  57. .BI "\-b " bloat
  58. Output backward-compatibility data as specified by
  59. .IR bloat .
  60. If
  61. .I bloat
  62. is
  63. .BR fat ,
  64. generate additional data entries that work around potential bugs or
  65. incompatibilities in older software, such as software that mishandles
  66. the 64-bit generated data.
  67. If
  68. .I bloat
  69. is
  70. .BR slim ,
  71. keep the output files small; this can help check for the bugs
  72. and incompatibilities.
  73. The default is
  74. .BR slim ,
  75. as software that mishandles 64-bit data typically
  76. mishandles timestamps after the year 2038 anyway.
  77. Also see the
  78. .B \-r
  79. option for another way to alter output size.
  80. .TP
  81. .BI "\-d " directory
  82. Create time conversion information files in the named directory rather than
  83. in the standard directory named below.
  84. .TP
  85. .BI "\-l " timezone
  86. Use
  87. .I timezone
  88. as local time.
  89. .B zic
  90. will act as if the input contained a link line of the form
  91. .sp
  92. .ti +2
  93. .ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u
  94. Link \fItimezone\fP localtime
  95. .sp
  96. If
  97. .I timezone
  98. is
  99. .BR \- ,
  100. any already-existing link is removed.
  101. .TP
  102. .BI "\-L " leapsecondfilename
  103. Read leap second information from the file with the given name.
  104. If this option is not used,
  105. no leap second information appears in output files.
  106. .TP
  107. .BI "\-p " timezone
  108. Use
  109. .IR timezone 's
  110. rules when handling nonstandard
  111. TZ strings like "EET\-2EEST" that lack transition rules.
  112. .B zic
  113. will act as if the input contained a link line of the form
  114. .sp
  115. .ti +2
  116. Link \fItimezone\fP posixrules
  117. .sp
  118. If
  119. .I timezone
  120. is
  121. .q "\-"
  122. (the default), any already-existing link is removed.
  123. .sp
  124. Unless
  125. .I timezone is
  126. .q "\-" ,
  127. this option is obsolete and poorly supported.
  128. Among other things it should not be used for timestamps after the year 2037,
  129. and it should not be combined with
  130. .B "\-b slim"
  131. if
  132. .IR timezone 's
  133. transitions are at standard time or Universal Time (UT) instead of local time.
  134. .TP
  135. .BR "\-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]"
  136. Limit the applicability of output files
  137. to timestamps in the range from
  138. .I lo
  139. (inclusive) to
  140. .I hi
  141. (exclusive), where
  142. .I lo
  143. and
  144. .I hi
  145. are possibly signed decimal counts of seconds since the Epoch
  146. (1970-01-01 00:00:00 UTC).
  147. Omitted counts default to extreme values.
  148. The output files use UT offset 0 and abbreviation
  149. .q "\-00"
  150. in place of the omitted timestamp data.
  151. For example,
  152. .q "zic \-r @0"
  153. omits data intended for negative timestamps (i.e., before the Epoch), and
  154. .q "zic \-r @0/@2147483648"
  155. outputs data intended only for nonnegative timestamps that fit into
  156. 31-bit signed integers.
  157. On platforms with GNU
  158. .BR date ,
  159. .q "zic \-r @$(date +%s)"
  160. omits data intended for past timestamps.
  161. Although this option typically reduces the output file's size,
  162. the size can increase due to the need to represent the timestamp range
  163. boundaries, particularly if
  164. .I hi
  165. causes a TZif file to contain explicit entries for
  166. .RI pre- hi
  167. transitions rather than concisely representing them
  168. with a proleptic TZ string.
  169. Also see the
  170. .B "\-b slim"
  171. option for another way to shrink output size.
  172. .TP
  173. .BI "\-R @" hi
  174. Generate redundant trailing explicit transitions for timestamps
  175. that occur less than
  176. .I hi
  177. seconds since the Epoch, even though the transitions could be
  178. more concisely represented via the proleptic TZ string.
  179. This option does not affect the represented timestamps.
  180. Although it accommodates nonstandard TZif readers
  181. that ignore the proleptic TZ string,
  182. it increases the size of the altered output files.
  183. .TP
  184. .BI "\-t " file
  185. When creating local time information, put the configuration link in
  186. the named file rather than in the standard location.
  187. .TP
  188. .B \-v
  189. Be more verbose, and complain about the following situations:
  190. .RS
  191. .PP
  192. The input specifies a link to a link,
  193. something not supported by some older parsers, including
  194. .B zic
  195. itself through release 2022e.
  196. .PP
  197. A year that appears in a data file is outside the range
  198. of representable years.
  199. .PP
  200. A time of 24:00 or more appears in the input.
  201. Pre-1998 versions of
  202. .B zic
  203. prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00.
  204. .PP
  205. A rule goes past the start or end of the month.
  206. Pre-2004 versions of
  207. .B zic
  208. prohibit this.
  209. .PP
  210. A time zone abbreviation uses a
  211. .B %z
  212. format.
  213. Pre-2015 versions of
  214. .B zic
  215. do not support this.
  216. .PP
  217. A timestamp contains fractional seconds.
  218. Pre-2018 versions of
  219. .B zic
  220. do not support this.
  221. .PP
  222. The input contains abbreviations that are mishandled by pre-2018 versions of
  223. .B zic
  224. due to a longstanding coding bug.
  225. These abbreviations include
  226. .q L
  227. for
  228. .q Link ,
  229. .q mi
  230. for
  231. .q min ,
  232. .q Sa
  233. for
  234. .q Sat ,
  235. and
  236. .q Su
  237. for
  238. .q Sun .
  239. .PP
  240. The output file does not contain all the information about the
  241. long-term future of a timezone, because the future cannot be summarized as
  242. a proleptic TZ string. For example, as of 2023 this problem
  243. occurs for Morocco's daylight-saving rules, as these rules are based
  244. on predictions for when Ramadan will be observed, something that
  245. a proleptic TZ string cannot represent.
  246. .PP
  247. The output contains data that may not be handled properly by client
  248. code designed for older
  249. .B zic
  250. output formats. These compatibility issues affect only timestamps
  251. before 1970 or after the start of 2038.
  252. .PP
  253. The output contains a truncated leap second table,
  254. which can cause some older TZif readers to misbehave.
  255. This can occur if the
  256. .B "\-L"
  257. option is used, and either an Expires line is present or
  258. the
  259. .B "\-r"
  260. option is also used.
  261. .PP
  262. The output file contains more than 1200 transitions,
  263. which may be mishandled by some clients.
  264. The current reference client supports at most 2000 transitions;
  265. pre-2014 versions of the reference client support at most 1200
  266. transitions.
  267. .PP
  268. A time zone abbreviation has fewer than 3 or more than 6 characters.
  269. POSIX requires at least 3, and requires implementations to support
  270. at least 6.
  271. .PP
  272. An output file name contains a byte that is not an ASCII letter,
  273. .q "\-" ,
  274. .q "/" ,
  275. or
  276. .q "_" ;
  277. or it contains a file name component that contains more than 14 bytes
  278. or that starts with
  279. .q "\-" .
  280. .RE
  281. .SH FILES
  282. Input files use the format described in this section; output files use
  283. .BR tzfile (5)
  284. format.
  285. .PP
  286. Input files should be text files, that is, they should be a series of
  287. zero or more lines, each ending in a newline byte and containing at
  288. most 2048 bytes counting the newline, and without any NUL bytes.
  289. The input text's encoding
  290. is typically UTF-8 or ASCII; it should have a unibyte representation
  291. for the POSIX Portable Character Set (PPCS)
  292. \*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
  293. and the encoding's non-unibyte characters should consist entirely of
  294. non-PPCS bytes. Non-PPCS characters typically occur only in comments:
  295. although output file names and time zone abbreviations can contain
  296. nearly any character, other software will work better if these are
  297. limited to the restricted syntax described under the
  298. .B \-v
  299. option.
  300. .PP
  301. Input lines are made up of fields.
  302. Fields are separated from one another by one or more white space characters.
  303. The white space characters are space, form feed, carriage return, newline,
  304. tab, and vertical tab.
  305. Leading and trailing white space on input lines is ignored.
  306. An unquoted sharp character (#) in the input introduces a comment which extends
  307. to the end of the line the sharp character appears on.
  308. White space characters and sharp characters may be enclosed in double quotes
  309. (") if they're to be used as part of a field.
  310. Any line that is blank (after comment stripping) is ignored.
  311. Nonblank lines are expected to be of one of three types:
  312. rule lines, zone lines, and link lines.
  313. .PP
  314. Names must be in English and are case insensitive.
  315. They appear in several contexts, and include month and weekday names
  316. and keywords such as
  317. .BR "maximum" ,
  318. .BR "only" ,
  319. .BR "Rolling" ,
  320. and
  321. .BR "Zone" .
  322. A name can be abbreviated by omitting all but an initial prefix; any
  323. abbreviation must be unambiguous in context.
  324. .PP
  325. A rule line has the form
  326. .nf
  327. .ti +2
  328. .ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\-\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
  329. .sp
  330. Rule NAME FROM TO \- IN ON AT SAVE LETTER/S
  331. .sp
  332. For example:
  333. .ti +2
  334. .sp
  335. Rule US 1967 1973 \- Apr lastSun 2:00w 1:00d D
  336. .sp
  337. .fi
  338. The fields that make up a rule line are:
  339. .TP
  340. .B NAME
  341. Gives the name of the rule set that contains this line.
  342. The name must start with a character that is neither
  343. an ASCII digit nor
  344. .q \-
  345. nor
  346. .q + .
  347. To allow for future extensions,
  348. an unquoted name should not contain characters from the set
  349. .ie \n(.g .q \f(CR!$%&\(aq()*,/:;<=>?@[\e]\(ha\(ga{|}\(ti\fP .
  350. .el .ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP .
  351. .el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ .
  352. .TP
  353. .B FROM
  354. Gives the first year in which the rule applies.
  355. Any signed integer year can be supplied; the proleptic Gregorian calendar
  356. is assumed, with year 0 preceding year 1.
  357. Rules can describe times that are not representable as time values,
  358. with the unrepresentable times ignored; this allows rules to be portable
  359. among hosts with differing time value types.
  360. .TP
  361. .B TO
  362. Gives the final year in which the rule applies.
  363. The word
  364. .B maximum
  365. (or an abbreviation) means the indefinite future, and the word
  366. .B only
  367. (or an abbreviation)
  368. may be used to repeat the value of the
  369. .B FROM
  370. field.
  371. .TP
  372. .B \-
  373. Is a reserved field and should always contain
  374. .q \-
  375. for compatibility with older versions of
  376. .BR zic .
  377. It was previously known as the
  378. .B TYPE
  379. field, which could contain values to allow a
  380. separate script to further restrict in which
  381. .q types
  382. of years the rule would apply.
  383. .TP
  384. .B IN
  385. Names the month in which the rule takes effect.
  386. Month names may be abbreviated as mentioned previously;
  387. for example, January can appear as
  388. .q January ,
  389. .q JANU
  390. or
  391. .q Ja ,
  392. but not as
  393. .q j
  394. which would be ambiguous with both June and July.
  395. .TP
  396. .B ON
  397. Gives the day on which the rule takes effect.
  398. Recognized forms include:
  399. .nf
  400. .in +2
  401. .sp
  402. .ta \w'Sun<=25\0\0'u
  403. 5 the fifth of the month
  404. lastSun the last Sunday in the month
  405. lastMon the last Monday in the month
  406. Sun>=8 first Sunday on or after the eighth
  407. Sun<=25 last Sunday on or before the 25th
  408. .fi
  409. .in
  410. .sp
  411. A weekday name (e.g.,
  412. .BR "Sunday" )
  413. or a weekday name preceded by
  414. .q "last"
  415. (e.g.,
  416. .BR "lastSunday" )
  417. may be abbreviated as mentioned previously,
  418. e.g.,
  419. .q Su
  420. for Sunday and
  421. .q lastsa
  422. for the last Saturday.
  423. There must be no white space characters within the
  424. .B ON
  425. field.
  426. The
  427. .q <=
  428. and
  429. .q >=
  430. constructs can result in a day in the neighboring month;
  431. for example, the IN-ON combination
  432. .q "Oct Sun>=31"
  433. stands for the first Sunday on or after October 31,
  434. even if that Sunday occurs in November.
  435. .TP
  436. .B AT
  437. Gives the time of day at which the rule takes effect,
  438. relative to 00:00, the start of a calendar day.
  439. Recognized forms include:
  440. .nf
  441. .in +2
  442. .sp
  443. .ta \w'00:19:32.13\0\0'u
  444. 2 time in hours
  445. 2:00 time in hours and minutes
  446. 01:28:14 time in hours, minutes, and seconds
  447. 00:19:32.13 time with fractional seconds
  448. 12:00 midday, 12 hours after 00:00
  449. 15:00 3 PM, 15 hours after 00:00
  450. 24:00 end of day, 24 hours after 00:00
  451. 260:00 260 hours after 00:00
  452. \-2:30 2.5 hours before 00:00
  453. \- equivalent to 0
  454. .fi
  455. .in
  456. .sp
  457. Although
  458. .B zic
  459. rounds times to the nearest integer second
  460. (breaking ties to the even integer), the fractions may be useful
  461. to other applications requiring greater precision.
  462. The source format does not specify any maximum precision.
  463. Any of these forms may be followed by the letter
  464. .B w
  465. if the given time is local or
  466. .q "wall clock"
  467. time,
  468. .B s
  469. if the given time is standard time without any adjustment for daylight saving,
  470. or
  471. .B u
  472. (or
  473. .B g
  474. or
  475. .BR z )
  476. if the given time is universal time;
  477. in the absence of an indicator,
  478. local (wall clock) time is assumed.
  479. These forms ignore leap seconds; for example,
  480. if a leap second occurs at 00:59:60 local time,
  481. .q "1:00"
  482. stands for 3601 seconds after local midnight instead of the usual 3600 seconds.
  483. The intent is that a rule line describes the instants when a
  484. clock/calendar set to the type of time specified in the
  485. .B AT
  486. field would show the specified date and time of day.
  487. .TP
  488. .B SAVE
  489. Gives the amount of time to be added to local standard time when the rule is in
  490. effect, and whether the resulting time is standard or daylight saving.
  491. This field has the same format as the
  492. .B AT
  493. field
  494. except with a different set of suffix letters:
  495. .B s
  496. for standard time and
  497. .B d
  498. for daylight saving time.
  499. The suffix letter is typically omitted, and defaults to
  500. .B s
  501. if the offset is zero and to
  502. .B d
  503. otherwise.
  504. Negative offsets are allowed; in Ireland, for example, daylight saving
  505. time is observed in winter and has a negative offset relative to
  506. Irish Standard Time.
  507. The offset is merely added to standard time; for example,
  508. .B zic
  509. does not distinguish a 10:30 standard time plus an 0:30
  510. .B SAVE
  511. from a 10:00 standard time plus a 1:00
  512. .BR SAVE .
  513. .TP
  514. .B LETTER/S
  515. Gives the
  516. .q "variable part"
  517. (for example, the
  518. .q "S"
  519. or
  520. .q "D"
  521. in
  522. .q "EST"
  523. or
  524. .q "EDT" )
  525. of time zone abbreviations to be used when this rule is in effect.
  526. If this field is
  527. .q \- ,
  528. the variable part is null.
  529. .PP
  530. A zone line has the form
  531. .sp
  532. .nf
  533. .ti +2
  534. .ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u
  535. Zone NAME STDOFF RULES FORMAT [UNTIL]
  536. .sp
  537. For example:
  538. .sp
  539. .ti +2
  540. Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00
  541. .sp
  542. .fi
  543. The fields that make up a zone line are:
  544. .TP
  545. .B NAME
  546. The name of the timezone.
  547. This is the name used in creating the time conversion information file for the
  548. timezone.
  549. It should not contain a file name component
  550. .q ".\&"
  551. or
  552. .q ".." ;
  553. a file name component is a maximal substring that does not contain
  554. .q "/" .
  555. .TP
  556. .B STDOFF
  557. The amount of time to add to UT to get standard time,
  558. without any adjustment for daylight saving.
  559. This field has the same format as the
  560. .B AT
  561. and
  562. .B SAVE
  563. fields of rule lines, except without suffix letters;
  564. begin the field with a minus sign if time must be subtracted from UT.
  565. .TP
  566. .B RULES
  567. The name of the rules that apply in the timezone or,
  568. alternatively, a field in the same format as a rule-line
  569. .B SAVE
  570. field,
  571. giving the amount of time to be added to local standard time
  572. and whether the resulting time is standard or daylight saving.
  573. Standard time applies if this field is
  574. .B \-
  575. or for timestamps occurring before any rule takes effect.
  576. When an amount of time is given, only the sum of standard time and
  577. this amount matters.
  578. .TP
  579. .B FORMAT
  580. The format for time zone abbreviations.
  581. The pair of characters
  582. .B %s
  583. shows where to put the time zone abbreviation's variable part,
  584. which is taken from the
  585. .B LETTER/S
  586. field of the corresponding rule;
  587. any timestamps that precede the earliest rule use the
  588. .B LETTER/S
  589. of the earliest standard-time rule (which in this case must exist).
  590. Alternatively, a format can use the pair of characters
  591. .B %z
  592. to stand for the UT offset in the form
  593. .RI \(+- hh ,
  594. .RI \(+- hhmm ,
  595. or
  596. .RI \(+- hhmmss ,
  597. using the shortest form that does not lose information, where
  598. .IR hh ,
  599. .IR mm ,
  600. and
  601. .I ss
  602. are the hours, minutes, and seconds east (+) or west (\-) of UT.
  603. Alternatively,
  604. a slash (/)
  605. separates standard and daylight abbreviations.
  606. To conform to POSIX, a time zone abbreviation should contain only
  607. alphanumeric ASCII characters,
  608. .q "+"
  609. and
  610. .q "\-".
  611. By convention, the time zone abbreviation
  612. .q "\-00"
  613. is a placeholder that means local time is unspecified.
  614. .TP
  615. .B UNTIL
  616. The time at which the UT offset or the rule(s) change for a location.
  617. It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]].
  618. If this is specified,
  619. the time zone information is generated from the given UT offset
  620. and rule change until the time specified, which is interpreted using
  621. the rules in effect just before the transition.
  622. The month, day, and time of day have the same format as the IN, ON, and AT
  623. fields of a rule; trailing fields can be omitted, and default to the
  624. earliest possible value for the missing fields.
  625. .IP
  626. The next line must be a
  627. .q "continuation"
  628. line; this has the same form as a zone line except that the
  629. string
  630. .q "Zone"
  631. and the name are omitted, as the continuation line will
  632. place information starting at the time specified as the
  633. .q "until"
  634. information in the previous line in the file used by the previous line.
  635. Continuation lines may contain
  636. .q "until"
  637. information, just as zone lines do, indicating that the next line is a further
  638. continuation.
  639. .PP
  640. If a zone changes at the same instant that a rule would otherwise take
  641. effect in the earlier zone or continuation line, the rule is ignored.
  642. A zone or continuation line
  643. .I L
  644. with a named rule set starts with standard time by default:
  645. that is, any of
  646. .IR L 's
  647. timestamps preceding
  648. .IR L 's
  649. earliest rule use the rule in effect after
  650. .IR L 's
  651. first transition into standard time.
  652. In a single zone it is an error if two rules take effect at the same
  653. instant, or if two zone changes take effect at the same instant.
  654. .PP
  655. If a continuation line subtracts
  656. .I N
  657. seconds from the UT offset after a transition that would be
  658. interpreted to be later if using the continuation line's UT offset and
  659. rules, the
  660. .q "until"
  661. time of the previous zone or continuation line is interpreted
  662. according to the continuation line's UT offset and rules, and any rule
  663. that would otherwise take effect in the next
  664. .I N
  665. seconds is instead assumed to take effect simultaneously.
  666. For example:
  667. .br
  668. .ne 7
  669. .nf
  670. .in +2
  671. .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
  672. .sp
  673. # Rule NAME FROM TO \- IN ON AT SAVE LETTER/S
  674. Rule US 1967 2006 - Oct lastSun 2:00 0 S
  675. Rule US 1967 1973 - Apr lastSun 2:00 1:00 D
  676. .ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u
  677. # Zone NAME STDOFF RULES FORMAT [UNTIL]
  678. Zone America/Menominee \-5:00 \- EST 1973 Apr 29 2:00
  679. \-6:00 US C%sT
  680. .sp
  681. .in
  682. .fi
  683. Here, an incorrect reading would be there were two clock changes on 1973-04-29,
  684. the first from 02:00 EST (\-05) to 01:00 CST (\-06),
  685. and the second an hour later from 02:00 CST (\-06) to 03:00 CDT (\-05).
  686. However,
  687. .B zic
  688. interprets this more sensibly as a single transition from 02:00 CST (\-05) to
  689. 02:00 CDT (\-05).
  690. .PP
  691. A link line has the form
  692. .sp
  693. .nf
  694. .ti +2
  695. .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u
  696. Link TARGET LINK-NAME
  697. .sp
  698. For example:
  699. .sp
  700. .ti +2
  701. Link Europe/Istanbul Asia/Istanbul
  702. .sp
  703. .fi
  704. The
  705. .B TARGET
  706. field should appear as the
  707. .B NAME
  708. field in some zone line or as the
  709. .B LINK-NAME
  710. field in some link line.
  711. The
  712. .B LINK-NAME
  713. field is used as an alternative name for that zone;
  714. it has the same syntax as a zone line's
  715. .B NAME
  716. field.
  717. Links can chain together, although the behavior is unspecified if a
  718. chain of one or more links does not terminate in a Zone name.
  719. A link line can appear before the line that defines the link target.
  720. For example:
  721. .sp
  722. .ne 3
  723. .nf
  724. .in +2
  725. .ta \w'Zone\0\0'u +\w'Greenwich\0\0'u
  726. Link Greenwich G_M_T
  727. Link Etc/GMT Greenwich
  728. Zone Etc/GMT\0\00\0\0\-\0\0GMT
  729. .sp
  730. .in
  731. .fi
  732. The two links are chained together, and G_M_T, Greenwich, and Etc/GMT
  733. all name the same zone.
  734. .PP
  735. Except for continuation lines,
  736. lines may appear in any order in the input.
  737. However, the behavior is unspecified if multiple zone or link lines
  738. define the same name.
  739. .PP
  740. The file that describes leap seconds can have leap lines and an
  741. expiration line.
  742. Leap lines have the following form:
  743. .nf
  744. .ti +2
  745. .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
  746. .sp
  747. Leap YEAR MONTH DAY HH:MM:SS CORR R/S
  748. .sp
  749. For example:
  750. .ti +2
  751. .sp
  752. Leap 2016 Dec 31 23:59:60 + S
  753. .sp
  754. .fi
  755. The
  756. .BR YEAR ,
  757. .BR MONTH ,
  758. .BR DAY ,
  759. and
  760. .B HH:MM:SS
  761. fields tell when the leap second happened.
  762. The
  763. .B CORR
  764. field
  765. should be
  766. .q "+"
  767. if a second was added
  768. or
  769. .q "\-"
  770. if a second was skipped.
  771. The
  772. .B R/S
  773. field
  774. should be (an abbreviation of)
  775. .q "Stationary"
  776. if the leap second time given by the other fields should be interpreted as UTC
  777. or
  778. (an abbreviation of)
  779. .q "Rolling"
  780. if the leap second time given by the other fields should be interpreted as
  781. local (wall clock) time.
  782. .PP
  783. Rolling leap seconds would let one see
  784. Times Square ball drops where there'd be a
  785. .q "3... 2... 1... leap... Happy New Year"
  786. countdown, placing the leap second at
  787. midnight New York time rather than midnight UTC.
  788. Although stationary leap seconds are the common practice,
  789. rolling leap seconds can be useful in specialized applications
  790. like SMPTE timecodes that may prefer to put leap second
  791. discontinuities at the end of a local broadcast day.
  792. However, rolling leap seconds are not supported if the
  793. .B \-r
  794. option is used.
  795. .PP
  796. The expiration line, if present, has the form:
  797. .nf
  798. .ti +2
  799. .ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u
  800. .sp
  801. Expires YEAR MONTH DAY HH:MM:SS
  802. .sp
  803. For example:
  804. .ti +2
  805. .sp
  806. Expires 2020 Dec 28 00:00:00
  807. .sp
  808. .fi
  809. The
  810. .BR YEAR ,
  811. .BR MONTH ,
  812. .BR DAY ,
  813. and
  814. .B HH:MM:SS
  815. fields give the expiration timestamp in UTC for the leap second table.
  816. .br
  817. .ne 22
  818. .SH "EXTENDED EXAMPLE"
  819. Here is an extended example of
  820. .B zic
  821. input, intended to illustrate many of its features.
  822. .nf
  823. .in +2
  824. .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
  825. .sp
  826. # Rule NAME FROM TO \- IN ON AT SAVE LETTER/S
  827. Rule Swiss 1941 1942 \- May Mon>=1 1:00 1:00 S
  828. Rule Swiss 1941 1942 \- Oct Mon>=1 2:00 0 \-
  829. .sp .5
  830. Rule EU 1977 1980 \- Apr Sun>=1 1:00u 1:00 S
  831. Rule EU 1977 only \- Sep lastSun 1:00u 0 \-
  832. Rule EU 1978 only \- Oct 1 1:00u 0 \-
  833. Rule EU 1979 1995 \- Sep lastSun 1:00u 0 \-
  834. Rule EU 1981 max \- Mar lastSun 1:00u 1:00 S
  835. Rule EU 1996 max \- Oct lastSun 1:00u 0 \-
  836. .sp
  837. .ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:29:45.50\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u
  838. # Zone NAME STDOFF RULES FORMAT [UNTIL]
  839. Zone Europe/Zurich 0:34:08 \- LMT 1853 Jul 16
  840. 0:29:45.50 \- BMT 1894 Jun
  841. 1:00 Swiss CE%sT 1981
  842. 1:00 EU CE%sT
  843. .sp
  844. Link Europe/Zurich Europe/Vaduz
  845. .sp
  846. .in
  847. .fi
  848. In this example, the EU rules are for the European Union
  849. and for its predecessor organization, the European Communities.
  850. The timezone is named Europe/Zurich and it has the alias Europe/Vaduz.
  851. This example says that Zurich was 34 minutes and 8
  852. seconds east of UT until 1853-07-16 at 00:00, when the legal offset
  853. was changed to
  854. 7\*d\*_26\*m\*_22.50\*s,
  855. which works out to 0:29:45.50;
  856. .B zic
  857. treats this by rounding it to 0:29:46.
  858. After 1894-06-01 at 00:00 the UT offset became one hour
  859. and Swiss daylight saving rules (defined with lines beginning with
  860. .q "Rule Swiss")
  861. apply. From 1981 to the present, EU daylight saving rules have
  862. applied, and the UTC offset has remained at one hour.
  863. .PP
  864. In 1941 and 1942, daylight saving time applied from the first Monday
  865. in May at 01:00 to the first Monday in October at 02:00.
  866. The pre-1981 EU daylight-saving rules have no effect
  867. here, but are included for completeness. Since 1981, daylight
  868. saving has begun on the last Sunday in March at 01:00 UTC.
  869. Until 1995 it ended the last Sunday in September at 01:00 UTC,
  870. but this changed to the last Sunday in October starting in 1996.
  871. .PP
  872. For purposes of display,
  873. .q "LMT"
  874. and
  875. .q "BMT"
  876. were initially used, respectively. Since
  877. Swiss rules and later EU rules were applied, the time zone abbreviation
  878. has been CET for standard time and CEST for daylight saving
  879. time.
  880. .SH FILES
  881. .TP
  882. .I /etc/localtime
  883. Default local timezone file.
  884. .TP
  885. .I /usr/share/zoneinfo
  886. Default timezone information directory.
  887. .SH NOTES
  888. For areas with more than two types of local time,
  889. you may need to use local standard time in the
  890. .B AT
  891. field of the earliest transition time's rule to ensure that
  892. the earliest transition time recorded in the compiled file is correct.
  893. .PP
  894. If,
  895. for a particular timezone,
  896. a clock advance caused by the start of daylight saving
  897. coincides with and is equal to
  898. a clock retreat caused by a change in UT offset,
  899. .B zic
  900. produces a single transition to daylight saving at the new UT offset
  901. without any change in local (wall clock) time.
  902. To get separate transitions
  903. use multiple zone continuation lines
  904. specifying transition instants using universal time.
  905. .SH SEE ALSO
  906. .BR tzfile (5),
  907. .BR zdump (8)