ctime.3: clarify mktime()'s use of tm_isdst

Describe use of tm_isdst for input to mktime();
explain how mktime() modifies this field.
(This field is left unchanged in case of error.)

Reported-by: Eugene V. Lyubimkin <jackyf.devel@gmail.com>
Debian bug 500178

man3/ctime.3

@@ -227,8 +227,24 @@ the values supplied by the caller in the
 and
 .I tm_yday
 fields.
+The value specified in the
+.I tm_isdst
+field informs
 .BR mktime ()
-modifies the fields of the
+whether or not daylight saving time (DST)
+is in effect for the time supplied in the
+.I tm
+structure:
+a positive value means DST is in effect;
+zero means that DST is not in effect;
+and a negative value means that
+.BR mktime ()
+should (use timezone information and system databases to)
+attempt to determine whether DST is in effect at the specified time.
+
+The
+.BR mktime ()
+function modifies the fields of the
 .IR tm
 structure as follows:
 .I tm_wday
@@ -236,18 +252,23 @@ and
 .I tm_yday
 are set to values determined from the contents of the other fields;
 if structure members are outside their valid interval, they will be
-normalized (so that, for example, 40 October is changed into 9 November).
+normalized (so that, for example, 40 October is changed into 9 November);
+.I tm_isdst
+is set (regardless of its initial value)
+to a positive value or to 0, respectively,
+to indicate whether DST is or is not in effect at the specified time. 
 Calling
 .BR mktime ()
 also sets the external variable \fItzname\fP with
 information about the current timezone.
+
 If the specified broken-down
 time cannot be represented as calendar time (seconds since the Epoch),
 .BR mktime ()
 returns a value of
 .I (time_t)\ \-1
 and does not alter the
-\fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
+members of the broken-down time structure.
 .SH "RETURN VALUE"
 Each of these functions returns the value described, or NULL
 (\-1 in case of