New draft C standard

Arthur David Olson ado
Sat Nov 21 22:41:22 UTC 1987


I got the latest, November 9, 1987 draft C standard in the mail
yesterday.

The good news:  there's a footnote telling how to get a
broken-down wall clock time converted into "elapsed seconds since the epoch"
(or whatever the implementation is choosing to use) *without* having to know
whether the time being converted is Daylight Time or not:
you're supposed to drop a -1 into the "tm_isdst" field.

The bad news:  this mechanism is described in a footnote,
and, unfortunately, footnotes are not part of the Standard (as is
explained at the start of the Standard).  (There's other stuff relegated
to footnotes that might better be made part of the Standard, but that's
a different soapbox.)

Giving a choice of lobbying to get the footnote's content moved into the
Standard or dropping mktime entirely, I'd choose the second
alternative, but I realize I'm getting crabbier as I get older.

I've attached a transcribed version of the latest wording.

				--ado


4.12  DATE AND TIME <time.h>

4.12.1  Components of time

	The header <time.h> declares one macro, three types, and several
functions for manipulating time.  Many functions deal with a calendar
time that represents the current date (according to the Gregorian
calendar) and time.  Some functions deal with local time, which is the
calendar time expressed for some specific time zone, and with Daylight
Saving Time, which is a temporary change in the algorithm for
determining local time.  The local time zone and Daylight Saving Time
are implementation defined.

	The macro defined is
		CLK_TCK
which is the number per second of the value returned by the clock
function.  The types declared are
		clock_t
and
		time_t
which are arithmetic types capable of representing times, and
		struct tm
which holds the components of a calendar time, called the broken-down
time.  The structure shall contain at least the following members, in
any order.  The semantics of the members and their normal ranges are
expressed in the comments.
		int tm_sec;	/* seconds after the minute - [0,59] */
		int tm_min;	/* minutes after the hour - [0,59] */
		int tm_hour;	/* hours since midnight - [0,23] */
		int tm_mday;	/* day of the month - [1,31] */
		int tm_mon;	/* months since January - [0,11] */
		int tm_year;	/* years since 1900 */
		int tm_wday;	/* days since Sunday - [0,6] */
		int tm_yday;	/* days since January 1 - [0,365] */
		int tm_isdst;	/* Daylight Saving Time flag */
The value of tm_isdst is positive if Daylight Saving Time is in effect,
zero if Daylight Saving Time is not in effect, and negative if the
information is not available.

4.12.2  Time manipulation functions

4.12.2.1  The clock function

		[SECTION OMITTED]

4.12.2.2  The difftime function

		[SECTION OMITTED]

4.12.2.3  The mktime function

Synopsis
		#include <time.h>
		time_t mktime(struct tm *timeptr);

Description
	The mktime function converts the broken-down time, expressed as
local time, in the structure pointed to by timeptr into a calendar time
value with the same encoding as that of the values returned by the time
function.  The original values of the tm_wday and tm_yday components of
the structure are ignored, and the original values of the         101
other components are not restricted to the ranges indicated above.
On successful completion, the values of the tm_wday and tm_yday
components of the structure are set appropriately, and the other
components are set to represent the specified calendar time, but with
their values forced to the ranges indicated above; the final value of
tm_mday is not set until tm_mon and tm_year are determined.

Returns
	The mktime function returns the specified calendar time encoded
as a value of type time_t.  If the calendar time cannot be represented,
the function returns the value (time_t)-1.

Example
	What day of the week is July 4, 2001?

		#include <stdio.h>
		#include <time.h>
		static const char *const wday[] = {
			"Sunday", "Monday", "Tuesday", "Wednesday",
			"Thursday", "Friday", "Saturday", "-unknown-"
		};
		struct tm time_str;

		time_str.tm_year	= 2001 - 1900;
		time_str.tm_mon		= 7 - 1;
		time_str.tm_mday 	= 4;
		time_str.tm_hour	= 0;
		time_str.tm_min		= 0;
		time_str.tm_sec		= 1;
		time_str.tm_isdst	= -1;
		if (mktime(&time_str) == -1)
			time_str.tm_wday = 7;
		printf("%s\n", wday[time_str.tm_wday]);

4.12.2.4  The time function

Synopsis
		#include <time.h>
		time_t time(time_t *timer);

Description
	The time function determines current calendar time.  The
encoding of the value is unspecified.

Returns
	The time function returns the implementation's best
approximation to the current calendar time.  The value (time_t)-1 is
returned if the calendar time is not available.  If timer is not a null
pointer, the return value is also assigned to the object it points to.
____________

101.  A positive or zero value for tm_isdst causes the mktime function
	initially to presume that Daylight Saving Time, respectively, is
	or is not in effect for the specified time.  A negative value
	for tm_isdst causes the mktime function to attempt to determine
	whether Daylight Saving Time is in effect for the specified
	time.



More information about the tz mailing list