Time Management: Time Scales, Corrections, and Reading

Connection timeouts, credential expiration after lid closure, and cross-machine log ordering do not require a single timeline.

Time management answers different questions: what date an event occurred, how much actual time elapsed, whether system sleep counts toward timeouts, and whether timestamps from two machines can be compared. Clock selection should first address these semantic questions, and then consider reading costs.

1. Selecting Clocks by Semantics

The monotonicity of MONOTONIC usually allows adjacent reads to be equal; it does not guarantee a strict increase with every read. It is not "immune to NTP adjustments," nor does it imply that counters are free from frequency errors indefinitely. RAW is also not a UTC scale comparable across machines, nor can it unconditionally be called the most precise business clock. See clock_gettime for API semantics.

Two Deadline Examples

A connection establishment timeout of up to 5 seconds typically requires a MONOTONIC deadline to avoid waiting an extra minute if an administrator rolls back the calendar clock. If authentication credentials should expire based on elapsed time even after the laptop lid is closed, the design should combine BOOTTIME or correctly synchronized absolute deadlines.

Saving a MONOTONIC value to disk and continuing to compare it after a reboot is usually meaningless. Subtracting a MONOTONIC value from Machine A from that of Machine B does not yield network latency. Distributed logs require calendar time, error assessment, and causal identifiers for joint interpretation.

Advance awake time first, then cross a suspend or wall-clock jump. Below, we separate "the clock has passed the deadline" from "the callback has been executed" to avoid misinterpreting expiration as immediate execution.

2. How Timekeeping Converts Counts to Time

The core maintains the most recently updated count and base time, calculating the elapsed amount after reading a new count. A simplified integer conversion is:

delta_ns ≈ ((cycles_now - cycles_last) & mask) × mult >> shift

The mask handles finite-width counter wraparound, while mult/shift reduce expensive calculations. However, real implementations must also avoid intermediate overflows, handle different bases and corrections, and cannot treat the formula as complete driver code. The maintained frequency must be sufficient to distinguish wraparounds and cannot remain unupdated indefinitely.

Reading time does not require waiting for the next tick: it can deduce how much time has passed since the base using the current count difference. The actual structure of the timekeeper varies by version, and maintaining its update path is not equivalent to "all hrtimer interrupts completely recalculating all clocks." See timekeeping for underlying responsibilities.

Why Consistent Snapshots Are Needed

Fields such as the base, mult, and shift must be interpreted together. If you read a pre-update base and post-update conversion parameters, the result may be incorrect. Therefore, the read path uses sequence validation mechanisms; if a concurrent update is detected, it retries. It is not a matter of reading the counter once and being done.

3. NTP: Time Servers, User-Space Control, and Kernel Corrections

User-space services like chronyd/ntpd handle network time sources and estimation, while the kernel performs corresponding frequency and phase adjustments via interfaces such as adjtimex/clock_adjtime. The kernel's ntp.c is not an independent, network-connected "NTP daemon."

The long-term difference between RAW and MONOTONIC can provide clues about corrections, but measurement noise and clock selection must still be considered.

The units of struct timex fields depend on flags/mode; for example, frequency uses specified scaling units, and the microsecond/nanosecond semantics of offset depend on the state. Do not annotate all adjtimex fields as plain nanoseconds and ppm. See adjtimex.

Synchronization Status and Error Ranges Must Be Read Together

A sync service reporting synchronization does not mean two machines have identical times. Network path asymmetry, clock drift, sampling, and hardware all introduce errors. When making cross-machine judgments for intervals below a millisecond, error ranges must be included in the conclusion.

4. TAI, UTC, and Leap Seconds

The offset between TAI and UTC is determined by historical leap seconds and should not be written as a permanent constant in long-term knowledge articles. Linux CLOCK_TAI also relies on the system having the correct offset configured; if the offset is not configured or is incorrect, a successful call does not guarantee a trustworthy TAI return.

The TAI time scale does not have the same discontinuous handling as UTC leap second insertions, but kernel time corrections and configuration changes can still affect actual observations. Time services using leap smear will intentionally deviate from strict UTC within the window; machines mixing different smear strategies cannot assume timestamps are directly consistent.

Protocols should explicitly define the time scale, units, and leap second/correction strategies; passing a single integer named timestamp is insufficient.

5. PTP, PHC, and Hardware Timestamps

PHC is the PTP Hardware Clock on the device; Linux provides access via /dev/ptpN. Network cards timestamp closer to the transmit/receive hardware, reducing uncertainty caused by software queuing; the PTP protocol and user-space services then use these measurements to synchronize corresponding clocks.

The network card PHC and system REALTIME are different clock objects; installing ptp4l does not guarantee they will automatically become fully consistent. Tools like phc2sys are responsible for synchronizing between corresponding clocks, and configurations must specify which is the reference and which is adjusted.

The software, conversion, and raw hardware timestamp fields and flags of SO_TIMESTAMPING must be interpreted according to the interface. Nanosecond storage units do not guarantee nanosecond synchronization accuracy; actual performance is also affected by the network card, switch, link, configuration, and temperature. See PTP clock and Network Timestamping.

6. vDSO is a Fast Read Path, Not a New Time Scale

The kernel maps the vDSO ELF to user processes, allowing libc to call clock functions within it. Coupled with kernel-published data pages and count sources readable in user space, common clock queries can avoid kernel traps every time.

This still relies on time parameters and consistency protocols maintained by the kernel. If the target architecture, clocksource, or clock ID is not supported by the fast path, it may fall back to a syscall. Not seeing a clock_gettime syscall in strace does not mean the program is not reading time.

Syscall entry into the kernel involves privilege level transitions and does not necessarily cause a task context switch. Reading costs must be measured; one cannot fixate on promises of 20 ns for vDSO and 100 ns for syscalls. The x86 path should not be pseudonymously written as calling ARM's __arch_counter_get_cntvct(). See vDSO.

7. Hardware Capabilities Do Not Equal Final Time Quality

TSC, HPET, ACPI PM timer, ARM Generic Timer, and virtualization paravirtual clocks have different access, frequency, and stability attributes. TSC's invariant capabilities help stabilize timing, but cross-CPU synchronization, firmware, virtualization, and migration still require kernel judgment; one cannot directly use the inverse of CPU frequency as a measure of accuracy.

The clocksource watchdog and kernel validation can detect unreliable sources and switch. Forcing a choice of a "theoretically faster" source may reduce reliability; read-only observation is the first step to understanding the current configuration.

from pathlib import Path
import time

root = Path('/sys/devices/system/clocksource/clocksource0')
for field in ('current_clocksource', 'available_clocksource'):
    try:
        print(field, (root / field).read_text().strip())
    except OSError as exc:
        print(field, type(exc).__name__)

names = ('CLOCK_REALTIME', 'CLOCK_MONOTONIC', 'CLOCK_MONOTONIC_RAW',
         'CLOCK_BOOTTIME', 'CLOCK_TAI')
for name in names:
    if not hasattr(time, name):
        continue
    clock = getattr(time, name)
    try:
        print(name, 'ns=', time.clock_gettime_ns(clock),
              'resolution_s=', time.clock_getres(clock))
    except OSError as exc:
        print(name, type(exc).__name__)

start = time.clock_gettime_ns(time.CLOCK_MONOTONIC)
time.sleep(0.02)
elapsed = time.clock_gettime_ns(time.CLOCK_MONOTONIC) - start
assert elapsed >= 20_000_000
print('observed sleep elapsed_ns=', elapsed)

These clocks are read sequentially; one cannot directly treat the difference between adjacent printed values as a precise offset. The example also does not modify clocks or trigger suspend. clock_getres() provides resolution information but does not prove current UTC error or actual wakeup jitter.

8. Order of Checks for Time Measurement

First, confirm that you are comparing the same time scale and the same machine/boot cycle; then confirm whether suspend, correction, and virtualization pauses should be counted. When periodic execution is required, check absolute/relative deadlines and catch-up rules; when cross-machine comparison is needed, confirm synchronization errors; finally, analyze vDSO and hardware reading overhead.

Related Reading: Clocks and Timers, Synchronization Mechanisms.