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 (
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 (
If you want to calculate the difference between two times, you can do so using the difftime function, which takes two UTC values:
difftime (
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. |