C Reference ยท ctype.h, math.h and others
C mktime() and difftime() functions
Reference for mktime() and difftime(): convert a local struct tm to time_t, normalize out-of-range fields, add days and months, and handle daylight saving.
mktime() is the inverse of localtime(): it converts a broken-down local time (struct tm) into a time_t. It also normalizes the structure, which makes it the standard tool for date arithmetic in C. Set tm_mday to 45, and mktime() carries the excess into the following month and fixes up the other fields, including the weekday and day of the year.
difftime() subtracts two time_t values and returns the difference in seconds as a double, so it works even where time_t is not a plain integer.
#include <time.h> struct tm tm = { .tm_year = 124, .tm_mon = 0, .tm_mday = 31 + 30, .tm_isdst = -1 }; time_t t = mktime(&tm); /* tm now holds 2024-03-01 */
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
time_t mktime(struct tm *timeptr); double difftime(time_t time1, time_t time0); time_t timegm(struct tm *timeptr); /* C23; widely available earlier as an extension */
| Name | Description |
|---|---|
timeptr |
The broken-down local time to convert. Fields tm_wday and tm_yday are ignored on input and set on output; all others are normalized into their normal ranges. |
time1, time0 |
The two calendar times for difftime(); the result is time1 - time0. |
For mktime(), set tm_isdst to 0 (standard time), a positive value (daylight saving) or -1 (decide from the date).
Returns: mktime() returns the time_t value, or (time_t)(-1) if the date cannot be represented. difftime() returns seconds as a double.
Errors / undefined behavior: if the result cannot be represented, mktime() returns -1 and the contents of *timeptr are unspecified. Note that -1 is also a valid time (one second before 1970), so a successful call can theoretically return it too.
Usage notes
- Zero-initialize and set
tm_isdst = -1.struct tm tm = {0};givestm_isdst = 0, which forces standard time and makes summer dates off by an hour. Use-1unless you know better. - The input is local time. To interpret a
struct tmas UTC, usetimegm()(C23, and available in glibc, musl and BSD), or setTZto UTC as the examples do._mkgmtimeis the Windows name. - Normalization is the feature. Months outside 0-11, days outside the month, negative hours, and so on are all legal input. This is the safest way to add or subtract days and months: change the field, then call
mktime(). - "Add one month" is not well defined. January 31 plus a month becomes March 2 or 3 after normalization, not February 28. If you want clamping, check
tm_mdayafter the call and reset to the last day of the previous month. - Do not add
86400 * nseconds to atime_tto move by days in local time: on a daylight-saving day that lands an hour off. Normalize withmktime()instead. Adding seconds is correct for durations. - Nonexistent and repeated times: during a spring-forward gap or a fall-back overlap, the result for a time that falls in the gap or overlap is implementation-defined. Avoid local midnight arithmetic if exact results around transitions matter; work in UTC.
- Check for -1. Especially with user-supplied years.
difftime()is the portable subtraction and returns a floating-point number, so format it with%.0for cast carefully. With integertime_ton common platforms(long long)(a - b)is equivalent.- Local time depends on the
TZenvironment, so tests should fix it withsetenv("TZ", ...)plustzset(), as above. - Standard version: C89 (
mktime,difftime);timegmis C23.