time-print-tai64n 1 user commands nosh
time-print-tai64n print external TAI64N timestamps
`time-print-tai64n` -n timestamp

## Description

`time-print-tai64n` parses timestamp to yield a TAI64N time. It prints the result as a `@` character prefix, a TAI64N timestamp in external form (16 hexadecimal digits of seconds and 8 hexadecimal digits of nanoseconds), a space, and (if the -n command-line option is not used) a newline.

## Timestamps

The format of timestamp is a rough superset of the timestamp format from Paul Jarc's runwhen 1 program, omtting all of the relative offset forms (which have no applicability):

`@hexdigits`

  hexdigits is a 16-character TAI64 or a 24-character TAI64N timestamp in their external forms. For the former, the nanoseconds count is understood to be zero. The output of the `time-print-tai64n` command may contain trailing whitespace; this must not, however.

`iiso8601`

  iso8601 is date, time, and timezone in ISO 8601 form. As extensions to the standard form, a space can be substituted for the `T` character between the date and time, and a space character can be placed between the time and the timezone. The timezone, per the standard, is always in the offset from UTC numeric form and is not optional.

`Ddate`

  date is a date that is either in the ISO 8601 form, or in the current locale's form (i.e. as understood by the strptime 3 library function with the `%x` format specifier). The time is taken to be 00:00:00, local time, on that day.

`Ttime`

  time is a time that is either in the ISO 8601 form, or in the current locale's form (i.e. as understood by the strptime 3 library function with the `%X` format specifier). The date is taken to be today, and the time to be local time.

`$var`

  var is the name of an environment variable, whose value is looked up and processed as a timestamp. If the environment variable does not exist, the resultant timestamp is null.

  It is possible to create loops where each environment variable's value is a `$var` timestamp referencing the next environment variable in the loop. This is an error.

`<filename`

  The last access timestamp of the file `filename`.

`>filename`

  The last modification timestamp of the file `filename`.

`0filename`

  The creation timestamp of the file `filename`.

`now`

  The current time from the `CLOCK_REALTIME` clock read using the clock_gettime 3 library function.

`today`

  The current time from the `CLOCK_REALTIME` clock read using the clock_gettime 3 library function, forced to the contemporary or immediately preceding 00:00:00 local time.

`zero`

  The TAI64 zero point, a long way in the past.

`null`

  A null timestamp.

`boot`
`startup`

  The time that the current invocation of the operating system was bootstrapped.

  `boot` should be preferred over `startup` when using this command. `startup` is provided for convert-systemd-units 1 to convert systemd unit files. It does not provide any special semantics, merely a visual clue to what the source unit setting being converted was.
  This value is not constant over the runtime of the system, counterintuitively. FreeBSD and NetBSD calculate this time on the fly in the kernel by subtracting the accumulated uptime from from the current time, in order to avoid problems when there is no hardware clock during the bootstrap. (Linux does not even have a saved boot time kept by the kernel, and this same calculation is thus done explicitly in applications code; taking the value of the `CLOCK_REALTIME` clock less the value of the `CLOCK_BOOTTIME` clock, both read using the clock_gettime 3 library function.) Every time that the system clock is changed, the bootstrap time will thus change along with it.
`monotonic`

  The value of the `CLOCK_MONOTONIC` clock, read using the clock_gettime 3 library function. Operating systems do not specify when this clock ticks from.

`uptime`

  The value of the `CLOCK_UPTIME` (a.k.a. `CLOCK_BOOTTIME`) clock, read using the clock_gettime 3 library function. Operating systems do not specify when this clock ticks from. (Ridiculously, applications code has to invert the kernel's calculation of `boot` on NetBSD.)

`time-print-tai64n` attempts to generate correct TAI64N times when reading the real-time clock. On a Linux system where it detects an Olson "right" timezone currently in use, it knows that the real-time clock is TAI seconds since the Epoch and performs a simple conversion. On other Linux systems, and on BSDs, it assumes that the real-time clock is UTC seconds since the Epoch and attempts to correct for (known) UTC leap seconds in order to determine TAI.

## Author

Jonathan de Boyne Pollard