POSIX definition

The POSIX.1 definition of Unix time is a number which is zero at the Unix epoch (1970-01-01T00:00:00Z), and increases by exactly 86 400 per day. Epoch and day ordinals are based on UTC.

The subtlety in this definition comes from the fact that days aren't exactly 86 400 seconds long. POSIX timestamps grow at 1Hz during the day, then end the day with small jumps to adjust for the duration of the UTC day.

For example, 2004-09-16T00:00:00Z, 12 677 days after the epoch, is represented by the Unix time number 12 677 × 86 400 = 1 095 292 800. The time interval between the epoch and 2004-09-16T00:00:00Z actually lasted 12 677 × 86 400 + 22 seconds.

This definition can be extended to represent instants before the epoch using negative numbers. 1957-10-04T00:00:00Z, 4 472 days before the epoch, is represented by the Unix time number -4 472 × 86 400 = -386 380 800. UTC is not defined for these instants, but universal time (any time standard that counts days from midnight at the reference meridian, such as the Julian Day) can be used, and the reduced accuracy is unlikely to matter.

POSIX provides for sub-second resolution with struct timespec, a fixed point format with a tv_nsec struct member for nanoseconds. This format is useful for system interfaces, but unsuitable for serialisation (naive range-checking could leave holes).

POSIX timestamps are ambiguous, discontinuous, and non-monotonic across leap seconds. When a leap second is inserted, a 1s range of Unix timestamps is repeated, first representing the leap second, then representing the first second of the next day (some implementations repeat the timestamp range immediately before the leap second instead). In the theoretical case of negative leap seconds, there would be 1s ranges of Unix time that do not represent any instant in time. The rest of the time, these Unix timestamps are continuous, unambiguous, and grow monotonically by 1s every second. The ambiguity isn't introduced by UTC, which measures time broken down in components and not as a single number.

System timestamps

On Unix systems, the CLOCK_REALTIME clock represents Unix time on a best-effort basis, based on hardware and network support. It may jump if the system clock is too far from reference time. Different clocks, representing different notions of system time, are exposed through clock_gettime. On Linux, CLOCK_MONOTONIC is monotonic and continuous (with no time elapsing when the system is suspended). It may speed up or slow down when adjtime is called, typically through NTP steering (clock slew). CLOCK_BOOTTIME is also monotonic, but will continue growing when the system is suspended. CLOCK_MONOTONIC_RAW is like CLOCK_MONOTONIC, but matches the speed of the hardware clock and ignores adjtime adjustments to clock speed. CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID count CPU time consumed by the process and thread, respectively. Linux also provides coarse variants that may provide better performance.

Timestamps recorded by the kernel (for example, modification times on filesystem inodes) follow the CLOCK_REALTIME clock.

Assuming CLOCK_REALTIME follows POSIX time, getting unambiguous time (UTC or TAI) from the kernel is an unsolved problem; adjtimex might expose enough internal state but it is highly implementation dependent. Breaking from the standard brings its own tradeoffs.

Alternative timestamps

POSIX.1b-1993 switched the definition of Unix timestamps away from a simple second count from the epoch. This introduced a few drawbacks: timestamps do not represent instants unambiguously, and Unix time is discontinuous and jumps backwards. The jumps are rare, thus hard to test for. Bugs can be subtle and are most likely to be discovered in production, after developers have moved on.

TAI-10 (TAI minus ten seconds) hits midnight at the Unix epoch. TAI is an ideal timestamp format; it grows perfectly linearly at 1/s.

Redefining CLOCK_REALTIME to follow an alternative to POSIX time is doable, but not advisable unless you control the system entirely. Setting the clock to TAI-10, applications that use localtime will still work, with /etc/localtime pointing to the Olson "right" timezones, but many applications expect to compute UTC days from timestamp / 86_400. Redefining CLOCK_REALTIME indirectly, through a tweaked NTP server, is more feasible; many applications will survive slightly varying clock speeds. This is the leap smear technique, which silently replaces UTC with UTC-SLS (smoothed leap seconds).

Other proposals aim to extend the clock_gettime interface instead of replacing the default clock. One is CLOCK_UTC, which encodes the leap second by growing tv_nsec beyond the [0, NSEC_PER_SEC] range, removing the ambiguity of CLOCK_REALTIME. The other is CLOCK_TAI, which simply encodes TAI.

time_t binary representation

ABIs where time_t is 32 bits are unable to represent times beyond January 2038; their timestamps will jump into the early twentieth century instead. This will prove a problem for some embedded systems that are being deployed now. clock_gettime/timespec_get, 64 bit integers, or other fixed-point formats like TAI64 should be used instead.

Use in protocols and serialisation

Unix timestamps are sometimes persisted, for example through serialisation or archive formats. Most filesystems use them for inode metadata. Internet protocols and formats systematically prefer RFC 3339/ISO 8601 datetimes. The SQL timestamp type is a Unix timestamp; when (fixed-offset) timezones are used, naive datetimes are translated to UTC at the storage boundary. TAI64 has been proposed to address the interoperability shortcomings of POSIX timestamps (and of time_t). When the extra compactness of integers isn't required, RFC 3339 UTC datetimes are self-describing and provide better portability, readability and widespread support.