Per-shell time zone isolation limits in zsh/datetime

Question

Scripts using the zsh/datetime module often need to format EPOCHSECONDS or parse strings via strftime and strptime in a specific regional time zone. The module documentation ties these operations to the host C library and the process environment, meaning the active zone is inherited from variables such as TZ rather than selected by a zsh option.
Because there is no documented parameter to override the zone independently for a single shell instance, the boundary between supported usage and unsupported per-session isolation is unclear. A script that must render timestamps in a fixed zone without altering the parent environment appears to face a structural limit.
Is there a supported way to scope a time zone to one zsh session without mutating the parent process environment? If not, what is the intended behavior when regional offset or DST rules differ from the host default? Does the module impose any additional constraints beyond those of the underlying libc?

Wasi · Answer

Direct answer
No supported per-shell time zone override exists in zsh/datetime. The module resolves zones through the host C library using the process-level TZ variable, and zsh provides no option or module parameter to bind a different zone to one shell instance. To avoid changing the parent process, run the date work in a child shell with TZ prefixed to the invocation.
Confirmed facts

zmodload zsh/datetime is required; the module is not always active by default.
EPOCHSECONDS, EPOCHREALTIME, strftime, and strptime inherit the process time zone from TZ or the system default when TZ is unset.
Exporting TZ changes the current shell and its children, but a child process cannot alter its parent's environment.
zsh applies no separate offset or DST calendar; those rules come from libc and installed tzdata.

Steps for this case

Load the module in the isolated shell: zmodload zsh/datetime.
Run formatting or parsing in a child process so the zone does not leak upward: TZ=America/New_York zsh -c 'zmodload zsh/datetime; strftime "%Y-%m-%d %Z %z" $EPOCHSECONDS'
If you own the current shell and can change its environment, export TZ=America/New_York scopes the zone to that shell and its descendants only; the parent process remains unaffected.

Intended behavior when offsets or DST rules differ
When the regional offset or DST rules differ from the host default, the C library applies its own transition table for the named zone. zsh/datetime does not adjust, convert, or validate those rules. Output reflects libc behavior for the selected TZ, including any gaps or overlaps around DST transitions.
Constraints beyond libc
The module imposes no documented zone-selection mechanism beyond what libc offers. Additional limits are practical rather than architectural: zone-name availability, strptime specifier support, and DST edge cases depend on glibc, musl, BSD libc, the local tzdata package, and the zsh version in use.
Verification
zmodload zsh/datetime
strftime '%Y-%m-%d %Z %z' $EPOCHSECONDS
TZ=America/New_York zsh -c 'zmodload zsh/datetime; strftime "%Y-%m-%d %Z %z" $EPOCHSECONDS'
Compare the %Z and %z output between the parent shell and the child shell. They should differ when the zones differ.
Missing diagnostic detail
Can the script start a child shell? If process creation is blocked, there is no supported in-process workaround; state that constraint for a different recommendation.

Per-shell time zone isolation limits in zsh/datetime

1 answer

Direct answer

Confirmed facts

Steps for this case

Intended behavior when offsets or DST rules differ

Constraints beyond libc

Verification

Missing diagnostic detail

Your perspective belongs here.

0 question comments