.. include:: ../header.txt

.. _scheduling:

Scheduling Commands
===========================

:title:`Linux for Programmers and Users`, Section 4.7.

You may want to schedule some programs to run at later time or want them to
run on a regular, repeating schedule.  Examples of when you might want to do
this are:

* If you have a program that uses a lot of the computer's resources, you may
  want it to run at time when you will not be using the computer.

* To run system maintenance tasks, such as making backups or scanning the
  filesystem for viruses or other security concerns.

Unix has a facility for running scheduled tasks called :program:`cron`, but
users do run :program:`cron` directly.  It is always running in the background
to run scheduled commands at the appropriate times.  We call system programs,
such as :program:`cron`, that run in the backgroud *daemons*.

.. note::

    The output from any scheduled commands, is by default sent to the user in
    an e-mail message.  If this is not desired, then when scheduling the
    command, redirect the output from the command to a file or to the system
    provided trash can (:file:`/dev/null`).

    If you receive an e-mail message from the cron daemon, you might try
    using :command:`mutt`, to read the message.

The programs that users use to schedule programs are :command:`crontab`
and :command:`at`.

.. _crontab:

crontab
--------

.. index:: crontab
.. program:: crontab

SYNOPSIS

    :command:`crontab` [-u user] [file]

    :command:`crontab` [-u user] -l | -r [-i] | -e 

DESCRIPTION

    Crontab  is  the program used to install, deinstall or list the tables
    used to drive the cron daemon for running commands on a repeating
    schedule.

    The first usage is to install a schedule of commands from a file or from
    standard input.  If no options are specified, it reads from standard
    input.

    .. option:: -u user

        Specify which user's schedule to adjust (only for root). The default
        is for your own account.

    .. option:: -l

        List the currently scheduled commands

    .. option:: -r

        Remove the currently scheduled commands 

    .. option:: -i

        Prompt the user to confirm removal of the scheduled commands

    .. option:: -e 

        Edit the list of scheduled commands.  After saving the temporary file
        and exiting from the editor, the commands entered in the file are
        scheduled.  The default editor used is :command:`vi`.  If you wish to
        use another editor, such as :command:`nano`, set your :envvar:`EDITOR`
        environment variable::

            export EDITOR='nano'

---------------------------

.. centered:: :command:`crontab` file format

* Each scheduled command should be on one line of the file.  

* The file should contain 6 fields separated by spaces.  

* The first five field specify when the command should run (minute, hour,
  day, month, weekday).  A wild-card (\ **\ ***) may used to specify
  every instance. [#f1]_  A specific time value,
  a list of times or a range of times may be used for any field.  

  - The hour is in 24 hour time format (0-23).  
    
  - The valid values for weekday are 0 to 7.  Sunday is both 0
    and 7.  Monday to Saturday take the values 1 to 6.

* The last field specifies the command to run along with any arguments or 
  redirection of the output.  For some commands, it may be advisable to list
  the absolute path name of command rather than relying 

.. _at:

at
--------

.. index:: at
.. program:: at

SYNOPSIS

    :command:`at` -r job | -l | *TIME*

DESCRIPTION

    The :command:`at` command is used to schedule a command to run one time.

    .. option:: -r job

        Remove scheduled jobs, identified by their job number.
        This is the same as running ``atrm job``

    .. option:: -l

        List the scheduled jobs

    .. option:: TIME

        *TIME* is a very flexible specification of when the command should run.
        See the text book for examples.  :command:`at` then reads from standard
        input for list of commands to run at this time.  Type the EOF character
        (:kbd:`Cntrl-d`) when finished entering commands.

.. rubric:: Footnotes

.. [#f1]   Give some though to where you might want to use a wildcard
           (**\ ***) character.  A wildcard in the *day* field, means that that
           the day of the month is not important -- other criteria such
           *weekday* will determine when the program runs.  However, a wildcard
           in the *minute* field would mean that for the specified *hour*, the
           command runs once for every minute (60 times).