1.24 Time and Date

The ANSI C library includes a set of functions to determine the current time and date, to convert time and date information, and to generate formatted time and date strings for output. These functions are declared in the header file time.h.

The principal functions for determining the current time are:

clock_t clock( void );

Returns the CPU time used by the program so far, with type clock_t (usually equivalent to long). The result can be converted to seconds by dividing it by the constant CLOCKS_PER_SEC.

time_t time ( time_t *pSec  );

Returns the number of seconds that have elapsed since a certain time (usually January 1, 1970, 00:00:00 o'clock). If the pointer pSec is not NULL, the result is also copied to the location it addresses. The type time_t is generally defined as long.

The functions for converting and formatting date and time information are:

double difftime ( time_t t1 , time_t t0  );

Returns the number of seconds between t0 and t1.

struct tm *gmtime ( const time_t *pSec  ); 

Returns a pointer to the current Greenwich Mean Time as a structure of type struct tm, with members of type int for the second, minute, hour, day, etc.

struct tm *localtime ( const time_t *pSec  ); 

Like gmtime(), but returns the local time rather than Greenwich Mean Time.

char *ctime ( const time_t *pSec  );
char *asctime ( const struct tm *ptm  );
size_t strftime (char *dest , size_t maxsize ,
                const char *format , const struct tm *ptm  );

These functions generate a string representing the local date and time. strftime() accepts a format string to control the output format.

The function wcsftime() is a version of strftime() for wide-character strings, and is declared in the header file wchar.h(*).

Figure 1-6 illustrates the uses of the time and date functions.

Figure 1-6. Usage of time and date functions