Time::Piece and Time::TimeZone compatibility boundary when replacing system TZ with explicit regional offsets

Answer

When you replace the system TZ lookup with an explicit offset from Time::TimeZone, the boundary that determines daylight‑saving transitions is governed by the CPAN module’s offset table, not the C library’s transition table. Time::Piece itself only follows the C library (localtime/gmtime) and the process TZ environment variable; if you bypass it by adding an offset manually, you are relying entirely on the data supplied by Time::TimeZone.

Thread‑safe offset handling

Modifying $ENV{TZ} at runtime is unsafe in threaded Perl because the environment block is process‑wide and shared by all threads. To avoid race conditions:

1. Obtain the offset for the desired zone and epoch using Time::TimeZone->offset($epoch, $zone).
2. Create a UTC Time::Piece object: my $tp = Time::Piece->gmtime($epoch);
3. Add the offset (the overload handles seconds): $tp += $offset;
4. Format or use the resulting Time::Piece as needed.

This approach never touches %ENV, so it is safe across threads.

Version guarantees

There is no documented guarantee that Time::Piece (which uses the host’s tzdata) and Time::TimeZone (which ships its own zoneinfo copy) will produce identical DST boundaries across different OS tzdata versions. Consistency is only assured when both components are built from the same version of the zoneinfo database. If you need strict parity, verify that the system’s tzdata package and the version of Time::TimeZone you are using were derived from the same release.

Missing diagnostic detail

If you observe a mismatch between the two methods, please confirm the exact versions of the system tzdata (e.g., zdump -V /etc/localtime | head -1) and the Time::TimeZone module (perl -MTime::TimeZone -e 'print $Time::TimeZone::VERSION'). This information determines whether a version skew explains the discrepancy.