22.24 The zsh/sched Module

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

sched [-o] [+]hh:mm[:ss] command ...
sched [-o] [+]seconds command ...
sched [ -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 The zsh/datetime Module.

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 ‘-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 widget’ to access the editor via the named 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’.

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 The zsh/datetime Module 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.