C time.h

Q: What is time.h in C?

time.h is a standard C header that provides types and functions for working with calendar time, broken-down time, formatted time, and processor time.

Q: What does time() return?

time() returns the current calendar time encoded as time_t when available, or the value (time_t)-1 if the calendar time is not available.

Q: What is struct tm?

struct tm is a broken-down calendar-time structure with fields for values such as seconds, minutes, hours, day, month, and year.

Q: Is clock() the same as the current wall-clock time?

No. clock() measures processor time used by the program as defined by the C implementation; it is not a function for reading the current date and time.

<time.h> provides standard C tools for working with dates, times, and processor time.

It includes types and functions for reading calendar time, breaking it into parts, formatting it, and measuring processor time.

Quick Answer

Use #include <time.h> for standard time facilities such as time_t, time(), difftime(), localtime(), gmtime(), mktime(), strftime(), and clock(). Calendar time and processor time are different concepts.

Include time.h

#include <time.h>

The header declares time-related types, structures, macros, and functions.

time_t — Calendar Time Type

time_t now;

time_t is a type used to represent calendar time.

Do not assume it must be a particular integer type or that it always means “seconds since 1970.” Its representation is implementation-defined.

time() — Read Current Calendar Time

time_t now = time(NULL);

time() obtains the current calendar time when the implementation can provide it.

If the calendar time is unavailable, it returns (time_t)-1.

difftime() — Difference Between Two Times

double seconds = difftime(end, start);

difftime() returns the difference between two calendar times in seconds as a double.

It is better than assuming that subtracting two time_t values is always meaningful.

struct tm — Broken-Down Time

struct tm stores calendar time as separate fields.

Field	Meaning
`tm_sec`	Seconds
`tm_min`	Minutes
`tm_hour`	Hours since midnight
`tm_mday`	Day of month
`tm_mon`	Months since January, so January is 0
`tm_year`	Years since 1900
`tm_wday`	Days since Sunday
`tm_yday`	Days since January 1
`tm_isdst`	Daylight-saving-time information

localtime() and gmtime()

struct tm *local = localtime(&now);
struct tm *utc = gmtime(&now);

localtime() converts calendar time to broken-down local time.

gmtime() converts it to broken-down Coordinated Universal Time (UTC).

Either function can return a null pointer if the conversion fails.

C time.h Example

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

int main(void) {
    time_t sample = (time_t)0;
    struct tm *utc = gmtime(&sample);

    if (utc == NULL) {
        return 1;
    }

    printf("Year: %d\n", utc->tm_year + 1900);
    printf("Month number: %d\n", utc->tm_mon + 1);

    return 0;
}

Output on the verified environment

Year: 1970
Month number: 1

This example uses the implementation's value (time_t)0. On the verified environment, it converts to January 1970 in UTC.

Portable C does not require every implementation to use the same epoch or representation for time_t.

strftime() — Format Date and Time

char buffer[80];

strftime(buffer, sizeof buffer,
         "%Y-%m-%d %H:%M:%S", local);

strftime() writes formatted date and time text into a character array.

Its format string uses conversion specifications such as %Y for year and %H for hour.

It returns the number of characters written, excluding the terminating null character, or 0 if the result does not fit.

mktime() — Build Calendar Time from Local Time

struct tm meeting = {0};

meeting.tm_year = 2026 - 1900;
meeting.tm_mon = 7;
meeting.tm_mday = 9;
meeting.tm_hour = 10;

time_t value = mktime(&meeting);

mktime() interprets the struct tm value as local calendar time and converts it to time_t.

It also normalizes fields that are outside their usual ranges when a representation is possible.

clock() — Processor Time

clock_t start = clock();

/* work */

clock_t end = clock();

clock() measures processor time used by the program as defined by the implementation.

It is not a function for reading the current date or wall-clock time.

Convert clock() Ticks to Seconds

double seconds =
    (double)(end - start) / CLOCKS_PER_SEC;

CLOCKS_PER_SEC is the number used to convert clock_t units to seconds.

clock() returns (clock_t)-1 if processor time is unavailable or cannot be represented.

Common time.h Mistakes

Mistake	Correct Idea
Assuming `time_t` always means Unix seconds since 1970.	Treat its representation as implementation-defined.
Using `clock()` to get the current date and time.	Use `time()` for calendar time.
Printing `tm_mon` directly as a human month number.	Add 1 because January is stored as 0.
Printing `tm_year` directly as the calendar year.	Add 1900.
Ignoring possible null returns from `localtime()` or `gmtime()`.	Check the returned pointer before dereferencing it.

Which function obtains current calendar time?
What must you add to tm_year to get the calendar year?
Is clock() for wall-clock date and time?

Practice Answers

1. Which function reads calendar time?

Use time().

2. How do you read tm_year?

Add 1900.

3. Is clock() wall-clock time?

No. It measures processor time as defined by the implementation.

Frequently Asked Questions

What is time.h in C?

time.h is a standard C header that provides types and functions for working with calendar time, broken-down time, formatted time, and processor time.

What does time() return?

time() returns the current calendar time encoded as time_t when available, or the value (time_t)-1 if the calendar time is not available.

What is struct tm?

struct tm is a broken-down calendar-time structure with fields for values such as seconds, minutes, hours, day, month, and year.

Is clock() the same as the current wall-clock time?

No. clock() measures processor time used by the program as defined by the C implementation; it is not a function for reading the current date and time.

Summary

<time.h> provides standard tools for calendar time and processor time. time() obtains calendar time, localtime() and gmtime() break it into fields, strftime() formats those fields, mktime() converts local broken-down time back to calendar time, and clock() measures processor time. Do not assume a fixed representation for time_t.