.. zsh-module-meta::
   :name: zsh/sched
   :summary: A builtin that provides a timed execution facility within the shell.

The ``zsh/sched`` module makes available one builtin command and one
parameter.

.. index:: single: sched; Function

.. index:: single: timed execution; Command

.. index:: single: execution, timed; Command

``sched`` [``-o``] [``+``]:var:`hh`\ ``:``:var:`mm`\[``:``:var:`ss`] :var:`command` ...

``sched`` [``-o``] [``+``]:var:`seconds` :var:`command` ...

``sched`` [ ``-``:var:`item` ]
    
    Make an entry in the scheduled list of commands to execute.
    The time may be specified in either absolute or relative time,
    and either as hours, minutes and (optionally) seconds separated by a
    colon, or seconds alone.
    An absolute number of seconds indicates the time since the epoch
    (1970/01/01 00:00); this is useful in combination with the features in
    the ``zsh/datetime`` module, see
    :zshsectref:`The zsh/datetime Module <zshmodules>`.
    
    With no arguments, prints the list of scheduled commands.  If the
    scheduled command has the ``-o`` flag set, this is shown at the
    start of the command.
    
    With the argument ``-``:var:`item`, removes the given item
    from the list.  The numbering of the list is continuous and entries are
    in time order, so the numbering can change when entries are added or
    deleted.
    
    Commands are executed either immediately before a prompt, or while
    the shell's line editor is waiting for input.  In the latter case
    it is useful to be able to produce output that does not interfere
    with the line being edited.  Providing the option ``-o`` causes
    the shell to clear the command line before the event and redraw it
    afterwards.  This should be used with any scheduled event that produces
    visible output to the terminal; it is not needed, for example, with
    output that updates a terminal emulator's title bar.
    
    To effect changes to the editor buffer when an event executes, use the
    ``zle`` command with no arguments to test whether the editor is active,
    and if it is, then use ``zle`` :var:`widget` to access the editor via
    the named :var:`widget`.
    
    The ``sched`` builtin is not made available by default when the shell
    starts in a mode emulating another shell.  It can be made available
    with the command ``zmodload -F zsh/sched b:sched``.
    

.. index:: single: zsh_scheduled_events; Variable

``zsh_scheduled_events``
    
    A readonly array corresponding to the events scheduled by the
    ``sched`` builtin.  The indices of the array correspond to the numbers
    shown when ``sched`` is run with no arguments (provided that the
    ``KSH_ARRAYS`` option is not set).  The value of the array
    consists of the scheduled time in seconds since the epoch
    (see :zshsectref:`The zsh/datetime Module <zshmodules>` for facilities for
    using this number), followed by a colon, followed by any options
    (which may be empty but will be preceded by a ``-`` otherwise),
    followed by a colon, followed by the command to be executed.
    
    The ``sched`` builtin should be used for manipulating the events.  Note
    that this will have an immediate effect on the contents of the array,
    so that indices may become invalid.
    

