C Standard Library time.h

What You’ll Learn

<time.h> lets C programs work with real-world clocks: stamp log entries, print today’s date, measure how long something took, or seed random numbers with time(NULL). You will use time_t for “seconds since epoch,” struct tm for calendar fields, and strftime for readable output.

Definition and Usage

Calendar time counts forward from a fixed moment (the Unix epoch: 1970-01-01 00:00:00 UTC). time() returns that count as time_t. To show hours and minutes humans understand, convert with localtime or gmtime into struct tm, then format with strftime.

For benchmarking code, clock() measures processor time (ticks divided by CLOCKS_PER_SEC). For wall-clock delays between events, use time() and difftime().

📝 Syntax

Include the header:

#include <time.h>

Key types and macros

• time_t — arithmetic type for calendar time (usually seconds since epoch)
• struct tm — broken-down time: tm_year, tm_mon, tm_mday, tm_hour, etc.
• clock_t — processor time ticks
• CLOCKS_PER_SEC — ticks per second for clock()
• NULL — pass to time(NULL) if you do not need to store the value yet

Common functions

• time(&t) / time(NULL) — current calendar time
• localtime(&t) — struct tm * in local timezone
• gmtime(&t) — struct tm * in UTC
• mktime(&tm) — convert struct tm (local) back to time_t
• strftime(buf, size, format, &tm) — format date/time string
• difftime(t1, t2) — t1 - t2 in seconds as double
• clock() — processor time used so far
• ctime(&t) — quick string (non-reentrant; prefer strftime)

struct tm field notes

tm_year  /* years since 1900 — 2026 is 126 */
tm_mon   /* 0–11 — January is 0 */
tm_mday  /* 1–31 */
tm_hour  /* 0–23 */
tm_min, tm_sec

Common strftime specifiers

• %Y — 4-digit year; %m month; %d day
• %H — hour 00–23; %M minute; %S second
• %I — hour 01–12 (12-hour clock); %p AM/PM
• %A — full weekday name; %B full month name

Headers and linking

• #include <time.h> — linked automatically on most systems.
• Pairs with <stdio.h> for printing formatted times.
• Compile: gcc program.c -std=c11 -o program.

Examples Gallery

Compile with gcc file.c -std=c11 -o out. Date/time output depends on when and where you run the program.

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

int main(void) {
    time_t current_time;
    struct tm time_copy;
    char buffer[80];

    if (time(&current_time) == (time_t)(-1)) {
        fprintf(stderr, "time() failed\n");
        return 1;
    }

    time_copy = *localtime(&current_time);

    if (strftime(buffer, sizeof(buffer),
                 "Current date and time: %Y-%m-%d %H:%M:%S",
                 &time_copy) == 0) {
        fprintf(stderr, "strftime buffer too small\n");
        return 1;
    }

    printf("%s\n", buffer);
    printf("Epoch seconds: %lld\n", (long long)current_time);

    return 0;
}

Current date and time: 2026-07-05 16:30:00
Epoch seconds: 1751721000

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

int main(void) {
    time_t start = time(NULL);
    volatile unsigned long i;
    time_t end;

    for (i = 0; i < 300000000UL; i++) {
        /* busy work */
    }

    end = time(NULL);
    printf("Elapsed (whole seconds): %.0f\n", difftime(end, start));

    return 0;
}

Elapsed (whole seconds): 0 or 1

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

int main(void) {
    clock_t start = clock();
    volatile unsigned long i;
    clock_t end;
    double cpu_seconds;

    for (i = 0; i < 50000000UL; i++) {
        /* work */
    }

    end = clock();
    cpu_seconds = (double)(end - start) / (double)CLOCKS_PER_SEC;

    printf("CPU time used: %.4f seconds\n", cpu_seconds);
    printf("CLOCKS_PER_SEC = %ld\n", (long)CLOCKS_PER_SEC);

    return 0;
}

CPU time used: 0.0523 seconds
CLOCKS_PER_SEC = 1000

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

int main(void) {
    time_t now = time(NULL);
    struct tm local = *localtime(&now);
    struct tm utc = *gmtime(&now);
    char buf_local[64];
    char buf_utc[64];

    strftime(buf_local, sizeof(buf_local), "Local: %Y-%m-%d %H:%M:%S", &local);
    strftime(buf_utc, sizeof(buf_utc),     "UTC:   %Y-%m-%d %H:%M:%S", &utc);

    printf("%s\n", buf_local);
    printf("%s\n", buf_utc);

    return 0;
}

Local: 2026-07-05 16:30:00
UTC:   2026-07-05 11:00:00

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

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

    t.tm_year = 2026 - 1900;  /* 2026 */
    t.tm_mon  = 6 - 1;        /* June */
    t.tm_mday = 15;
    t.tm_hour = 9;
    t.tm_min  = 30;
    t.tm_sec  = 0;

    time_t when = mktime(&t);
    char buffer[64];

    if (when == (time_t)(-1)) {
        fprintf(stderr, "mktime failed\n");
        return 1;
    }

    strftime(buffer, sizeof(buffer), "Built date: %A, %B %d %Y %H:%M", &t);
    printf("%s\n", buffer);
    printf("Epoch: %lld\n", (long long)when);

    return 0;
}

Built date: Monday, June 15 2026 09:30
Epoch: 1781505600

🚀 Common Use Cases

• Log timestamps — strftime on each log line.
• File names — backup_%Y%m%d.dat from current time.
• Timeouts — compare time(NULL) to a deadline.
• Benchmarks — clock() around hot loops.
• Random seeds — srand((unsigned)time(NULL)) in <stdlib.h> demos.
• Age / duration — difftime between two dates as time_t.

📝 Notes

• time_t overflow (Year 2038 on 32-bit) is a known issue—modern 64-bit time_t helps.
• localtime/gmtime return static pointers—copy struct tm if needed.
• tm_year is since 1900; tm_mon is 0–11 (January = 0).
• time() resolution is often 1 second—not for high-precision timers.
• clock() measures process CPU time, not wall time or sleep duration.
• Daylight saving and timezones are OS-defined—test edge cases in production apps.

⚡ Optimization

Avoid calling time() or strftime inside tight inner loops. Cache formatted timestamps per second for logs. For micro-benchmarks, clock() or platform-specific high-resolution timers beat difftime. Store events as time_t or UTC epoch in databases; convert to local only for display.

💡 Best Practices