TimeSpec

Timespec is a data type used in POSIX and C libraries to represent a time value with second and nanosecond precision. It is defined as a small structure containing two fields: tv_sec, which is a time_t specifying seconds since the Unix epoch (00:00:00 UTC on 1 January 1970), and tv_nsec, a long integer specifying nanoseconds within the current second (0 to 999,999,999). The exact types can vary by platform, but the concept is a two-part representation of time or duration with nanosecond precision.

Timespec is widely used with clock and timer APIs. Functions such as clock_gettime, clock_nanosleep, and nanosleep accept or return a timespec to specify either an absolute time or a duration. When performing arithmetic on timespec values (for example, adding durations or computing differences), it is common to normalize so that tv_nsec stays in the range 0 to 999,999,999, carrying any excess into tv_sec. This ensures consistent interpretation across calls and platforms.

Clocks and semantics differ for the two primary uses. For CLOCK_REALTIME, the value represents wall clock time, subject to system clock changes. For CLOCK_MONOTONIC, the value represents elapsed time relative to an unspecified starting point and is not affected by wall clock adjustments. Other clocks exist on some systems, such as per-process or per-thread CPU time clocks, but their availability and semantics are platform dependent.

Portability considerations include variability in the underlying types of tv_sec and tv_nsec and potential overflow in time_t on 32-bit systems. Modern systems commonly use 64-bit time_t, reducing the year-2038 risk, but portable code should avoid assuming specific sizes. Timespec remains a core primitive for precise time specification and interval measurement in POSIX-compliant environments. See also timeval, nanosleep, and clock_gettime.