# Linux - System Time Library Usage Manual

> This manual explains how to use the system clock native Linux libraries. [name=Ender Yang][time=Monday, December 22, 2025]

[ToC]

## Basics of System Time

- Most computer systems use the Unix Timestamp, which counts the number of seconds elapsed since 00:00:00 UTC on January 1, 1970, known as the *Unix Epoch*.
- The Unix Timestamp is typically stored as a 32-bit signed integer, with a maximum value of 2,147,483,647 (corresponding to 03:14:07 UTC on January 19, 2038). After this point, the value overflows and becomes negative (-2,147,483,648, corresponding to December 13, 1901), leading to the *Year 2038 problem* (Y2K38).

## How to Use

This manual introduces four essential functions from the native Linux library for working with system time:

- [`gettimeofday()`](#gettimeofday-Usage): Retrieves the current system time with microsecond precision. It fills [`struct timeval`](#struct-timeval-structure) structure with the number of seconds and microseconds since the Unix Epoch.
- [`settimeofday()`](#settimeofday-Usage): Sets the system time and date using [`struct timeval`](#struct-timeval-structure) structures value. This function usually requires superuser privileges.
- [`localtime()`](#localtime-Usage): Converts Unix Timestamp (seconds since the Unix Epoch) to human-readable local time, represented as [`struct tm`](#struct-tm-structure) structure.
- [`mktime()`](#mktime-Usage): Converts [`struct tm`](#struct-tm-structure) structure representing local time back into Unix Timestamp.

## Structures

- This section describes the key data structures used for handling system time in Linux.
- These structures are fundamental for manipulating and representing time in C programs on Linux systems.

### `struct tm` structure

The `struct tm` structure breaks down a calendar date and time into its components:

| Member | Type | Description | Range |
|----------|------|-----------------------------|--------|
| tm_sec | int | Seconds after the minute | 0–61* |
| tm_min | int | Minutes after the hour | 0–59 |
| tm_hour | int | Hours since midnight | 0–23 |
| tm_mday | int | Day of the month | 1–31 |
| tm_mon | int | Months since January | 0–11 |
| tm_year | int | Years since 1900 | |
| tm_wday | int | Days since Sunday | 0–6 |
| tm_yday | int | Days since January 1 | 0–365 |
| tm_isdst | int | Daylight Saving Time flag | |

\* The range for `tm_sec` can be up to 60 or 61 to account for leap seconds.

### `struct timeval` structure

The `struct timeval` structure represents time with microsecond precision:

| Member | Type | Description |
|----------|-------------|-------------------------------------------|
| tv_sec | time_t | Seconds since the Unix Epoch |
| tv_usec | suseconds_t | Microseconds past the value in `tv_sec` |

---

## System Time Functions

### `gettimeofday()` Usage

Retrieves the current time.

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

int main() {
    struct timeval tv;

    gettimeofday(&tv, NULL); // Get seconds since Unix Epoch
    
    printf("Unix Time: %ld (Microseconds: %ld)\n", (long)tv.tv_sec, tv.tv_usec);
    return 0;
}

Output example:

Unix Time: 1745203454 (Microseconds: 123456)

### `settimeofday()` Usage

Sets the system time. Requires root privileges.

#include <sys/time.h>
#include <stdio.h>
#include <errno.h>

int main() {
    struct timeval tv;

    tv.tv_sec = 1745203454; // Example: set to a specific Unix timestamp
    tv.tv_usec = 0;         // Reset microseconds (Optional)

    if (settimeofday(&tv, NULL) == 0) {
        printf("System time updated successfully.\n");
    } else {
        perror("settimeofday");
        return 1;
    }
    return 0;
}

Output example:

System time updated successfully.

If failed to set system time:

settimeofday: Operation not permitted

### `localtime()` Usage

Converts a Unix Timestamp to local time.

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

int main() {
    struct timeval tv;
    struct tm *t;

    tv.tv_sec = 1745203454;    // Example: set to a specific Unix timestamp
    t = localtime(&tv.tv_sec); // Converts Unix Timestamp to local time with `struct tm` structure

    printf("Local Time: %04d/%02d/%02d %02d:%02d:%02d (Unix Time: %ld)\n",
        t->tm_year + 1900, t->tm_mon + 1, t->tm_mday, t->tm_hour,
        t->tm_min, t->tm_sec, (long)tv.tv_sec);
    return 0;
}

Output example:

Local Time: 2025/4/21 02:44:14 (Unix Time: 1745203454)

### `mktime()` Usage

Converts a `struct tm` to a Unix Timestamp.

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

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

    // Fill the `struct tm` structure with the desired date and time to convert.
    t.tm_year = 2025 - 1900; // Example: set to specific year (years since 1900)
    t.tm_mon = 4 - 1;        // April (months since January, 0–11)
    t.tm_mday = 21;          // Month of the day
    t.tm_hour = 2;          // Hour
    t.tm_min = 44;            // Minute
    t.tm_sec = 14;            // Second

    time_t ts = mktime(&t);  // Convert `struct tm` structure to Unix Timestamp

    printf("Unix Timestamp: %ld\n", ts);
    return 0;
}

Output example:

Unix Timestamp: 1745203454