[patch] tzset.3: Add a note on how tzset() caches data when $TZ is used

[patch] tzset.3: Add a note on how tzset() caches data when $TZ is used

[Johan Herland]

The caching behavior of tzset() is poorly documented: outside of the
source itself[1], I know only of the article in [2]. This caching
behavior was first added in glibc commit 68dbb3a69e78 back in 1996, and
has not changed significantly since then, AFAICS. I suspect that it is
not about to change anytime soon.

Add a note to explain how tzset caches data, and the gotcha of setting
TZ to a symlink that, when retargeted, will cause glibc's cache to go
stale.

This was found while debugging a sandboxed application that failed to
retrieve the system timezone when all filesystem access was revoked.
We found that by setting TZ=":/etc/localtime" and calling tzset()
_before_ revoking filesystem access, the process would keep reporting
the correct timezone also after the filesystem was gone. Albeit with
the caveat that timezone changes would not be reflected by the process
(which we solve by restarting the process on timezone changes).

[1]: https://sourceware.org/git/?p=glibc.git;a=blob;f=time/tzset.c;h=2fc51194b63bda8eeaff4f2ac111291ff43c28ad#l388

[2]: https://packagecloud.io/blog/set-environment-variable-save-thousands-of-system-calls/

Signed-off-by: Johan Herland <jherland@cisco.com>
---
 man3/tzset.3 | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/man3/tzset.3 b/man3/tzset.3
index c80da53f8..ac275a07e 100644
--- a/man3/tzset.3
+++ b/man3/tzset.3
@@ -197,6 +197,27 @@ Here's an example, once more for New Zealand:
 TZ=":Pacific/Auckland"
 .EE
 .in
+.PP
+Note that if the
+.B TZ
+variable is used to set the timezone, glibc will not recalculate the timezone
+information unless the value of
+.B TZ
+is changed. Thus, if you use a symbolic link, like for example:
+.PP
+.in +4n
+.EX
+TZ=":/etc/localtime"
+.EE
+.in
+.PP
+and this symlink is later changed to point to a new timezone, then subsequent
+calls to
+.BR tzset ()
+or other time conversion functions that depend on the timezone will not
+reflect the new timezone (because the immediate value of
+.B TZ
+itself did not change).
 .SH ENVIRONMENT
 .TP
 .B TZ
-- 
2.29.2