crontab(C)

crontab -- schedule commands to be executed at regular intervals

Syntax

crontab [ file ]

crontab [ -e | -l | -r ]

crontab -u user [ -e | -l | -r ]

Description

The crontab command can be used to schedule commands to be executed at regular intervals. These commands are stored in the user's crontab file, /usr/spool/cron/crontabs/username. Any output or errors generated by the commands are mailed to the user.

If called with no options, crontab copies the specified file, or standard input if no file is specified, into the crontabs directory. If the user has a previous crontab file, this is replaced.

crontab understands the following options:

-e: Permit the contents of the user's crontab file to be edited with the editor specified by the EDITOR environment variable. The default editor is vi(C). A copy of the crontab file is edited and checked for validity before it replaces the installed crontab file.
-l: List the contents of the user's crontab file.
-r: Remove the user's crontab file from the crontabs directory.
-u: Allow crontab to manipulate a different crontab file from invoking users. If crontab is used from an su(C) session then crontab by default will manipulate the crontab file of the su'ed user. The -u option may be used to direct crontab to manipulate the original login user's crontab file instead. root can also use the -u option to manipulate any user's crontab file.

If the file /usr/lib/cron/cron.allow exists, only the users listed in that file are allowed to use crontab. If cron.allow does not exist, and the file /usr/lib/cron/cron.deny does, then all users not listed in cron.deny are allowed access to crontab. An empty cron.deny allows global usage. If neither file exists, only root is allowed to submit a job. The allow/deny files consist of one user name per line.

The crontabs files consist of lines of six fields each. The fields are separated by spaces or tabs. The first five are integer patterns that specify the minute (0-59), hour (0-23), day of the month (1-31), month of the year (1-12), and day of the week (0-6, with 0=Sunday). Each of these patterns may contain:

a number in the (respective) range indicated above
two numbers separated by a minus (indicating an inclusive range)
a list of numbers separated by commas (meaning all of these numbers)
an asterisk (meaning all legal values)

Note that the specification of days may be made by two fields (day of the month and day of the week). If both are specified as a list of elements, both are adhered to. For example, 0 0 1,15

1 would run a command on the first and fifteenth of each month, as well as on every Monday. To specify days by only one field, the other field should be set to ``

'' (for example, 0 0

1 would run a command only on Mondays).

The sixth field is a string that is executed by the shell at the specified time (using time(S) format). A ``%'' in this field is translated into a newline character. Only the first line (up to a ``%'' or end-of-line) of the command field is executed by the shell. The other lines are made available to the command as standard input.

The shell is invoked from your $HOME directory with an arg0 of sh. cron supplies a default environment for every shell, defining HOME, LOGNAME, SHELL (=/bin/sh), and PATH(=/bin:/usr/bin:).

To specify a different environment, the command specified in the crontab entry should be an executable shell script which sets the environment explicitly.

Exit values

If no error occurs, crontab exits with a value of 0. If it exits for any other reason, it returns a value of 1.

If the specified user does not exist, crontab returns a value of 1 and an error message.

Examples

An example crontabs file follows:

0        4  *  *  *  calendar -
15       4  *  *  *  find /usr/preserve -mtime +7 -exec rm -f {} \;
30       4  1  *  1  /usr/lib/uucp/uuclean
40       4  *  *  *  find / -name '#*' -atime +3 -exec rm -f {} \;
1,21,41  *  *  *  *  (echo -n ' '; date; echo ) >/dev/console

The lines in this example do the following: run the calendar program every night at 4:00 am, clear old files from the /etc/preserve directory every night at 4:15 am, clean up the uucp spool directory every Monday and the first of every month at 4:30 am, find and remove any old files with names beginning with ``#'' every night at 4:40 am, and echo the current date and time to the console three times an hour at one minute, 21 minutes, and 41 minutes past the hour.

Limitations

crontab commands are executed by cron(C). cron reads the files in the crontabs directory only on startup or when a new crontab is submitted with the crontab command, so changes made to these files by hand will not take effect until the system is rebooted. Changes submitted with the crontab command will take effect as soon as cron is free to read them (that is, when cron is not in the process of running a scheduled job or reading another newly submitted at(C) or crontab job).

Remember to redirect the standard output and standard error of commands, otherwise any generated output or errors will be mailed to you. In this example, the standard output of the who(C) is appended to the file /tmp/whofile. Output on the standard error is discarded by redirecting it to /dev/null.

   0  *  *  *  *  who >> /tmp/whofile 2> /dev/null

For more details on output redirection, see the sh(C) manual page.

crontab will overwrite any previous crontab submitted by the same user.

Care should be taken when scheduling commands to run during time zone changes from the standard time to the daylight savings time. This is because when the clocks go forward, certain times cease to exist. For example, when the clocks go forward an hour at 2 am, all times between 2 am and 3 am (including 2 am) cease to exist. If commands are scheduled to run in this time period, then cron will still execute them at their scheduled time in the standard time zone, which will be later than expected in the local time zone. cron will warn the user of this by mail and give the exact local time that the command will be executed. It is then the user's responsibility to reschedule the job if required.

Authorizations

The behavior of this command depends on the ``cron'' authorization in authorize(F). See subsystem(M) for details.

Files

/usr/lib/cron: main cron directory
/usr/spool/cron/crontabs: crontab directory
/usr/lib/cron/cron.allow: list of allowed users
/usr/lib/cron/cron.deny: list of denied users
/usr/lib/cron/queuedefs: cron data file

Standards conformance

crontab is conformant with:

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.