On 2021-02-25 02:06, Martin Burnicki via tz wrote:

the zdump.8.txt file generated from the current github code says:

-c [loyear,]hiyear ... Cutoffs are at the start of each year, where the lower-bound timestamp is *exclusive* and the upper is *inclusive*; for example, -c 1970,2070 selects transitions after 1970-01-01 00:00:00 UTC and on or before 2070-01-01 00:00:00 UTC.  The default cutoff is -500,2500.

and

$ ./zdump -V -c 2021,2022 Europe/Berlin Europe/Berlin  Sun Mar 28 00:59:59 2021 UT = Sun Mar 28 01:59:59 .. Europe/Berlin  Sun Mar 28 01:00:00 2021 UT = Sun Mar 28 03:00:00 .. Europe/Berlin  Sun Oct 31 00:59:59 2021 UT = Sun Oct 31 02:59:59 .. Europe/Berlin  Sun Oct 31 01:00:00 2021 UT = Sun Oct 31 02:00:00 ..

(lines shorted to avoid line-wrapping)

So the lower year is *inclusive* and the upper year is *exclusive*, and from my understanding these words should be swapped in the text of the man page. Or am I missing something?

If I'm correct, should I provide a patch or pull request for the git repo?

You're right, it appears misleading and is unintuitive, but has been the same since it was partially clarified in 2014h/i. The -c year range is inclusive of the first optional year, excluding the first second of that year in UT excluding leap seconds (presumably POSIX time), but exclusive of the required second year, but inclusive of the first second of that year in UT excluding leap seconds (presumably POSIX time). For -t timestamps, the first optional timestamp is excluded and the second is excluded I believe. It would be better if both years/timestamps were *inclusive*, as that is what most users expect in ranges e.g. 1970 thru 2021, as exemplified in many languages which include ranges, as opposed to C loops which are choosey about their friends. When you have to keep clarifying documentation because of misunderstandings or misinterpretations, or having to implement work arounds, then the design, implementation, or interface may be based on poor or inadequate assumptions, and the interface, implementation, or design should be corrected to match normal assumptions, allowing the documentation to be simplified to match normal assumptions, and the work arounds to be simplified or eliminated, in my opinion. So both -c years should be inclusive from start to end and so should -t timestamps. As zdump produces no default output for $TZ or /etc/localtime, my interactive zdump interface for my usual use case is now: $ which zdump zdump () { local z=${1:-${TZ:-/etc/localtime}} y=$(date +%Y); local e=$(($y+1)) b p l t; for b in $y 1970 1900 1752; do p=$(command /usr/bin/zdump -Vc$b,$e $z); [ -n "$p" ] && break; done; l=${p##*$'\n'}; t=${l##*[012][0-9]:[0-5][0-9]:[0-6][0-9] }; b=${t:0:4}; [ $b -lt $y ] && p=$(command /usr/bin/zdump -Vc$b,$e $z); echo "$p" } which produces a dump for transitions enclosing the current year: $ zdump America/Edmonton Sun Mar 14 08:59:59 2021 UT = Sun Mar 14 01:59:59 2021 MST isdst=0 gmtoff=-25200 America/Edmonton Sun Mar 14 09:00:00 2021 UT = Sun Mar 14 03:00:00 2021 MDT isdst=1 gmtoff=-21600 America/Edmonton Sun Nov 7 07:59:59 2021 UT = Sun Nov 7 01:59:59 2021 MDT isdst=1 gmtoff=-21600 America/Edmonton Sun Nov 7 08:00:00 2021 UT = Sun Nov 7 01:00:00 2021 MST isdst=0 gmtoff=-25200 I may add options if I see more need, but for now use the command prefix or explicit /usr/bin/zdump path for other use cases: $ command zdump $ command zdump $TZ America/Edmonton Thu Feb 25 14:13:39 2021 MST $ command zdump /etc/localtime /etc/localtime Thu Feb 25 14:13:42 2021 MST although the output appears to ignore all locale settings: $ date; date +%c 2021 Feb 25 Thu 14:13:48 MST 2021 Feb 25 Thu 14:13:48-0700 which to me should only be done if using ISO style formats e.g. %F\ %T%z. Same results regardless of system and zdump build: $ command zdump --version zdump (Debian GLIBC 2.28-10) 2.28 $ command zdump --version zdump (tzcode) 2021a although other distros are more selective about incorporating tzcode changes. -- Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada This email may be disturbing to some readers as it contains too much technical detail. Reader discretion is advised. [Data in binary units and prefixes, physical quantities in SI.]