On 2023-03-07 15:54, Alejandro Colomar wrote:
mandoc: man5/tzfile.5:15:19: WARNING: undefined escape, printing literally: \\
mandoc: man5/tzfile.5:15:10: WARNING: undefined escape, printing literally: \\
My guess is that this is fallout from last month's changes to use \[lq]
instead of \(lq and so forth. I suggest reverting all those changes to
tzfile.5, since the upstream tzfile.5 continues to use \(lq etc. for
compatibility with traditional troff, which is still a thing upstream.
Come to think of it, we should resync tzfile.5 and tzselect.8 from
upstream for other reasons. Proposed patch to manpages attached. If this
generates more mandoc warnings, I suppose we can adjust the calls to mandoc.From f68d7d2ac270f366bc97b6e8dc2b0f2af201c8aa Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Tue, 7 Mar 2023 21:11:38 -0800
Subject: [PATCH] tzfile.5, tzselect.8: sync from tzdb upstream
This makes tzfile.5 and tzselect.8 a copy of the tzdb develoment
version (commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0), except that
man-pages boilerplate surrounds the copyright notice, and the .TH line
uses man-pages format.
---
man5/tzfile.5 | 194 +++++++++++++++++++++++++++++++++---------------
man8/tzselect.8 | 133 +++++++++++++++++++++++++--------
2 files changed, 237 insertions(+), 90 deletions(-)
diff --git a/man5/tzfile.5 b/man5/tzfile.5
index aa2170479..e94aaaad6 100644
--- a/man5/tzfile.5
+++ b/man5/tzfile.5
@@ -1,21 +1,21 @@
.\" %%%LICENSE_START(PUBLIC_DOMAIN)
.\" This file is in the public domain, so clarified as of
-.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@xxxxxxx>.
+.\" 1996-06-05 by Arthur David Olson.
.\" %%%LICENSE_END
.\"
-.TH tzfile 5 2022-09-09 Linux "Linux Programmer's Manual"
+.TH tzfile 5 2023-03-07 Linux "Linux Programmer's Manual"
.SH NAME
tzfile \- timezone information
.SH DESCRIPTION
-.ie '\[lq]'' .ds lq \&"\"
-.el .ds lq \[lq]\"
-.ie '\[rq]'' .ds rq \&"\"
-.el .ds rq \[rq]\"
+.ie '\(lq'' .ds lq \&"\"
+.el .ds lq \(lq\"
+.ie '\(rq'' .ds rq \&"\"
+.el .ds rq \(rq\"
.de q
\\$3\*(lq\\$1\*(rq\\$2
..
-.ie \n(.g .ds - \f(CW-\fP
-.el ds - \-
+.ie \n(.g .ds - \f(CR-\fP
+.el .ds - \-
The timezone information files used by
.BR tzset (3)
are typically found under a directory with a name like
@@ -35,35 +35,36 @@ The magic four-byte ASCII sequence
identifies the file as a timezone information file.
.IP *
A byte identifying the version of the file's format
-(as of 2017, either an ASCII NUL, or
+(as of 2021, either an ASCII NUL,
.q "2",
+.q "3",
or
-.q "3" ).
+.q "4" ).
.IP *
Fifteen bytes containing zeros reserved for future use.
.IP *
Six four-byte integer values, in the following order:
.RS
.TP
-.I tzh_ttisutcnt
+.B tzh_ttisutcnt
The number of UT/local indicators stored in the file.
(UT is Universal Time.)
.TP
-.I tzh_ttisstdcnt
+.B tzh_ttisstdcnt
The number of standard/wall indicators stored in the file.
.TP
-.I tzh_leapcnt
+.B tzh_leapcnt
The number of leap seconds for which data entries are stored in the file.
.TP
-.I tzh_timecnt
+.B tzh_timecnt
The number of transition times for which data entries are stored
in the file.
.TP
-.I tzh_typecnt
+.B tzh_typecnt
The number of local time types for which data entries are stored
in the file (must not be zero).
.TP
-.I tzh_charcnt
+.B tzh_charcnt
The number of bytes of time zone abbreviation strings
stored in the file.
.RE
@@ -71,14 +72,14 @@ stored in the file.
The above header is followed by the following fields, whose lengths
depend on the contents of the header:
.IP * 2
-.I tzh_timecnt
+.B tzh_timecnt
four-byte signed integer values sorted in ascending order.
These values are written in network byte order.
Each is used as a transition time (as returned by
.BR time (2))
at which the rules for computing local time change.
.IP *
-.I tzh_timecnt
+.B tzh_timecnt
one-byte unsigned integer values;
each one but the last tells which of the different types of local time types
described in the file is associated with the time period
@@ -88,8 +89,8 @@ and continuing up to but not including the next transition time.
POSIX-style TZ string described below.)
These values serve as indices into the next field.
.IP *
-.I tzh_typecnt
-.I ttinfo
+.B tzh_typecnt
+.B ttinfo
entries, each defined as follows:
.in +.5i
.sp
@@ -104,55 +105,78 @@ struct ttinfo {
.fi
.sp
Each structure is written as a four-byte signed integer value for
-.IR tt_utoff ,
+.BR tt_utoff ,
in network byte order, followed by a one-byte boolean for
-.I tt_isdst
+.B tt_isdst
and a one-byte value for
-.IR tt_desigidx .
+.BR tt_desigidx .
In each structure,
-.I tt_utoff
+.B tt_utoff
gives the number of seconds to be added to UT,
-.I tt_isdst
+.B tt_isdst
tells whether
-.I tm_isdst
+.B tm_isdst
should be set by
.BR localtime (3)
and
-.I tt_desigidx
+.B tt_desigidx
serves as an index into the array of time zone abbreviation bytes
that follow the
-.I ttinfo
-structure(s) in the file.
+.B ttinfo
+entries in the file; if the designated string is "\*-00", the
+.B ttinfo
+entry is a placeholder indicating that local time is unspecified.
The
-.I tt_utoff
+.B tt_utoff
value is never equal to \-2**31, to let 32-bit clients negate it without
overflow.
Also, in realistic applications
-.I tt_utoff
+.B tt_utoff
is in the range [\-89999, 93599] (i.e., more than \-25 hours and less
than 26 hours); this allows easy support by implementations that
already support the POSIX-required range [\-24:59:59, 25:59:59].
.IP *
-.I tzh_leapcnt
+.B tzh_charcnt
+bytes that represent time zone designations,
+which are null-terminated byte strings, each indexed by the
+.B tt_desigidx
+values mentioned above.
+The byte strings can overlap if one is a suffix of the other.
+The encoding of these strings is not specified.
+.IP *
+.B tzh_leapcnt
pairs of four-byte values, written in network byte order;
the first value of each pair gives the nonnegative time
(as returned by
.BR time (2))
-at which a leap second occurs;
-the second is a signed integer specifying the
+at which a leap second occurs or at which the leap second table expires;
+the second is a signed integer specifying the correction, which is the
.I total
number of leap seconds to be applied during the time period
starting at the given time.
-The pairs of values are sorted in ascending order by time.
-Each transition is for one leap second, either positive or negative;
-transitions always separated by at least 28 days minus 1 second.
+The pairs of values are sorted in strictly ascending order by time.
+Each pair denotes one leap second, either positive or negative,
+except that if the last pair has the same correction as the previous one,
+the last pair denotes the leap second table's expiration time.
+Each leap second is at the end of a UTC calendar month.
+The first leap second has a nonnegative occurrence time,
+and is a positive leap second if and only if its correction is positive;
+the correction for each leap second after the first differs
+from the previous leap second by either 1 for a positive leap second,
+or \-1 for a negative leap second.
+If the leap second table is empty, the leap-second correction is zero
+for all timestamps;
+otherwise, for timestamps before the first occurrence time,
+the leap-second correction is zero if the first pair's correction is 1 or \-1,
+and is unspecified otherwise (which can happen only in files
+truncated at the start).
.IP *
-.I tzh_ttisstdcnt
+.B tzh_ttisstdcnt
standard/wall indicators, each stored as a one-byte boolean;
they tell whether the transition times associated with local time types
were specified as standard time or local (wall clock) time.
.IP *
-.I tzh_ttisutcnt
+.B tzh_ttisutcnt
UT/local indicators, each stored as a one-byte boolean;
they tell whether the transition times associated with local time types
were specified as UT or local time.
@@ -178,10 +202,10 @@ The
.BR localtime (3)
function
normally uses the first
-.I ttinfo
+.B ttinfo
structure in the file
if either
-.I tzh_timecnt
+.B tzh_timecnt
is zero or the time argument is less than the first transition time recorded
in the file.
.SS Version 2 format
@@ -195,11 +219,11 @@ POSIX-TZ-environment-variable-style string for use in handling instants
after the last transition time stored in the file
or for all instants if the file has no transitions.
The POSIX-style TZ string is empty (i.e., nothing between the newlines)
-if there is no POSIX representation for such instants.
+if there is no POSIX-style representation for such instants.
If nonempty, the POSIX-style TZ string must agree with the local time
type after the last transition time if present in the eight-byte data;
for example, given the string
-.q "WET0WEST,M3.5.0,M10.5.0/3"
+.q "WET0WEST,M3.5.0/1,M10.5.0"
then if a last transition time is in July, the transition's local time
type must specify a daylight-saving time abbreviated
.q "WEST"
@@ -217,33 +241,52 @@ from 0 through 24.
Second, DST is in effect all year if it starts
January 1 at 00:00 and ends December 31 at 24:00 plus the difference
between daylight saving and standard time.
+.SS Version 4 format
+For version-4-format TZif files,
+the first leap second record can have a correction that is neither
++1 nor \-1, to represent truncation of the TZif file at the start.
+Also, if two or more leap second transitions are present and the last
+entry's correction equals the previous one, the last entry
+denotes the expiration of the leap second table instead of a leap second;
+timestamps after this expiration are unreliable in that future
+releases will likely add leap second entries after the expiration, and
+the added leap seconds will change how post-expiration timestamps are treated.
.SS Interoperability considerations
Future changes to the format may append more data.
.PP
Version 1 files are considered a legacy format and
-should be avoided, as they do not support transition
+should not be generated, as they do not support transition
times after the year 2038.
-Readers that only understand Version 1 must ignore
+Readers that understand only Version 1 must ignore
any data that extends beyond the calculated end of the version
1 data block.
.PP
-Writers should generate a version 3 file if
+Other than version 1, writers should generate
+the lowest version number needed by a file's data.
+For example, a writer should generate a version 4 file
+only if its leap second table either expires or is truncated at the start.
+Likewise, a writer not generating a version 4 file
+should generate a version 3 file only if
TZ string extensions are necessary to accurately
model transition times.
-Otherwise, version 2 files should be generated.
.PP
The sequence of time changes defined by the version 1
-header and data block should be a contiguous subsequence
+header and data block should be a contiguous sub-sequence
of the time changes defined by the version 2+ header and data
block, and by the footer.
This guideline helps obsolescent version 1 readers
agree with current readers about timestamps within the
-contiguous subsequence. It also lets writers not
+contiguous sub-sequence. It also lets writers not
supporting obsolescent readers use a
-.I tzh_timecnt
+.B tzh_timecnt
of zero
in the version 1 data block to save space.
.PP
+When a TZif file contains a leap second table expiration
+time, TZif readers should either refuse to process
+post-expiration timestamps, or process them as if the expiration
+time did not exist (possibly with an error indication).
+.PP
Time zone designations should consist of at least three (3)
and no more than six (6) ASCII characters from the set of
alphanumerics,
@@ -253,13 +296,20 @@ and
This is for compatibility with POSIX requirements for
time zone abbreviations.
.PP
-When reading a version 2 or 3 file, readers
+When reading a version 2 or higher file, readers
should ignore the version 1 header and data block except for
the purpose of skipping over them.
.PP
Readers should calculate the total lengths of the
headers and data blocks and check that they all fit within
the actual file size, as part of a validity check for the file.
+.PP
+When a positive leap second occurs, readers should append an extra
+second to the local minute containing the second just before the leap
+second. If this occurs when the UTC offset is not a multiple of 60
+seconds, the leap second occurs earlier than the last second of the
+local minute and the minute's remaining local seconds are numbered
+through 60 instead of the usual 59; the UTC offset is unaffected.
.SS Common interoperability issues
This section documents common problems in reading or writing TZif files.
Most of these are problems in generating TZif files for use by
@@ -280,7 +330,7 @@ design goal has been that a reader can successfully use a TZif
file even if the file is of a later TZif version than what the
reader was designed for.
When complete compatibility was not achieved, an attempt was
-made to limit glitches to rarely used timestamps, and to allow
+made to limit glitches to rarely used timestamps and allow
simple partial workarounds in writers designed to generate
new-version data useful even for older-version readers.
This section attempts to document these compatibility issues and
@@ -297,20 +347,33 @@ version 2+ data even if the reader's native timestamps have only
32 bits.
.IP *
Some readers designed for version 2 might mishandle
-timestamps after a version 3 file's last transition, because
+timestamps after a version 3 or higher file's last transition, because
they cannot parse extensions to POSIX in the TZ-like string.
As a partial workaround, a writer can output more transitions
than necessary, so that only far-future timestamps are
mishandled by version 2 readers.
.IP *
Some readers designed for version 2 do not support
-permanent daylight saving time, e.g., a TZ string
+permanent daylight saving time with transitions after 24:00
+\(en e.g., a TZ string
.q "EST5EDT,0/0,J365/25"
-denoting permanent Eastern Daylight Time (\-04).
-As a partial workaround, a writer can substitute standard time
-for the next time zone east, e.g.,
+denoting permanent Eastern Daylight Time
+(\-04).
+As a workaround, a writer can substitute standard time
+for two time zones east, e.g.,
+.q "XXX3EDT4,0/0,J365/23"
+for a time zone with a never-used standard time (XXX, \-03)
+and negative daylight saving time (EDT, \-04) all year.
+Alternatively,
+as a partial workaround a writer can substitute standard time
+for the next time zone east \(en e.g.,
.q "AST4"
-for permanent Atlantic Standard Time (\-04).
+for permanent
+Atlantic Standard Time (\-04).
+.IP *
+Some readers designed for version 2 or 3, and that require strict
+conformance to RFC 8536, reject version 4 files whose leap second
+tables are truncated at the start or that end in expiration times.
.IP *
Some readers ignore the footer, and instead predict future
timestamps from the time type of the last transition.
@@ -375,6 +438,17 @@ thus swapping standard and daylight saving time.
Although this workaround misidentifies which part of the year
uses daylight saving time, it records UT offsets and time zone
abbreviations correctly.
+.IP *
+Some readers generate ambiguous timestamps for positive leap seconds
+that occur when the UTC offset is not a multiple of 60 seconds.
+For example, in a timezone with UTC offset +01:23:45 and with
+a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will
+map both 78796800 and 78796801 to 01:23:45 local time the next day
+instead of mapping the latter to 01:23:46, and they will map 78796815 to
+01:23:59 instead of to 01:23:60.
+This has not yet been a practical problem, since no civil authority
+has observed such UTC offsets since leap seconds were
+introduced in 1972.
.PP
Some interoperability problems are reader bugs that
are listed here mostly as warnings to developers of readers.
@@ -417,11 +491,9 @@ of one hour, or of 15 minutes, or of 1 minute.
.PP
Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif).
2019 Feb.
-.UR https://\:www.rfc-editor.org/\:info/\:rfc8536
+.UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536
Internet RFC 8536
.UE
.UR https://\:doi.org/\:10.17487/\:RFC8536
doi:10.17487/RFC8536
.UE .
-.\" This file is in the public domain, so clarified as of
-.\" 1996-06-05 by Arthur David Olson.
diff --git a/man8/tzselect.8 b/man8/tzselect.8
index 2319c6158..3b69587f3 100644
--- a/man8/tzselect.8
+++ b/man8/tzselect.8
@@ -1,53 +1,128 @@
.\" %%%LICENSE_START(PUBLIC_DOMAIN)
-.\" This page is in the public domain
+.\" This file is in the public domain, so clarified as of
+.\" 2009-05-17 by Arthur David Olson.
.\" %%%LICENSE_END
.\"
.TH tzselect 8 (date) "Linux man-pages (unreleased)"
.SH NAME
tzselect \- select a timezone
.SH SYNOPSIS
-.nf
+.ie \n(.g .ds - \f(CR-\fP
+.el .ds - \-
+.ds d " degrees
+.ds m " minutes
+.ds s " seconds
+.ds _ " \&
+.if t \{\
+. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\
+. ds d \(de
+. ds m \(fm
+. ds s \(sd
+. ds _ \|
+. \}
+.\}
.B tzselect
-.fi
+[
+.B \*-c
+.I coord
+] [
+.B \*-n
+.I limit
+] [
+.B \*-\*-help
+] [
+.B \*-\*-version
+]
.SH DESCRIPTION
The
.B tzselect
program asks the user for information about the current location,
-and outputs the resulting timezone description to standard output.
-The output is suitable as a value for the
-.B TZ
-environment variable.
+and outputs the resulting timezone to standard output.
+The output is suitable as a value for the TZ environment variable.
.PP
All interaction with the user is done via standard input and standard error.
-.SH EXIT STATUS
-The exit status is zero if a timezone was successfully obtained
-from the user, and is nonzero otherwise.
-.SH ENVIRONMENT
-.TP
-.B AWK
-Name of a POSIX-compliant
-.I awk
+.SH OPTIONS
+.TP
+.BI "\*-c " coord
+Instead of asking for continent and then country and then city,
+ask for selection from time zones whose largest cities
+are closest to the location with geographical coordinates
+.I coord.
+Use ISO 6709 notation for
+.I coord,
+that is, a latitude immediately followed by a longitude. The latitude
+and longitude should be signed integers followed by an optional
+decimal point and fraction: positive numbers represent north and east,
+negative south and west. Latitudes with two and longitudes with three
+integer digits are treated as degrees; latitudes with four or six and
+longitudes with five or seven integer digits are treated as
+.I "DDMM, DDDMM, DDMMSS,"
+or
+.I DDDMMSS
+representing
+.I DD
+or
+.I DDD
+degrees,
+.I MM
+minutes,
+and zero or
+.I SS
+seconds, with any trailing fractions represent fractional minutes or
+(if
+.I SS
+is present) seconds. The decimal point is that of the current locale.
+For example, in the (default) C locale,
+.B "\*-c\ +40.689\*-074.045"
+specifies 40.689\*d\*_N, 74.045\*d\*_W,
+.B "\*-c\ +4041.4\*-07402.7"
+specifies 40\*d\*_41.4\*m\*_N, 74\*d\*_2.7\*m\*_W, and
+.B "\*-c\ +404121\*-0740240"
+specifies 40\*d\*_41\*m\*_21\*s\*_N, 74\*d\*_2\*m\*_40\*s\*_W.
+If
+.I coord
+is not one of the documented forms, the resulting behavior is unspecified.
+.TP
+.BI "\*-n " limit
+When
+.B \*-c
+is used, display the closest
+.I limit
+locations (default 10).
+.TP
+.B "\*-\*-help"
+Output help information and exit.
+.TP
+.B "\*-\*-version"
+Output version information and exit.
+.SH "ENVIRONMENT VARIABLES"
+.TP
+\f3AWK\fP
+Name of a Posix-compliant
+.B awk
program (default:
.BR awk ).
.TP
-.B TZDIR
+\f3TZDIR\fP
Name of the directory containing timezone data files (default:
-.IR /usr/share/zoneinfo ).
-.\" or perhaps /usr/local/etc/zoneinfo in some older systems.
+.BR /usr/share/zoneinfo ).
.SH FILES
.TP
-\fBTZDIR\fP\fI/iso3166.tab\fP
+\f2TZDIR\fP\f3/iso3166.tab\fP
Table of ISO 3166 2-letter country codes and country names.
.TP
-\fBTZDIR\fP\fI/zone.tab\fP
-Table of country codes, latitude and longitude, TZ values, and
+\f2TZDIR\fP\f3/zone1970.tab\fP
+Table of country codes, latitude and longitude, timezones, and
descriptive comments.
.TP
-\fBTZDIR\fP\fI/\fP\fITZ\fP
-Timezone data file for timezone
-.IR TZ .
-.SH SEE ALSO
-.BR tzfile (5),
-.BR zdump (8),
-.BR zic (8)
-.\" @(#)tzselect.8 1.3
+\f2TZDIR\fP\f3/\fP\f2TZ\fP
+Timezone data file for timezone \f2TZ\fP.
+.SH "EXIT STATUS"
+The exit status is zero if a timezone was successfully obtained from the user,
+nonzero otherwise.
+.SH "SEE ALSO"
+newctime(3), tzfile(5), zdump(8), zic(8)
+.SH NOTES
+Applications should not assume that
+.BR tzselect 's
+output matches the user's political preferences.
--
2.39.2
