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:
- This is the number of ‘ticks’ per second returned by the
- These are arithmetic types used to represent different forms of time.
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 */
tm_isdstmember 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);
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.
- Returns the best available approximation to the time used by the
current invocation of the program, in ‘ticks’.
(clock_t)-1is 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
- This returns the difference in seconds between two calendar times.
This returns the calendar time corresponding to the values in a structure pointed to by
(time_t)-1if the value cannot be represented.
tm_ydaymembers 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_tcorresponds to a known date and time.
- Returns the best approximation to the current calendar time in an
(time_t)-1is returned if the time is not available.
Converts the time in the structure pointed to by
timeptrinto 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).
- Equivalent to
asctimefor the return value.
- Returns a pointer to a
struct tmset 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.
- Converts the time pointed to by
timerinto local time and puts the results into a
struct tm, returning a pointer to that structure.
Fills the character array pointed to by
swith at most
formatstring 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.
abbreviated weekday name
full weekday name
abbreviated month name
full month name
date and time representation
decimal day of month number 01–31
hour 00–23 (24 hour format)
hour 01–12 (12 hour format)
day of year 001–366
local equivalent of ‘AM’ or ‘PM’
week number in year 00–53 (Sunday is first day of week
weekday, 0–6 (Sunday is 0)
week number in year 00–53 (Monday is first day of week
local date representation
local time representation
year without century prefix 00–99
year with century prefix
timezone name, or no characters if no timezone exists
The total number of characters copied into
*sis returned, excluding the null. If there was not room (as determined by
maxsize) for the trailing null, zero is returned.