C Mastery / time.h: Calendar and Processor Time
Part 3 — The Standard Library

time.h: Calendar and Processor Time

This chapter covers <time.h>: calendar time, processor time, and the functions and types for measuring and formatting time.

Why This Matters

Time is fundamental to logging, benchmarking, scheduling, and protocol engineering. <time.h> provides the standard, portable interface, though its resolution and epoch details are implementation-defined.

Prerequisites

Core Concept

Types and functions

typedef ... time_t;        /* arithmetic type for calendar time */
typedef ... clock_t;       /* arithmetic type for processor time */
struct tm { ... };         /* broken-down time */

time_t time(time_t *t);
clock_t clock(void);
double difftime(time_t a, time_t b);
struct tm *gmtime(const time_t *t);
struct tm *localtime(const time_t *t);
time_t mktime(struct tm *tm);
size_t strftime(char *s, size_t n, const char *fmt, const struct tm *tm);

time() returns the current calendar time (typically seconds since the Unix epoch, but the epoch is implementation-defined). clock() returns processor time used, for measuring CPU time (not wall time).

Syntax

#include <time.h>

time_t now = time(NULL);
struct tm *utc = gmtime(&now);
char buf[64];
strftime(buf, sizeof buf, "%Y-%m-%d %H:%M:%S", utc);

Examples

Current time

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

int main(void)
{
    time_t now = time(NULL);
    struct tm *local = localtime(&now);
    char buf[64];
    strftime(buf, sizeof buf, "%Y-%m-%d %H:%M:%S", local);
    printf("%s\n", buf);
    return 0;
}

Expected output is the current date/time.

Measuring elapsed wall time

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

int main(void)
{
    time_t start = time(NULL);
    /* ... work ... */
    time_t end = time(NULL);
    printf("elapsed: %.0f seconds\n", difftime(end, start));
    return 0;
}

Measuring processor time

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

int main(void)
{
    clock_t start = clock();
    /* ... CPU-bound work ... */
    clock_t end = clock();
    printf("CPU seconds: %f\n", (double)(end - start) / CLOCKS_PER_SEC);
    return 0;
}

How It Works

time_t stores calendar time; clock_t stores processor time in implementation-defined units (convert with CLOCKS_PER_SEC). gmtime/ localtime convert a time_t into broken-down fields, and strftime formats them.

Variations

time_t epoch

The epoch is implementation-defined, but on POSIX and most systems it is 00:00:00 UTC, 1 Jan 1970. Do not assume this in strictly portable code.

Reentrancy

gmtime/localtime may return a pointer to static storage and are not thread-safe; POSIX provides gmtime_r/localtime_r.

Common Mistakes

Undefined Behavior

the result is truncated/unspecified.

Portability

Under the Hood

time() and clock() are typically thin wrappers over OS/kernel time services. localtime applies the process's timezone and DST rules. strftime is a formatting loop.

Practical Usage

like clock_gettime on POSIX, c.perf.1).

Exercises

1. Print the current UTC and local time using gmtime/localtime and strftime. 2. Measure elapsed wall time and CPU time for a loop. 3. Write a function that formats a time_t as an ISO 8601 string. 4. Explain the difference between time() and clock().

Deep Challenge

Implement a small ISO 8601 timestamp formatter that is independent of localtime's static-storage limitation (thread-safe), using gmtime carefully or mktime for validation. Discuss the portability of the epoch assumption.

References

Verification

verified.`

Progress

Concept checkboxes

Mastery levels

ConceptCurrent level (0–8)Target level
c.lib.time05
← PrevNext →