.. zsh-module-meta::
   :name: zsh/datetime
   :summary: Some date/time commands and parameters.

The ``zsh/datetime`` module makes available one builtin command:

.. index:: single: strftime; Function

.. index:: single: date string, printing; Command

``strftime`` [ ``-s`` :var:`scalar` | ``-n`` ] :var:`format` [ :var:`epochtime` [ :var:`nanoseconds` ] ] 

``strftime`` ``-r`` [ ``-q`` ] [ ``-s`` :var:`scalar` | ``-n`` ] :var:`format` :var:`timestring`
    
    Output the date in the :var:`format` specified.  With no :var:`epochtime`, the
    current system date/time is used; optionally, :var:`epochtime` may be used to
    specify the number of seconds since the epoch, and :var:`nanoseconds` may
    additionally be used to specify the number of nanoseconds past the second
    (otherwise that number is assumed to be 0).
    See :manpage:`strftime(3)` for details.  The zsh extensions described
    under ``%D{``:var:`string`\ ``}`` prompt eqcape in
    :zshsectref:`Simple Prompt Escapes <zshmisc>` 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 :var:`epochtime` values are always printed.
        
    
    ``-r``
        
        With the option ``-r`` (reverse), use :var:`format` to parse the input
        string :var:`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 :manpage:`strptime(3)`.  This means that zsh
        format extensions are not available, but for reverse lookup they are not
        required.
        
        In most implementations of ``strptime`` any timezone in the
        :var:`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 :var:`timestring` does not match :var:`format` the command returns status 1
        and prints an error message.  If :var:`timestring` matches :var:`format` but
        not all characters in :var:`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`` :var:`scalar`
        
        Assign the date string (or epoch time in seconds if ``-r`` is given) to
        :var:`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:

.. index:: single: EPOCHREALTIME; Variable

``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.
    

.. index:: single: EPOCHSECONDS; Variable

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

.. index:: single: epochtime; Variable

``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:
    
    
    .. code-block:: zsh
       :class: example

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

