That same attention to detail has spilled over into the Standard C library. Its scope is basically whatever was available in C under UNIX that didn't depend on the peculiarities of UNIX. As a consequence, you can do a lot with times and dates in Standard C. The functions declared in <time. h> provide the relevant services.

It stretches the truth a bit to say that these functions don't depend on the peculiarities of UNIX. Not all operating systems distinguish between local time and UTC. Even fewer allow different users to display times relative to different time zones. Some of the smallest systems can't even give you the time of day. Yet all implementations of C must take a stab at telling time wisely if they want to claim conformance to the C Standard.

The C Standard contains enough weasel words to let nearly everybody off the hook. A system need only provide its "best approximation" to the current time and date, or to processor time consumed, to conform to the C Standard. A vendor could argue that 1 January 1980 is always the best available approximation to any time and date. A customer can rightly quarrel about the low quality of such an approximation, but not whether it satisfies the C Standard.

What this means in practice is that a program should never take times too seriously. It can enquire about the current time (by calling time) and display what it gets in a variety of attractive formats. But it can't know for sure that the time and date are meaningful. If you have an application that depends critically upon accurate time stamps, check each implementation of Standard C closely.

There are too many functions declared in <time.h> to cover in one installment. So I've divided the presentation into three parts:

• the basic time functions — those that yield results of type clock_t, time_t, or double
• the conversion functions — those that convert times between scalar and structured forms
• the formatting functions — those that yield text representations of encoded times

The macros defined are NULL (described in 7.1.6); and

CLOCKS_PER_SEC

The types declared are size_t (described in 7.1.6);

clock t

time_t

struct tm

int tm_sec;
/* seconds after the minute- [0, 61] */
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 */

   #include <time.h>
   clock_t clock(void);

   #include <time.h>
   double difftime(time_t time1, time_t time0);

.....

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

Footnotes

137. The range [0, 61] for tm_see allows for as many as two leap seconds.

138. In order to measure the time spent in a program, the clock function should be called at the start of the program and its return value subtracted from the value returned by subsequent calls.

• type clock_t for elapsed processor time, as returned by the primitive function clock
• type time_t for calendar time, as returned by the primitive function time or the function mktime
• type double for calendar time in seconds, as returned by the function difftime
• type struct tm for calendar time broken down into separate components, as returned by the functions gmtime and localtime
• a text string for calendar time, as returned by the functions asctime, ctime, and strftime

Here is a brief description of the individual types and macros defined in <time.h>. It is followed by brief notes on how to use the basic time functions declared in <time.h>.

NULL — See "The Header <stddef. h>," CUJ December 1991.

CLOCKS_PER_SEC — The expression clock() / CLOCKS_PER_SEC measures elapsed processor time in seconds. The macro can have any arithmetic type, either integer or floating point. Type cast it to double to ensure that you can represent fractions of a second as well as a wide range of values.

clock_t — This is the arithmetic type returned by clock, described below. It represents elapsed processor time. It can have any integer or floating-point type, which need not be the same type as the macro CLOCKS_PER_SECOND, above.

size_t — See "The Header <stddef.h >," CUJ December 1991.

time_t — This is the arithmetic type returned by time, described below. Several other functions declared in <time.h> also manipulate values of this type. It represents calendar times that span years, presumably to the nearest second (although not necessarily). Don't attempt to perform arithmetic on a value of this type.

tm — A structure of type struct tm represents a "broken-down time." Several functions declared in <time.h> manipulate values of this type. You can access certain members of struct tm. Its definition looks something like:

struct tm {
   int tm_sec;
/* seconds after the minute (from 0) */
   int tm_min;
/* minutes after the hour (from 0) */
   int tm_hour;
/* hour of the day (from 0) */
   int tm_mday;
/* day of the month (from 1) */
   int tm_mon;
/* month of the year (from 0) */
   int tm_year;
/* years since 1900 (from 0) */
   int tm_wday;
/* days since Sunday (from 0) */
   int tm_yday;
/* day of the year (from 0) */
   int tm_isdst;
/* DST flag */

clock — This function measures elapsed processor time instead of calendar time. It returns -1 if that is not possible. Otherwise, each call should return a value equal to or greater than an earlier call during the same program execution. It is the best measure you can get of the time your program actually consumes. See the macro CLOCKS_PER_SEC, above.

difftime — The only safe way compute the difference between two times t1 and t0 is by calling difftime(t1, t0). The result, measured in seconds, is positive if t1 is a later time than t0.

time — This function determines the current calendar time. It returns -1 if that is not possible. Otherwise, each call should return a value at the same time or later than an earlier call during the same program execution. It is the best estimate you can get of the current time and date.

References

This article is excerpted in part from P.J. Plauger, The Standard C Library, (Englewood Cliffs, N.J.: Prentice-Hall, 1992).