tzset: Expand comment about TZ problem on native Windows.

* lib/tzset.c (tzset): Elaborate comment, based on explanations by
Paul Eggert.
* lib/ctime.c (rpl_ctime): Likewise.
* lib/localtime.c (rpl_localtime): Likewise.
* lib/mktime.c (mktime): Likewise.
* lib/strftime-fixes.c (rpl_strftime): Likewise.
* lib/wcsftime.c (rpl_wcsftime): Likewise.

1 files changed, 22 insertions, 3 deletions

diff --git a/lib/mktime.c b/lib/mktime.c
index a78d960e53..72df770c1a 100644
--- a/lib/mktime.c
+++ b/lib/mktime.c
@@ -491,9 +491,28 @@ time_t
 mktime (struct tm *tp)
 {
 # if NEED_MKTIME_WINDOWS
-  /* If the environment variable TZ has been set by Cygwin, neutralize it.
-     The Microsoft CRT interprets TZ differently than Cygwin and produces
-     incorrect results if TZ has the syntax used by Cygwin.  */
+  /* Rectify the value of the environment variable TZ.
+     There are four possible kinds of such values:
+       - Traditional US time zone names, e.g. "PST8PDT".  Syntax: see
+         <https://msdn.microsoft.com/en-us/library/90s5c885.aspx>
+       - Time zone names based on geography, that contain one or more
+         slashes, e.g. "Europe/Moscow".
+       - Time zone names based on geography, without slashes, e.g.
+         "Singapore".
+       - Time zone names that contain explicit DST rules.  Syntax: see
+         <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03>
+     The Microsoft CRT understands only the first kind.  It produces incorrect
+     results if the value of TZ is of the other kinds.
+     But in a Cygwin environment, /etc/profile.d/tzset.sh sets TZ to a value
+     of the second kind for most geographies, or of the first kind in a few
+     other geographies.  If it is of the second kind, neutralize it.  For the
+     Microsoft CRT, an absent or empty TZ means the time zone that the user
+     has set in the Windows Control Panel.
+     If the value of TZ is of the third or fourth kind -- Cygwin programs
+     understand these syntaxes as well --, it does not matter whether we
+     neutralize it or not, since these values occur only when a Cygwin user
+     has set TZ explicitly; this case is 1. rare and 2. under the user's
+     responsibility.  */
   const char *tz = getenv ("TZ");
   if (tz != NULL && strchr (tz, '/') != NULL)
     _putenv ("TZ=");