From 24e14ed0b3bf907f11b574fd2e1bdf7bbf2fff2b Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 27 Apr 2020 07:24:29 +0200
Subject: [PATCH] zic.8: Sync to 2020a tzdb release

From https://www.iana.org/time-zones, version 2020a.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man8/zic.8 | 288 +++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 234 insertions(+), 54 deletions(-)

diff --git a/man8/zic.8 b/man8/zic.8
index 157fe0982..3f8141a7a 100644
--- a/man8/zic.8
+++ b/man8/zic.8
@@ -2,7 +2,7 @@
 .\" This page is in the public domain
 .\" %%%LICENSE_END
 .\"
-.TH ZIC 8 2019-03-06 "" "Linux System Administration"
+.TH ZIC 8 2020-04-27 "" "Linux System Administration"
 .SH NAME
 zic \- timezone compiler
 .SH SYNOPSIS
@@ -49,6 +49,32 @@ Output version information and exit.
 .B \*-\*-help
 Output short usage message and exit.
 .TP
+.BI "\*-b " bloat
+Output backward-compatibility data as specified by
+.IR bloat .
+If
+.I bloat
+is
+.BR fat ,
+generate additional data entries that work around potential bugs or
+incompatibilities in older software, such as software that mishandles
+the 64-bit generated data.
+If
+.I bloat
+is
+.BR slim ,
+keep the output files small; this can help check for the bugs
+and incompatibilities.
+Although the default is currently
+.BR fat ,
+this is intended to change in future
+.B zic
+versions, as software that mishandles the 64-bit data typically
+mishandles timestamps after the year 2038 anyway.
+Also see the
+.B \*-r
+option for another way to shrink output size.
+.TP
 .BI "\*-d " directory
 Create time conversion information files in the named directory rather than
 in the standard directory named below.
@@ -61,24 +87,64 @@ as local time.
 will act as if the input contained a link line of the form
 .sp
 .ti +.5i
+.ta \w'Link\0\0'u  +\w'\fItimezone\fP\0\0'u
 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
+.BI "\*-p " timezone
+Use
+.IR timezone 's
+rules when handling nonstandard
+TZ strings like "EET\*-2EEST" that lack transition rules.
+.B zic
+will act as if the input contained a link line of the form
+.sp
+.ti +.5i
+Link	\fItimezone\fP		posixrules
+.sp
+This feature is obsolete and poorly supported.
+Among other things it should not be used for timestamps after the year 2037,
+and it should not be combined with
+.B "\*-b slim"
+if
+.IR timezone 's
+transitions are at standard time or Universal Time (UT) instead of local time.
+.TP
+.BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]"
+Reduce the size of output files by limiting their applicability
+to timestamps in the range from
+.I lo
+(inclusive) to
+.I hi
+(exclusive), where
+.I lo
+and
+.I hi
+are possibly-signed decimal counts of seconds since the Epoch
+(1970-01-01 00:00:00 UTC).
+Omitted counts default to extreme values.
+For example,
+.q "zic \*-r @0"
+omits data intended for negative timestamps (i.e., before the Epoch), and
+.q "zic \*-r @0/@2147483648"
+outputs data intended only for nonnegative timestamps that fit into
+31-bit signed integers.
+On platforms with GNU
+.BR date ,
+.q "zic \-r @$(date +%s)"
+omits data intended for past timestamps.
+Also see the
+.B "\*-b slim"
+option for another way to shrink output size.
+.TP
+.BI "\*-t " file
+When creating local time information, put the configuration link in
+the named file rather than in the standard location.
+.TP
 .B \*-v
 Be more verbose, and complain about the following situations:
 .RS
@@ -86,9 +152,7 @@ Be more verbose, and complain about the following situations:
 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.
+of representable years.
 .PP
 A time of 24:00 or more appears in the input.
 Pre-1998 versions of
@@ -100,9 +164,39 @@ Pre-2004 versions of
 .B zic
 prohibit this.
 .PP
+A time zone abbreviation uses a
+.B %z
+format.
+Pre-2015 versions of
+.B zic
+do not support this.
+.PP
+A timestamp contains fractional seconds.
+Pre-2018 versions of
+.B zic
+do not support this.
+.PP
+The input contains abbreviations that are mishandled by pre-2018 versions of
+.B zic
+due to a longstanding coding bug.
+These abbreviations include
+.q L
+for
+.q Link ,
+.q mi
+for
+.q min ,
+.q Sa
+for
+.q Sat ,
+and
+.q Su
+for
+.q Sun .
+.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
+an extended POSIX TZ string.  For example, as of 2019 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.
@@ -113,8 +207,15 @@ code designed for older
 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.
+The output file contains more than 1200 transitions,
+which may be mishandled by some clients.
+The current reference client supports at most 2000 transitions;
+pre-2014 versions of the reference client support at most 1200
+transitions.
+.PP
+A time zone abbreviation has fewer than 3 or more than 6 characters.
+POSIX requires at least 3, and requires implementations to support
+at least 6.
 .PP
 An output file name contains a byte that is not an ASCII letter,
 .q "\*-" ,
@@ -125,11 +226,10 @@ 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.
+.SH FILES
+Input files use the format described in this section; output files use
+.IR tzfile (5)
+format.
 .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
@@ -179,7 +279,7 @@ Rule	NAME	FROM	TO	TYPE	IN	ON	AT	SAVE	LETTER/S
 For example:
 .ti +.5i
 .sp
-Rule	US	1967	1973	\*-	Apr	lastSun	2:00w	1:00	D
+Rule	US	1967	1973	\*-	Apr	lastSun	2:00w	1:00d	D
 .sp
 .fi
 The fields that make up a rule line are:
@@ -256,12 +356,22 @@ or a weekday name preceded by
 (e.g.,
 .BR "lastSunday" )
 may be abbreviated or spelled out in full.
-Note that there must be no spaces within the
+There must be no white space characters within the
 .B ON
 field.
+The
+.q <=
+and
+.q >=
+constructs can result in a day in the neighboring month;
+for example, the IN-ON combination
+.q "Oct Sun>=31"
+stands for the first Sunday on or after October 31,
+even if that Sunday occurs in November.
 .TP
 .B AT
-Gives the time of day at which the rule takes effect.
+Gives the time of day at which the rule takes effect,
+relative to 00:00, the start of a calendar day.
 Recognized forms include:
 .nf
 .in +.5i
@@ -270,24 +380,30 @@ Recognized forms include:
 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)
+00:19:32.13	time with fractional seconds
+12:00	midday, 12 hours after 00:00
+15:00	3 PM, 15 hours after 00:00
+24:00	end of day, 24 hours after 00:00
 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
+.B 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
+if the given time is local or
 .q "wall clock"
 time,
 .B s
-if the given time is local
-.q "standard"
-time, or
+if the given time is standard time without any adjustment for daylight saving,
+or
 .B u
 (or
 .B g
@@ -295,7 +411,11 @@ or
 .BR z )
 if the given time is universal time;
 in the absence of an indicator,
-wall clock time is assumed.
+local (wall clock) time is assumed.
+These forms ignore leap seconds; for example,
+if a leap second occurs at 00:59:60 local time,
+.q "1:00"
+stands for 3601 seconds after local midnight instead of the usual 3600 seconds.
 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
@@ -303,15 +423,20 @@ 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.
+effect, and whether the resulting time is standard or daylight saving.
 This field has the same format as the
 .B AT
 field
-(although, of course, the
-.B w
-and
+except with a different set of suffix letters:
 .B s
-suffixes are not used).
+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.
@@ -342,8 +467,8 @@ 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]
+.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
+Zone	NAME	STDOFF	RULES	FORMAT	[UNTIL]
 .sp
 For example:
 .sp
@@ -352,7 +477,7 @@ 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"
+.TP "\w'STDOFF'u"
 .B NAME
 The name of the timezone.
 This is the name used in creating the time conversion information file for the
@@ -364,8 +489,9 @@ or
 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.
+.B STDOFF
+The amount of time to add to UT to get standard time,
+without any adjustment for daylight saving.
 This field has the same format as the
 .B AT
 and
@@ -415,7 +541,7 @@ 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]]].
+It takes the form of one to four fields 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
@@ -440,6 +566,16 @@ 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.
+A zone or continuation line
+.I L
+with a named rule set starts with standard time by default:
+that is, any of
+.IR L 's
+timestamps preceding
+.IR L 's
+earliest rule use the rule in effect after
+.IR L 's
+first transition into standard time.
 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
@@ -474,7 +610,9 @@ 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:
+The file that describes leap seconds can have leap lines and an
+expiration line.
+Leap lines 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
@@ -513,7 +651,44 @@ or
 (an abbreviation of)
 .q "Rolling"
 if the leap second time given by the other fields should be interpreted as
-local wall clock time.
+local (wall clock) time.
+.PP
+The expiration line, if present, has the form:
+.nf
+.ti +.5i
+.ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u
+.sp
+Expires	YEAR	MONTH	DAY	HH:MM:SS
+.sp
+For example:
+.ti +.5i
+.sp
+Expires	2020	Dec	28	00:00:00
+.sp
+.fi
+The
+.BR YEAR ,
+.BR MONTH ,
+.BR DAY ,
+and
+.B HH:MM:SS
+fields give the expiration timestamp in UTC for the leap second table;
+.B zic
+outputs this expiration timestamp by truncating the end of the output
+file to the timestamp.
+If there is no expiration line,
+.B zic
+also accepts a comment
+.q "#expires \fIE\fP ...\&"
+where
+.I E
+is the expiration timestamp as a decimal integer count of seconds
+since the Epoch, not counting leap seconds.
+However, the
+.q "#expires"
+comment is an obsolescent feature,
+and the leap second file should use an expiration line
+instead of relying on a comment.
 .SH "EXTENDED EXAMPLE"
 Here is an extended example of
 .B zic
@@ -537,10 +712,10 @@ 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]
+.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
+# Zone	NAME	STDOFF	RULES	FORMAT	[UNTIL]
 Zone	Europe/Zurich	0:34:08	\*-	LMT	1853 Jul 16
-		0:29:46	\*-	BMT	1894 Jun
+		0:29:45.50	\*-	BMT	1894 Jun
 		1:00	Swiss	CE%sT	1981
 		1:00	EU	CE%sT
 .sp
@@ -551,9 +726,14 @@ Link	Europe/Zurich	Europe/Vaduz
 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
+was changed to
+.ds o 7 degrees 26 minutes 22.50 seconds
+.if \n(.g .if c \(de .if c \(fm .if c \(sd .ds o 7\(de\|26\(fm\|22.50\(sd
+\*o,
+which works out to 0:29:45.50;
+.B zic
+treats this by rounding it to 0:29:46.
+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
@@ -596,7 +776,7 @@ 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).
+without any change in local (wall clock) time.
 To get separate transitions
 use multiple zone continuation lines
 specifying transition instants using universal time.