9.17. Date and time

These functions deal with either ‘elapsed’ or ‘calendar’ time. They share the <time.h> header, which declares the functions as necessary and also the following:

CLOCKS_PER_SEC

This is the number of ‘ticks’ per second returned by the clock function.

clock_t

time_t

These are arithmetic types used to represent different forms of time.

struct tm

This structure is used to hold the values representing a calendar time. It contains the following members, with the meanings as shown.

int tm_sec      /* seconds after minute [0-61] (61 allows for 2 leap-seconds)*/
int tm_min      /* minutes after hour [0-59] */
int tm_hour     /* hours after midnight [0-23] */
int tm_mday     /* day of the month [1-31] */
int tm_mon      /* month of year [0-11] */
int tm_year     /* current year-1900 */
int tm_wday     /* days since Sunday [0-6] */
int tm_yday     /* days since January 1st [0-365] */
int tm_isdst    /* daylight savings indicator */

The tm_isdst member is positive if daylight savings time is in effect, zero if not and negative if that information is not available.

The time manipulation functions are the following:

#include <time.h>

clock_t clock(void);
double difftime(time_t time1, time_t time2);
time_t mktime(struct tm *timeptr);
time_t time(time_t *timer);
char *asctime(const struct tm *timeptr);
char *ctime(const time_t *timer);
struct tm *gmtime(const time_t *timer);
struct tm *localtime(const time_t *timer);
size_t strftime(char *s, size_t maxsize,
  const char *format,
  const struct tm *timeptr);

The functions asctime, ctime, gmtime, localtime, and strftime all share static data structures, either of type struct tm or char [], and calls to one of them may overwrite the data stored by a previous call to one of the others. If this is likely to cause problems, their users should take care to copy any values needed.

clock

Returns the best available approximation to the time used by the current invocation of the program, in ‘ticks’. (clock_t)-1 is returned if no value is available. To find the actual time used by a run of a program, it is necessary to find the difference between the value at the start of the run and the time of interest—there is an implementation-defined constant factor which biases the value returned from clock. To determine the time in seconds, the value returned should be divided by CLOCKS_PER_SEC.

difftime

This returns the difference in seconds between two calendar times.

mktime

This returns the calendar time corresponding to the values in a structure pointed to by timeptr, or (time_t)-1 if the value cannot be represented.

The tm_wday and tm_yday members of the structure are ignored, the other members are not restricted to their usual values. On successful conversion, the members of the structure are all set to appropriate values within their normal ranges. This function is useful to find out what value of a time_t corresponds to a known date and time.

time

Returns the best approximation to the current calendar time in an unspecified encoding. (time_t)-1 is returned if the time is not available.

asctime

Converts the time in the structure pointed to by timeptr into a string of the form

Sun Sep 16 01:03:52 1973\n\0

the example being taken from the Standard. The Standard defines the algorithm used, but the important point to notice is that all the fields within that string are of constant width and relevant to most English-speaking communities. The string is stored in a static structure which may be overwritten by a subsequent call to one of the other time-manipulation functions (see above).

ctime

Equivalent to asctime(localtime(timer)). See asctime for the return value.

gmtime

Returns a pointer to a struct tm set to represent the calendar time pointed to by timer. The time is expressed in terms of Coordinated Universal Time (UTC) (formerly Greenwich Mean Time). A null pointer is returned if UTC is not available.

localtime

Converts the time pointed to by timer into local time and puts the results into a struct tm, returning a pointer to that structure.

strftime

Fills the character array pointed to by s with at most maxsize characters. The format string is used to format the time represented in the structure pointed to timeptr. Characters in the format string (including the terminating null) are copied unchanged into the array, unless one of the following format directives is found—then the value specified below is copied into the destination, as appropriate to the locale.

%a	abbreviated weekday name
%A	full weekday name
%b	abbreviated month name
%B	full month name
%c	date and time representation
%d	decimal day of month number 01–31
%H	hour 00–23 (24 hour format)
%I	hour 01–12 (12 hour format)
%j	day of year 001–366
%m	month 01–12
%M	minute 00–59
%p	local equivalent of ‘AM’ or ‘PM’
%S	second 00–61
%U	week number in year 00–53 (Sunday is first day of week
%w	weekday, 0–6 (Sunday is 0)
%W	week number in year 00–53 (Monday is first day of week
%x	local date representation
%X	local time representation
%y	year without century prefix 00–99
%Y	year with century prefix
%Z	timezone name, or no characters if no timezone exists
%%	a % character

The total number of characters copied into *s is returned, excluding the null. If there was not room (as determined by maxsize) for the trailing null, zero is returned.