The zsh/datetime Module (zsh)

### 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