August 13 C Standard Rationale on mktime; seismo's retirement

[Arthur David Olson]

The attached material appears on pages 99 and 100 of the 13 August 1987
"Rationale for Draft Proposed American National Standard for Information Systems
Programming Language C".  Note that mktime is supposed to examine tm_isdst when
converting a "struct tm" to a "time_t".  Coding errors in previous versions of
the Rationale have also been corrected, although I believe that the
	when = *localtime(now);
line should read
	when = *localtime(&now);

Seismo's retirement from the mail forwarding business makes it unlikely that
the time zone mailing list can be continued; this should not be a problem since
volume has been nonexistent of late.  If all else fails, try comp.std.c.

				--ado

4.12.2.3	The mktime function

mktime was invented by the Committee to complete the set of time functions.
With this function it becomes possible to perform portable calculations
involving clock times and broken-down times.

	The rules on the ranges of the fields within the *timeptr record are
crafted to permit useful arithmetic to be done.  For instance, here is a
paradigm for continuing some loop for an hour:

	#include <time.h>
	struct tm	when;
	time_t		now;
	time_t		deadline;

	/* ... */
	now = time(0);
	when = *localtime(now);
	when.tm_hour += 1;	/* result is in the range [1,24] */
	deadline = mktime(&when);

	printf("Loop will finish: %s\n", asctime(&when));
	while (difftime(time(0), deadline) > 0) whatever();

The specification of mktime guarantees that the addition to the tm_hour field
produces the correct result even when the new value of tm_hour is 24, i.e., a
value outside the range ever returned by a library function in a struct tm
object.

	One of the reasons for adding this function is to replace the
capability to do such arithmetic which is lost when a programmer cannot depend
on time_t being an integral multiple of some known time unit.

	Several readers of earlier versions of this Rationale have pointed out
apparent problems in this example if now is just before a transition into or
out of daylight saviings time.  However, when.tm_isdst tags what sort of time
was the basis of the calculation.  Implementors, take heed.