C Library – <time.h> – The Geek Diary

The Time library provides the data structures and functions required to retrieve the system time, perform time calculations, and output formatted strings that allow the time to be displayed in a variety of common formats. Time is stored as ticks since 1 Jan 1970, midnight, known as UTC. This value must be converted to be of use, either into a structure or formatted output.

The time.h header file defines two macros. The first, also defined in many other header files, is NULL, representing the null pointer. The second macro is CLOCKS_PER_SEC; dividing the value returned by clock() by this macro yields time in seconds.

Library Variables

The header file defines the types listed below:

Type	Description
size_t	The integer type returned by the sizeof operator.
clock_t	An arithmetic type suitable to represent time.
time_t	An arithmetic type suitable to represent time.
struct tm	A structure type for holding components of calendar time.

The components of the calendar type are referred to as broken-down time. Table below lists the required members of a struct tm structure.

Member	Description
int tm_sec	Seconds after the minute (0-61)
int tm_min	Minutes after the hour (0-59)
int tm_hour	Hours after midnight (0-23)
int tm_mday	Day of the month (0-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 Savings Time flag (greater than zero value means DST is in effect; zero means not in effect; negative means information not available)

So to get the correct year from the tm structure, you need to use the following:

struct tm * myTime; // Pointer to tm structure
myTime = localtime ( time (NULL) ); // Get the time
printf ( "The year is %d", myTime.tm_year + 1900 );

Notice that this code snippet introduces another function, local time. This function takes the current time expressed in clock ticks and returns a pointer to a tm structure:

localtime (  )
               // returns pointer to tm structure, from time

The return value is the time, adjusted for local parameters (such as Daylight Savings Time). The value placed into the function was the return value from another function, time, which simply returns the current number of clock ticks, as discussed previously.

time ( )        returns current UTC

There is a companion function, gmtime, which returns a pointer to the same structure as before, so it is overwritten but expressed in GMT. The definition is the same as for localtime:

gmtime (  )
     // returns a pointer to tm structure, from time, in GMT

If you want to calculate the difference between two times, you can do so using the difftime function, which takes two UTC values:

difftime ( ,  )
       // returns difference between two times

The return value can then be supplied to a call to gmtime (for example) to populate a tm structure. For completeness, note also that you can convert a tm structure into a UTC value using:

mktime (  )
       // returns UTC from tm structure

If you would rather report the number of clock ticks since the process started, you can use the clock function:

clock ( )
      // returns clock ticks since process start

Because the value of a clock tick is platform dependent, a constant CLK_TCK gives the relation between clock ticks and seconds. To calculate the number of seconds that a clock tick value represents, you can use code such as:

nNumSeconds = lClockTicks / CLK_TCK;

Finally, there are some useful functions that return pointers to a statically maintained string containing formatted time values. You need to remember to copy this string if you want to preserve the value between calls to the conversion functions, of which there are two:

ctime (  )
      // returns string from UTC
asctime ()
      // returns string from pointer to a tm structure

The ctime function returns a string that is formatted as follows:

Www Mmm dd hh:mm:ss yyyy

Where Www is the abbreviated week day, Mmm is the abbreviated month name, and dd is the day of the month. The other values should be self-explanatory. The ctime function returns the local time.

The companion function takes a pointer to a tm structure and returns a string of the same format as ctime from it. The asctime function is defined as:

asctime (  )
   // returns string from pointer to tm

These functions represent the only possibilities for time handling and formatting in the C libraries. However, various implementations extend the ANSI definitions to provide even more formatting possibilities.

Time Functions

The term calendar time represents the current date and time; for example, it could be the number of seconds elapsed since the first second of 1900. The term local time is the calendar time expressed for a local time zone. Table below lists the time functions.

Prototype	Description
clock_t clock(void);	Returns the implementation’s best approximation to the processor time elapsed since the program was invoked; divide by CLOCKS_PER_SEC to get the time in seconds; returns (clock_t)(-1) if the time is not available or representable.
double difftime(time_t t1, time_t t0);	Calculates the difference (t1 – t0) between two calendar times, expresses the result in seconds, and returns the result.
time_t mktime(struct tm *tmptr);	Converts the broken-down time in the structure pointed to by tmptr into a calendar time; having the same encoding used by the time() function, the structure is altered in that out-of-range values are adjusted (for example, 2 minutes, 100 seconds becomes 3 minutes, 40 seconds) and tm_wday and tm_yday are set to the values implied by the other members; returns (time_t)(-1) if the calendar time cannot be represented; otherwise, returns the calendar time in time_t format.
time_t time(time_t *ptm)	Returns the current calendar time and also places it in the location pointed to by ptm, providing ptm is not NULL; returns (time_t)(-1) if the calendar time is not available.
char asctime(const struct tm tmpt);	Converts the broken-down time in the structure pointed to by tmpt into a string of the form Thu Feb 26 13:14:33 1998\n\0 and returns a pointer to that string.
char ctime(const time_t ptm); Wed Aug 11 10:48:24 1999\n\0	Converts the calendar time pointed to by ptm into a string of the form and returns a pointer to that string.
struct tm gmtime(const time_t ptm);	Converts the calendar time pointed to by ptm into a broken-down time, expressed as Coordinated Universal Time (UCT), and returns a pointer to a structure holding that information; returns NULL if UTC is not available.
struct tm localtime(const time_t ptm);	Converts the calendar time pointed to by ptm into a broken-down time, expressed as local time; stores a tm structure and returns a pointer to that structure.
size_t strftime(char s, size_t max, const char fmt, const struct tm *tmpt);	Copies string fmt to string s, replacing format specifiers (see Table F.20) in fmt with appropriate data derived from the contents of the broken-down time structure pointed to by tmpt; no more than max characters are placed into s; the function returns the number of characters placed (excluding the null character); if the resulting string (including null character) is larger than maxcharacters, the function returns 0 and the contents of s are indeterminate.