mktime() Function

The mktime() function in C time.h converts a broken-down time, represented by a struct tm, into a time_t value that represents the corresponding local calendar time. This conversion is especially useful when you need to perform time arithmetic or comparisons using a single numeric value.

Syntax of mktime()

</>
Copy
time_t mktime(struct tm *timeptr);

Parameters

ParameterDescription
timeptrPointer to a struct tm containing a broken-down local time.

This function not only converts the given time components into a time_t value but also automatically adjusts any out-of-range values (such as an invalid day of the month) and updates the tm_wday and tm_yday fields of the structure accordingly.

Return Value

The function returns a time_t value corresponding to the local time described by the provided struct tm. If the specified calendar time cannot be represented, it returns -1.

Examples for mktime()

Example 1: Basic Conversion of a Valid Date and Time

This example demonstrates how to convert a correctly filled struct tm into a time_t value using mktime().

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    struct tm t = {0};

    // Setting date: July 15, 2021 10:30:00
    t.tm_year = 2021 - 1900;  // Years since 1900
    t.tm_mon  = 7 - 1;        // Months since January (0-11)
    t.tm_mday = 15;           // Day of the month
    t.tm_hour = 10;
    t.tm_min  = 30;
    t.tm_sec  = 0;

    time_t time_val = mktime(&t);
    if (time_val == -1) {
        printf("mktime() failed to convert time.\n");
    } else {
        printf("The time_t value is: %ld\n", time_val);
    }
    return 0;
}

Explanation:

  1. A struct tm is initialized with the desired date and time components.
  2. The mktime() function converts this structured time into a time_t value.
  3. The program checks if the conversion was successful and prints the resulting value.

Program Output:

The time_t value is: 1626345000

Example 2: Handling Out-of-Range Date Components

This example illustrates how mktime() automatically adjusts a struct tm when provided with out-of-range values, such as an invalid day of the month.

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    struct tm t = {0};

    // Setting an out-of-range day: April 40, 2021 (April has only 30 days)
    t.tm_year = 2021 - 1900;
    t.tm_mon  = 4 - 1;        // April
    t.tm_mday = 40;           // Out-of-range day
    t.tm_hour = 12;
    t.tm_min  = 0;
    t.tm_sec  = 0;

    time_t time_val = mktime(&t);
    if (time_val == -1) {
        printf("mktime() failed to convert time.\n");
    } else {
        // The function adjusts the date to a valid calendar date.
        printf("Adjusted date: %d-%d-%d\n", t.tm_year + 1900, t.tm_mon + 1, t.tm_mday);
        printf("The time_t value is: %ld\n", time_val);
    }
    return 0;
}

Explanation:

  1. A struct tm is set with an out-of-range day (40th day of April).
  2. mktime() normalizes the date, adjusting it to a valid date (which falls in May).
  3. The program prints the adjusted date and the corresponding time_t value.

Program Output:

Adjusted date: 2021-5-10
The time_t value is: 1620648000

Example 3: Automatic Update of tm_wday and tm_yday Fields

This example demonstrates how mktime() updates the tm_wday (day of the week) and tm_yday (day of the year) fields of the struct tm after conversion.

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    struct tm t = {0};

    // Setting date: December 31, 2021 23:59:59
    t.tm_year = 2021 - 1900;
    t.tm_mon  = 12 - 1;
    t.tm_mday = 31;
    t.tm_hour = 23;
    t.tm_min  = 59;
    t.tm_sec  = 59;

    time_t time_val = mktime(&t);
    if (time_val == -1) {
        printf("mktime() failed to convert time.\n");
    } else {
        printf("Updated tm_wday (day of week): %d\n", t.tm_wday);
        printf("Updated tm_yday (day of year): %d\n", t.tm_yday);
        printf("The time_t value is: %ld\n", time_val);
    }
    return 0;
}

Explanation:

  1. A struct tm is initialized with the date and time for December 31, 2021.
  2. Upon calling mktime(), the function calculates and updates the tm_wday and tm_yday fields based on the provided date.
  3. The program prints these updated fields along with the resulting time_t value.

Program Output:

Updated tm_wday (day of week): 5
Updated tm_yday (day of year): 364
The time_t value is: 1640995199