Skip to content
Tutorials Center
My learning

Topics

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.

C
#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

C Adding days and months by normalization

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.

C Daylight saving time changes the length of a day

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

C
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}; gives tm_isdst = 0, which forces standard time and makes summer dates off by an hour. Use -1 unless you know better.
  • The input is local time. To interpret a struct tm as UTC, use timegm() (C23, and available in glibc, musl and BSD), or set TZ to UTC as the examples do. _mkgmtime is 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_mday after the call and reset to the last day of the previous month.
  • Do not add 86400 * n seconds to a time_t to move by days in local time: on a daylight-saving day that lands an hour off. Normalize with mktime() 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 %.0f or cast carefully. With integer time_t on common platforms (long long)(a - b) is equivalent.
  • Local time depends on the TZ environment, so tests should fix it with setenv("TZ", ...) plus tzset(), as above.
  • Standard version: C89 (mktime, difftime); timegm is C23.