crontab - Schedule regular background jobs

Format

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

Description

crontab creates or changes your crontab entry. The crontab is a system facility that automatically runs a set of commands for you on a regular schedule. For example, you might set up your crontab entry so it runs a job every night at midnight, or once a week during low-use hours. This job could perform regular maintenance chores, for example, backing up files or getting rid of unnecessary work files.

To set up a crontab entry, use: 
crontab file
If you omit the file argument, crontab takes input from standard input. In this mode, you must provide your entire crontab file. This replaces any other existing crontab entries. If you issue crontab with no options, do not enter the end-of-file character or you will end up with an empty crontab file. Press INTERRUPT instead.
Input consists of six fields, which are separated by blanks. All blank lines and any input that contains a # as the first non-blank character are ignored. The first five give a date and time in the following form:
  • A minute, expressed as a number from 0 through 59.
  • An hour, expressed as a number from 0 through 23.
  • A day of the month, expressed as a number from 1 through 31.
  • A month of the year, expressed as a number from 1 through 12.
  • A day of the week, expressed as a number from 0 through 6 (with 0 standing for Sunday).
Requirement: Always use a system default time zone. Your system administrator can tell you what it is. The cron daemon does not use the value of the TZ environment variable when crontab is invoked.
Any of these fields may contain an asterisk (*) standing for all possible values. For example, if you have an * as the day of the month, the job runs every day of the month. A field can also contain a set of numbers separated by commas, or a range of numbers, with the first number followed by a minus sign - followed by the second number. If you give specific days for both day of the month and day of the week, the two are ORed together. Here are some examples: 
     0 0 * * *          -- Midnight every day
     0 0 * * 1-5        -- Midnight every weekday
     0 0 1,15 * *       -- Midnight on 1st and 15th of month
     0 0 1 * 5          -- Midnight on 1st of month and every Friday

The sixth field of a crontab entry is a string that your shell executes at the specified time. When the shell executes this string, it sets the HOME, LOGNAME, PATH, and SHELL environment variables to default values for you.

If the string in your crontab entry contains percent characters %, the shell interprets them as newline characters, splitting your string in several logical lines. The first logical line (up to the first %) is interpreted as the command you want to execute; subsequent logical lines are used as standard input to the command. If any real (not logical) line in the file is blank or begins with #, the shell ignores the line (treats it as a comment).

To obtain the output of the command in your crontab entry, redirect the standard output and the standard error into a file. If you do not do this, the system mails you the output from the command.

at, batch, and crontab submit jobs to cron; the data for those jobs may contain double-byte characters. When the jobs are run, the data in the jobs is interpreted in the locale that cron is using. Because it is strongly recommended that cron be started in the POSIX locale, double-byte characters in the jobs may not be interpreted correctly. You can get around this by calling setlocale() in the job itself.

Options

-e
Lets you edit your crontab entry. crontab invokes an editor to edit the entry. if you have an EDITOR environment variable defined, crontab assumes that the variable's value is the name of the editor you want to use. if you do not have the EDITOR environment variable defined, crontab uses vi.

if you do not have a crontab entry, crontab sets up a blank entry for you. when you exit from the editor, crontab uses the edited entry as your new entry.

-l
Displays your current crontab entry on standard output.
-r
Removes (deletes) your current crontab entry.
-u user
Uses the crontab entry of user. the user specified has to be the same username that the crontab entry was created under in /usr/spool/cron/crontabs. this requires the appropriate privileges.

You can specify only one of the -e, -l, or -r options.

Environment variables

crontab uses the following environment variables:
EDITOR
Specifies the editor that the -e option invokes. The default editor is vi.
HOME
Is set to your user ID's home directory (not necessarily the current value of HOME when the commands in your crontab entry are run.
LOGNAME
Is set to your user ID when the commands in your crontab entry are run.
PATH
Is set to a system-wide default value when the commands in your crontab entry are run.
TZ
Is not used in time calculations. The cron daemon does, however, use this variable when cron is first started, typically when the system is started.

Localization

crontab uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_CTYPE
  • LC_MESSAGES
  • NLSPATH

Exit values

0
Successful completion.
1
Returned if the command fails for any reason. In this case, crontab does not change your crontab entry.

Portability

POSIX.2 User Portability Extension, X/Open Portability Guide, UNIX systems.

The -u option is an extension to the POSIX standard.

Related information

at, batch, bg, cron

The queuedef file format description in File formats.