16.10. Date and Time

The header time.h declares the standard library functions to obtain the current date and time , to perform certain conversions on date and time information, and to format it for output. A key function is time( ), which yields the current calendar time in the form of an arithmetic value of the type time_t. This is usually encoded as the number of seconds elapsed since a specified moment in the past, called the epoch. The Unix epoch is 00:00:00 o'clock on January 1, 1970, UTC (Coordinated Universal Time, formerly called Greenwich Mean Time or GMT).

There are also standard functions to convert a calendar time value with the type time_t into a string or a structure of type struct tm. The structure type has members of type int for the second, minute, hour, day, month, year, day of the week, day of the year, and a Daylight Saving Time flag (see the description of the gmtime( ) function in Chapter 17). Table 16-23 lists all the date and time functions.

Table 16-23. Date and time functions

Purpose	Function
Get the amount of CPU time used	clock( )
Get the current calendar time	time( )
Convert calendar time to struct tm	gmtime( )
Convert calendar time to struct tm with local time values	localtime( )
Normalize the values of a struct tm object and return the calendar time with type time_t	mktime( )
Convert calendar time to a string	ctime( ), strftime( ), wcsftime( )

The extremely flexible strftime( ) function uses a format string and the LC_TIME locale category to generate a date and time string. You can query or change the locale using the setlocale( ) function. The function wcsftime( ) is the wide-string version of strftime( ), and is declared in the header wchar.h rather than time.h.

The diagram in Figure 16-1 offers an organized summary of the available date and time functions.

Figure 16-01. Date and time functions