Normally by convention useful environmental variables are documented
in an ENVIRONMENT section of the man page. There is no coverage of any
env vars in the man page. I was trying to work out how to make
timestamps print in terms of the UTC timezone. It’s undocumented. As a
guess, I tried:

  $ env TZ=UTC tcpdump -r session.pcap

It worked as expected. Is that because tcpdump reads the TZ variable?
Or does tcpdump make a system call to obtain the time and the system
uses the TZ variable?

If it’s the former, then TZ should be documented in the man page. If
it’s the latter, then it’s unclear to me how to document that but
nonetheless users should be informed somehow.

Along these lines, it’s worth noting that the man page says this:

  “A packet trace that crosses a daylight savings time change will
   give skewed time stamps (the time change is ignored).”

Perhaps a TZ that’s shifted by 12 hours or set to a timezone that does
not honor daylight savings will work around that problem?  If so, the
man page could suggest that.

tcpdump has no special handling of TZ, it just calls strftime() which
handles TZ as described in strftime(3).

* Romain Francoise <rfrancoise@debian.org> [2024-03-17 19:52]:

Thanks for the quick feedback.

That’s a bit tricky one then. Users of tcpdump wouldn’t generally know
that strftime() is in use and thus don’t know to visit that man
page.

To investigate what’s done conventionally, I ran this command:

  $ man -IaK --regex TZ | sed -ne '/\<TZ\>.*zone/{x;G;p};/^NAME/{N;s/\n/ /;h}'

which short-listed some pages. Of those, “man tree” shows a good
complete example. It contains:

===8<----------------------------------------
ENVIRONMENT
       LS_COLORS      Color information created by dircolors
       TREE_COLORS    Uses this for color information over LS_COLORS if it is set.
       TREE_CHARSET   Character set for tree to use in HTML mode.
       CLICOLOR       Enables colorization even if TREE_COLORS or LS_COLORS is not set.
       CLICOLOR_FORCE Always enables colorization (effectively -C)
       LC_CTYPE       Locale for filename output.
       LC_TIME        Locale for timefmt output, see strftime(3).
       TZ             Timezone for timefmt output, see strftime(3).
…
SEE ALSO
       dircolors(1), ls(1), find(1), du(1), strftime(3)
===8<----------------------------------------

But if tcpdump were to document the TZ variable and strftime() were to
make a change so TZ no longer has effect, then tcpdump would have to
keep tabs on strftime(), in principle. OTOH, the “see strftime(3)” gives
users enough info to react if that happens.

Alternatively, a minimal change would be to add strftime(3) to the SEE ALSO
section. The current tcpdump man page misses it:

===8<----------------------------------------
SEE ALSO
       stty(1), pcap(3PCAP), bpf(4), nit(4P), pcap-savefile(5), pcap-filter(7), pcap-tstamp(7)
===8<----------------------------------------

Very little, if anything, of strftime() needs to handle TZ, because it's handed a const struct tm *, generated either by a call to localtime() or gmtime()  If generated by a call to localtime(), localtime() has already done all the work of converting a time_t to local time, meaning that it's localtime(), not strftime(), that uses TZ.

If, as I suspect, this is a bug inherited from another project's man pages, I'll file a bug there.

Would users of ls generally know that 1) ls uses localtime() and 2) that, therefore, the setting of TZ affects its behavior?  Even if they know 1), they wouldn't know 2) if all they did was look at the localtime() man page, as, at least in Debian 12.5, that man page does *not* mention that its behavior is affected by the TZ environment variable.

If they also wouldn't know that TZ affects ls, how is ls different from tcpdump in this regard?

Note that ls isn't the only command affected by TZ; date is also affected by TZ, and there are plenty of others.  Must all commands that happen either to take local time inputs (and convert them to time_t values by using mktime()) or product local time outputs converted from time_t values by using localtime() mention that the TZ environment variable affects their behavior?

I just checked the tip-of-the-main-branch GNU libc, and, in the time subdirectory:

	strftime_l.c does *not* call getenv(), and thus strftime() does *not* directly look at TZ;

	tzset.c *does* call getenv("TZ") - which it has to do, as it sets the current time information for the current process based on the setting of TZ.

I'll look at getting the man pages fixed.

I've filed https://bugzilla.kernel.org/show_bug.cgi?id=218711 against the strftime man page.

For localtime(), it may be sufficient that the man page indicates that localtime() behaves as if tzset() were called, and that the tzset man page indicates that TZ is used.  The macOS man page, however, *does* mention TZ, and that may also be true of the ctime man page in other BSDs.