[PATCH] manual: Add more documentation for the tm_isdst member of struct tm

[Florian Weimer <fweimer@redhat.com>]

The meaning of the member has changed implicitly since the IANA
tz database started releasing zone data with negative DST.

---
 manual/time.texi | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/manual/time.texi b/manual/time.texi
index 0c7a942b4c..8632bd9b77 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -1010,10 +1010,24 @@ range @code{0} through @code{365}).
 @item int tm_isdst
 @cindex Daylight Saving Time
 @cindex summer time
-This is a flag that indicates whether Daylight Saving Time is (or was, or
-will be) in effect at the time described.  The value is positive if
-Daylight Saving Time is in effect, zero if it is not, and negative if the
-information is not available.
+This field serves multiple purposes.  Historically, it is related to
+daylight saving time.
+
+When clocks move backwards (due to time zone changes, or due to the
+transition from daylight saving time to standard time), functions
+converting to a broken-down time value such as @code{localtime} may
+produce the same @code{tm_hour}, @code{tm_min}, @code{tm_sec} values for
+different input times.  The @code{tm_isdst} field is used to
+disambiguate these different points in time.  Historically, a positive
+value indicates Daylight Saving Time is in effect, and a zero value that
+it is not.  However, this interpretation depends on the data present in
+the system's time zone database.  For example, for some time zones, the
+role of positive and zero @code{tm_isdst} values are swapped in some
+years.
+
+If the broken-down time is used as an input for a conversion function in
+the other direction, such as @code{mktime}, a negative value can be
+used to indicate that the information is not available.
 
 @item long int tm_gmtoff
 This field describes the time zone that was used to compute this
@@ -1219,6 +1233,21 @@ simple time representation.  It also normalizes the contents of the
 broken-down time structure, and fills in some components based on the
 values of the others.
 
+If the @code{tm_isdst} member is not negative, its value should match a
+previous result from @code{localtime}, @code{localtime_r},
+@code{gmtime}, or @code{gmtime_r}.  If @code{tm_isdst} is negative and
+the calendar time is not ambiguous, @code{mktime} will use this time.
+For ambiguous inputs with a negative @code{tm_isdst} value, an arbitrary
+choice is made.  If a non-negative value was specified for
+@code{tm_isdst} and the system time zone database contains data
+conflicting with the request in @code{tm_isdst}, @code{mktime} attempts
+to adjust the computed result in an unspecified way.  Given that the
+system time zone database does not necessarily map @code{tm_isdst}
+values to popular notions of daylight saving time and standard time,
+using a negative @code{tm_isdst} value as input to @code{mktime} is
+generally preferable to letting the user input whether daylight saving
+time is in effect or not.
+
 The @code{mktime} function ignores the specified contents of the
 @code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone}
 members of the broken-down time
@@ -1226,7 +1255,9 @@ structure.  It uses the values of the other components to determine the
 calendar time; it's permissible for these components to have
 unnormalized values outside their normal ranges.  The last thing that
 @code{mktime} does is adjust the components of the @var{brokentime}
-structure, including the members that were initially ignored.
+structure, including the members that were initially ignored.  The
+@code{tm_isdst} member is updated to reflect the time zone status of the
+system time zone database at the specified time.
 
 If the specified broken-down time cannot be represented as a simple time,
 @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify

base-commit: 8775479804cfea2bbe4dcdf19d6589264c96d5fb