are arithmetic because values of these types must,
in accordance with existing practice,
on occasion be compared with -1 (a ``don't-know'' indication)
No arithmetic properties of these types are defined by the Standard, however,
in order to allow implementations the maximum flexibility in
choosing ranges, precisions, and representations most appropriate to
their intended application.
The representation need not be a count of some basic unit;
an implementation might conceivably represent different components of
a temporal value as subfields of an integral type.
Many C environments do not support the
Base Document library concepts
of daylight savings or time zones.
Both notions are defined geographically and politically,
and thus may require more knowledge about the real world than
an implementation can support.
Hence the Standard specifies the date and time functions
such that information about DST and time zones is not required.
The Base Document function
which would require dealing with time zones, has been
An implementation reports that information about DST is not
available by setting the
field in a broken-down time to a negative value.
An implementation may return a null pointer from a call to
if information about the displacement
between Universal Time (née GMT) and local time is
The function is intended for measuring intervals of execution time, in whatever units an implementation desires. The conflicting goals of high resolution, long interval capacity, and low timer overhead must be balanced carefully in the light of this intended use.
is an invention of the Committee.
It is provided so that an implementation can store an indication
of the date/time value in the most efficient format possible and still provide
a method of calculating the difference between two times.
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
are crafted to permit useful arithmetic to be done.
For instance, here is a paradigm for continuing some loop for an
#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(deadline,time(0)) > 0 ) whatever();The specification of
mktimeguarantees that the addition to the
tm_hourfield produces the correct result even when the new value of
tm_houris 24, i.e., a value outside the range ever returned by a library function in a
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
is just before a transition into or out of daylight savings time.
when.tm_isdst indicates what sort of time was the basis of the
Implementors, take heed.
If this field is set to -1 on input, one truly ambiguous case
involves the transition out of daylight savings time.
As DST is currently legislated in the USA, the hour 0100--0159 occurs
twice, first as DST and then as standard time. Hence an unlabeled
0130 on this date is problematic. An implementation may choose to
take this as DST or standard time, marking its decision in the
field. It may also legitimately take this as invalid input (and
Since no measure is given for how precise an implementation's best approximation to the current time must be, an implementation could always return the same date, instead of a more honest -1. This is, of course, not the intent.
strftimefunction (§18.104.22.168) provides appropriate facilities for locale-specific date and time strings.
This function has been retained, despite objections that GMT --- that is, Coordinated Universal Time (UTC) --- is not available in some implementations, since UTC is a useful and widespread standard representation of time. If UTC is not available, a null pointer may be returned.
strftime provides a way of formatting the date and time in
the appropriate locale-specific fashion, using the
%X format specifiers.
More generally, it allows the programmer to tailor whatever date and
time format is appropriate for a given application.
The facility is based on the UNIX system
See §4.4 for further discussion of locale specification.
For the field controlled by
%P, an implementation may
wish to provide special symbols to mark noon and midnight.