# Timestamps

Linux and the BSDs have two basic ways of keeping time:

- In a "posix" mode the system clock counts UTC seconds since the POSIX Epoch.

- In a "right" mode the system clock counts TAI seconds since the POSIX Epoch.

Both Linux and the BSDs in theory can operate in either mode. In practice, the "right" capability, albeit available in the source, is not enabled in FreeBSD; and Linux operating systems usually operate in "posix" mode, because programs like `ntpd` demand it. (OpenBSD has a "right" capability, though; including working `time2posix()` and `posix2time()` library functions.)

The POSIX Epoch is the same instant in time in both modes, 1970-01-01 00:00:00 UTC a.k.a. 1970-01-01 00:00:10 TAI. To be strictly accurate, in the "right" mode a system clock is set 10 seconds behind TAI, conventionally denoted TAI-10, as having the POSIX Epoch as 1970-01-01 00:00:00 TAI-10 makes things slightly simpler and is how the "right" mode files for the timezone database were constructed.

The `cyclog`, `tai64n`, and `tai64nlocal` commands all deal in TAI. They have to convert TAI timestamps into system time and they have to convert the system clock into TAI timestamps. (Their timestamps are not TAI-10, but actually TAI, and adding/subtracting the 10 seconds is part of their conversion calculations.)

They do so by attempting to deduce, from the value of the `TZ` and `TZDIR` environment variables, whether the system is in "posix" or in "right" mode. From this deduction they know how to convert between the the system clock time and TAI. In "right" mode this is a simple addition or subtraction, as the system clock ticks once for every 1 TAI second that passes. In "posix" mode they have to account for the insertion of leap seconds, which count as TAI ticks but do not count as UTC ticks, and which are not inserted according to any algorithmic pattern; and thus for some system clock ticks 2 TAI seconds pass.

The programs in daemontools, daemontools-encore, and runit do not correctly calculate TAI. They assume that the system clock is always counting TAI seconds since the Epoch, even if the system is not using a "right" timezone but is running in "posix" mode. The result is that the TAI64N timestamps generated by these toolsets (when in "posix" mode) are, as of 2017, 27 seconds behind the actual TAI seconds count since the POSIX Epoch. (The requirement that one must always use a "right" timezone was stated in the original Bernstein documentation, although many people have overlooked it or not realized the significance of what the documentation said.)

The result of that is that mixing those tools with the nosh toolset will produce surprising results, if one is unaware of this difference and not using a "right" timezone. The outputs of `cyclog` and `tai64n`, if passed through such tools, will appear advanced by up to 27 seconds. Similarly, the outputs of such tools, passed through `tai64nlocal`, will appear retarded by up to 27 seconds.