4.12  Date and Time  <time.h>

4.12.1  Components of time

The types clock_t and time_t are arithmetic because values of these types must, in accordance with existing practice, on occasion be compared with -1  (a ``don't-know'' indication) suitably cast.  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 tzset, which would require dealing with time zones, has been excluded altogether.  An implementation reports that information about DST is not available by setting the tm_isdst field in a broken-down time to a negative value.  An implementation may return a null pointer from a call to gmtime if information about the displacement between Universal Time (née GMT) and local time is not available. 

4.12.2  Time manipulation functions

4.12.2.1  The clock function

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. 

4.12.2.2  The difftime function

difftime 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. 

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(deadline,time(0)) > 0 ) whatever();

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 savings time.  However, when.tm_isdst indicates what sort of time was the basis of the calculation. 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 tm_isdst field. It may also legitimately take this as invalid input (and return (time_t)(-1)).

4.12.2.4  The time function

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. 

4.12.3  Time conversion functions

4.12.3.1  The asctime function

4.12.3.2  The ctime function

4.12.3.3  The gmtime function

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. 

4.12.3.4  The localtime function

4.12.3.5  The strftime function

strftime provides a way of formatting the date and time in the appropriate locale-specific fashion, using the %c, %x, and %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 date command.  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.