---
# System prepended metadata

title: Linux - System Time Library Usage Manual

---

# 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.

```c
#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:

```log
Unix Time: 1745203454 (Microseconds: 123456)
```

### `settimeofday()` Usage

Sets the system time. Requires root privileges.

```c
#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:

```log
System time updated successfully.
```

If failed to set system time:

```log
settimeofday: Operation not permitted
```

### `localtime()` Usage

Converts a Unix Timestamp to local time.

```c
#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:

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

### `mktime()` Usage

Converts a `struct tm` to a Unix Timestamp.

```c
#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:

```log
Unix Timestamp: 1745203454
```
