crontab - schedule periodic background work

crontab is used to have commands, shell scripts or executable programs executed regularly at specific times.

You can use crontab to:

• schedule command jobs (Format 1)

• have scheduled jobs listed (Format 2)

• delete scheduled jobs (Format 3)

• edit scheduled jobs (Format 4)

Jobs scheduled with crontab are retained even if the user who scheduled them closes the POSIX shell with exit or if the POSIX subsystem is shut down. There is no need to reschedule the jobs.

Before the call

The user ID must have a standard account number for rlogin access. This standard account number can be assigned using the ADD-USER, MODIFY-USER-ATTRIBUTES or ADD-POSIX-USER command.

If the file /usr/lib/cron.d/cron.allow exists, you can only use crontab if your login name appears in it.

If the file /usr/lib/cron.d/cron.allow does not exist, you can only use crontab if your login name does not appear in the file /usr/lib/cron.d/cron.deny.

If neither /usr/lib/cron.d/cron.allow nor /usr/lib/cron.d/cron.deny exists, only the POSIX administrator is allowed to use crontab.

If only an empty deny file exists, for example, everyone is allowed to use crontab.

Only the POSIX administrator is allowed to create and modify the allow and deny files. Each line in these files contains precisely one login name.

Before the crontab command is called, the POSIX administrator must have started up the cron daemon (/etc/init.d/cron start).

Caution!
If you inadvertently enter the crontab command with no arguments, do not attempt to get out with CTRL+D (resp. @@d)!

This would cause all entries in your crontab file to be removed. Instead, use CTRL+C (resp. @@c) to exit.

Syntax

Format 1:	crontab[ file]
Format 2:	crontab -l[ login_name]
Format 3:	crontab -r[ login_name]
Format 4:	crontab -e[ login_name]

Scheduling command jobs

Format 1:

crontab[ file]

To schedule a command job with crontab you have to specify:

• the command (or shell script or program) that is to be executed, and

• the times at which it is to be executed (e.g. every Friday or every January 15).

When you call crontab in the above format, crontab copies these specifications into your crontab file /var/spool/cron/crontabs/login_name. The /usr/sbin/cron process checks every minute whether there are commands in the crontab file which need to be executed, and if there are any, it has them executed.

To execute the specified command, crontab invokes a new shell (sh) from your home directory. crontab supplies a default environment for every shell, defining HOME, LOGNAME, SHELL (/bin/sh), and PATH (:/bin:/usr/bin:/usr/lbin). If you wish to have your .profile executed, you must specify this explicitly in the crontab file.

If neither the standard output nor the standard error output have been redirected for the commands in the crontab file, both the standard output and the standard error output will be sent to you by mailx.

There can be at most one crontab file per login name. If the crontab file /var/spool/cron/crontabs/login_name does not exist, it is created when crontab is called. If it already exists, its contents are overwritten. In other words, if you wish to schedule additional command jobs with crontab, you should use the -e option.

file

Name of the file containing the commands and the times at which they are to be executed.
file must be in the format described below (see “Format of a crontab file”).

file not specified:
crontab reads the text entered from the standard input. The text that you enter in this case must be in the format described below (see “Format of a crontab file”).

Listing scheduled jobs

Format 2:

crontab -l[ login_name]

-l

(list)
crontab lists the contents of your crontab file /var/spool/cron/crontabs/login_name.
If the file is not available, an error message is issued.

login_name

If a login_name is specified, the crontab file of the corresponding user is listed. However, only the POSIX administrator is permitted to specify a login_name.

Deleting scheduled jobs

Format 3:

crontab -r[ login_name]

-r

(remove)

crontab deletes your crontab file /var/spool/cron/crontabs/login_name.

login_name

If a login_name is specified, the crontab file of the corresponding user is deleted. However, only the POSIX administrator is permitted to specify a login_name.

Editing scheduled jobs

Format 4:

crontab -e[ login_name]

-e

(edit)

The -e option allows you to edit a copy of your crontab file or to create an empty file to edit (if crontab does not exist) and save this file as the current crontab file. The VISUAL environment variable determines which editor is called. If VISUAL is not defined, the EDITOR environment variable is checked, and if EDITOR is not defined, ed is invoked.

login_name

If a login_name is specified, the crontab file of the corresponding user is edited. However, only the POSIX administrator is permitted to specify a login_name.

Format of a crontab file

Your crontab file, or the text that you enter from standard input, (see Format 1) must be in the following format:

Text comprising:

• lines to define a command job, and

• comment lines, if required.

Blank lines are not permitted.

Command job definition lines

A line defining a command job consists of six fields separated by blanks or tabs. The fields contain the following information:

1	2	3	4	5	6
minute	hour	day of month	month	day of week	command

Fields 1 to 5 specify the times at which the command in field 6 is to be executed.

Minute	Range of values: 0-59 or pattern
Hour	Range of values: 0-23 or pattern
Day of month	Range of values: 1-31 or pattern
Month	Range of values: 1-12 or pattern
Day of week	Range of values: 0-6 (0=Sunday) or pattern
Command	Name of the command that is to be executed at the specified time. If your command needs to read data from standard input, you have to use the percent character %. Each % character in the command field that has not been escaped with a backslash (\) is interpreted as a newline character. The shell executes the content of the command field only up to the first unescaped percent or newline character; the remainder of the field is passed to the command as standard input (see example 3).

pattern may be:

• an asterisk * (standing for all legal values)

• a range described as number-number

• a comma-separated list of legal numbers or ranges,
  e.g.: 1,3,5 or 1-3,5

Specifying the day

Two fields are available for specifying the day; field 3 (day of month) and field 5 (day of week).

If you enter a number, a range or a list in the third field as well in the the fifth field, both specifications are valid, independently of each other.

For example, if your crontab file contains the line:

0 0 1,15 3 1 command

then command will be executed on March 1 and March 15 as well as on every Monday in March.

If you wish to specify the day in one field only, you must enter an asterisk in the second field.
Thus if your crontab file contains the line:

0 0 * 3 1 command

then command will be executed on every Monday in March.

Comment lines

A comment line has the hash character # in column one and may be followed by any arbitrary text. You can use comment lines in the crontab file to explain the function of the command job or to arrange the job into sections for the sake of clarity. Please note that the input text that you pass to crontab can contain any number of comment lines but must not include any blank lines.

Error

crontab: you are not authorized to use cron. Sorry.

See Before the call above.

Format 1

crontab: can't open your crontab file.

You have called crontab with the name of a file which does not exist or cannot be accessed.

crontab: error in previous line; ...

If any line of the input text that you pass to crontab is not in the correct format, crontab displays the relevant line followed by the above error message. The ellipses (...) shown here are replaced by a more detailed description of the error, e.g.:

unexpected character found in line

An illegal character was found in the line.

number out of bounds

A specified number is not in the permitted range.

Format 2

crontab: can't open your crontab file.

Your crontab file /var/spool/cron/crontabs/login_name does not exist and therefore cannot be read with crontab -l.

File

/usr/lib/cron.d/cron.allow

List of login names with permission to use crontab. One login name is entered per line.

/usr/lib/cron.d/cron.deny

List of login names explicitly denied permission to use crontab. One login name is entered per line.

/var/spool/cron/crontabs/login_name

crontab file of the user identified by login_name.

Variable

The following environment variables are used by crontab.

VISUAL

The VISUAL environment variable determines which editor is used when the -e option is specified.

EDITOR

If VISUAL is not set, the EDITOR environment variable determines which editor is used when the -e option is specified.

Locale

The following environment variables affect the execution of crontab:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments). LC_CTYPE governs character classes, character conversion (shifting) and the behavior of character classes in regular expressions.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

You want the system to remind you on May 15 every year that it is Aunt Jemima’s birthday.
To do this, you set up a file called birthday with the following contents:

0 0 15 5 * echo Today is Aunt Jemima's birthday !!!

Please note that since you only wish to make an entry for the day of the month and not for the day of the week, you must enter an asterisk in the "day of week" field.

You now pass the file named birthday to your crontab file:

$ crontab birthday

The system will then send you the appropriate message via mailx at 00.00 hours on May 15 of each year. This will obviously only function if the system has not been turned off during that night.

Example 2

Let us assume that on every Monday, at 1:30 p.m., you want to remind yourself and a coworker of your aerobics class that evening. Your reminder is to be displayed on the screen. You are at terminal tty007 and she is at terminal tty014. You can also include comment lines in the input text so that your text is easier to read with crontab -l at a later stage. Your crontab file could then be set up as follows:

# *   = all legal values
# n-n = range
# n,n = list
# Day of week: 0 = Sunday
#
# Min  Hrs  Day(Mon)  Mon  Day(Wk)  Command
#
30   13      *        *    1      echo Aerobics this evening ! >/dev/tty007
30   13      *        *    1      echo Aerobics this evening ! >/dev/tty014

Every Monday at 1:30 p.m., you and your colleague will now receive the message "Aerobics this evening !" at your respective terminals (and not in your mailboxes).

Example 3

Every Monday, you want to mailx the message below to user melodie, who works on a system called jukebox:

It may be blue

But it will pass too!

You do this by putting the following line in your crontab file:

0 0 * * 1 mailx melodie@jukebox %It may be blue %But it will pass too!

See also

at, mailx, sh, vi