22.10 The zsh/datetime Module

The zsh/datetime module makes available one builtin command:

strftime [ -s scalar | -n ] format [ epochtime [ nanoseconds ] ]
strftime -r [ -q ] [ -s scalar | -n ] format timestring

Output the date in the format specified. With no epochtime, the current system date/time is used; optionally, epochtime may be used to specify the number of seconds since the epoch, and nanoseconds may additionally be used to specify the number of nanoseconds past the second (otherwise that number is assumed to be 0). See strftime(3) for details. The zsh extensions described in Prompt Expansion are also available.

-n

Suppress printing a newline after the formatted string.

-q

Run quietly; suppress printing of all error messages described below. Errors for invalid epochtime values are always printed.

-r

With the option -r (reverse), use format to parse the input string timestring and output the number of seconds since the epoch at which the time occurred. The parsing is implemented by the system function strptime; see strptime(3). This means that zsh format extensions are not available, but for reverse lookup they are not required.

In most implementations of strftime any timezone in the timestring is ignored and the local timezone declared by the TZ environment variable is used; other parameters are set to zero if not present.

If timestring does not match format the command returns status 1 and prints an error message. If timestring matches format but not all characters in timestring were used, the conversion succeeds but also prints an error message.

If either of the system functions strptime or mktime is not available, status 2 is returned and an error message is printed.

-s scalar

Assign the date string (or epoch time in seconds if -r is given) to scalar instead of printing it.

Note that depending on the system’s declared integral time type, strftime may produce incorrect results for epoch times greater than 2147483647 which corresponds to 2038-01-19 03:14:07 +0000.

The zsh/datetime module makes available several parameters; all are readonly:

EPOCHREALTIME

A floating point value representing the number of seconds since the epoch. The notional accuracy is to nanoseconds if the clock_gettime call is available and to microseconds otherwise, but in practice the range of double precision floating point and shell scheduling latencies may be significant effects.

EPOCHSECONDS

An integer value representing the number of seconds since the epoch.

epochtime

An array value containing the number of seconds since the epoch in the first element and the remainder of the time since the epoch in nanoseconds in the second element. To ensure the two elements are consistent the array should be copied or otherwise referenced as a single substitution before the values are used. The following idiom may be used:

for secs nsecs in $epochtime; do
  ...
done