| [Top] | [Contents] | [Index] | [ ? ] |
This file documents the mcron command (Mellor's cron) for
running jobs at scheduled times.
1. Introducing mcron 2. Simple examples How to use mcron 99.9% of the time. 3. Full available syntax All the possibilities for configuring cron jobs. 4. Detailed invoking What happens when you run the mcron command. 5. Guile modules Incorporating mcron into another Guile program. Index The complete index.
-- The Detailed Node Listing ---
Simple examples
2.1 Guile 2.2 Vixie
Full available syntax
3.1 Guile Syntax 3.2 Extended Guile examples 3.3 Vixie
Extended Guile examples
3.2.1 Synthesizing "at" commands 3.2.2 Every second Sunday 3.2.3 Two hours every day 3.2.4 Missing the first appointment 3.2.5 Penultimate day of every month
Vixie
3.3.1 Paul Vixie's copyright 3.3.2 Crontab files. 3.3.3 Extensions and incompatibilities.
Detailed invoking
4.1 Running mcron 4.2 Running cron or crond 4.3 Running crontab 4.4 Exit codes
Guile modules
5.1 The core module The job list and execution loop. 5.2 The redirect module Sending output of jobs to a mail box. 5.3 The vixie-time module Parsing vixie-style time specifications. 5.4 The job-specifier module All commands for scheme configuration files. 5.5 The vixie-specification module Commands for reading vixie-style crontabs.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The new idea is to read the required command instructions, work out which command needs to be executed next, and then sleep until the inferred time has arrived. On waking the commands are run, and the time of the next command is computed. Furthermore, the specifications are written in scheme, allowing at the same time simple command execution instructions and very much more flexible ones to be composed than the original Vixie format. This has several useful advantages over the original idea.
A full discussion of the design and philosophy of mcron can be found in the white paper at http://rdmp.org:20202/mcron.html.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
2.1 Guile 2.2 Vixie
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
my-program in your home directory, which
you want to run every hour. Create a file job.guile in directory
~/.cron with the following contents
(job '(next-hour) "my-program") |
then run the command mcron.
Want the program to run fifteen minutes past the hour, every two hours? Edit the file to read
(job
'(next-minute-from
(next-hour (range 0 24 2))
15)
"my-program")
|
and run the command mcron.
Or, if you are not comfortable with Scheme, you could use (and see also the next section)
(job "15 */2 * * *" "my-program") |
and run the mcron command.
If you want to run other jobs, you can either add more lines to this
file, or you can create other files in your .cron directory
with the .guile extension. Alternatively, you can use any file
you want and pass it as an argument to mcron, or even pipe the
commands into the standard input.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
my-program in your home directory, which
you want to run every hour. Create a file job.vixie in directory
~/.cron with the following contents
0 * * * * my-program |
then run the command mcron.
Alternatively (full compatibility with Vixie cron), set your
environment variable EDITOR to your favorite editor, run
crontab -e, put the above line into the edit buffer, save and
exit. For this to work the cron daemon must be already running
on your system, by root.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.1 Guile Syntax 3.2 Extended Guile examples 3.3 Vixie
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
job function. This function
always takes two arguments, the first a time specification, and the
second a command specification. An optional third argument may contain
a string to display when this job is listed in a schedule.
The first argument can be a procedure, a list, or a string. If a function is supplied, it must take exactly one argument, which will be the "current" time in UNIX format, and the return value of the function must be the time in UNIX format when this action should next be run. The following functions are available to facilitate the computation:
(next-second-from time . args) without arguments this
returns the second after the current one. With the extra arguments,
these form a list of seconds in the minute when the action should run,
and the function will return the time of the next allowed second
(which may be in the next minute of the hour). (1)
Similarly to next-second-from, there are also
next-minute-from, next-hour-from, next-day-from,
next-week-from, next-month-from, next-year-from.
Furthermore, the optional argument can be fulfilled by the function
(range start end . step), which will provide a list of values
from start to (but not including) end, with the step if given. For
example (range 0 10 2) will yield the list '(0 2 4 6 8).
If the first argument to the job function is a list, it is
taken to be program code made up of the functions (next-second
. args), (next-minute...), etc, where the optional arguments
can be supplied with the (range) function above (these
functions are analogous to the ones above except that they implicitly
assume the current time; it is supplied by the mcron core when the
list is eval'd).
If the first argument to the job function is a string, it is
expected to be a Vixie cron-style time specification. See the section
on Vixie syntax for this.
The second argument to the (job) function can be either a
string, a list, or a function. In all cases the command is executed in
the user's home directory, under the user's own UID. If a string is
passed, it is assumed to be shell script and is executed with the
user's default shell. If a list is passed it is assumed to be scheme
code and is eval'd as such. A supplied function should take exactly
zero arguments, and will be called at the pertinent times.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In the case that the action is a string, then percentage signs are processed as per the vixie specifications, and information is piped to the shell command's standard input.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Note that environment modifications are accumulated as the configuration file is processed, so when a job actually runs, its environment will be modified according to the modifications specified before the job specification in the configuration file.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.2.1 Synthesizing "at" commands 3.2.2 Every second Sunday 3.2.3 Two hours every day 3.2.4 Missing the first appointment 3.2.5 Penultimate day of every month
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Suppose the program my-program needs to be run at midnight
tonight. A Guile script like the following should work. FIXME: TEST
THIS EXAMPLE.
(define my-program-flag #t)
(job (lambda (current-time)
(if my-program-flag
(begin
(set! my-program-flag #f)
(next-day-from current-time))
99999999))
(lambda () (system "my-program")
(kill (getppid))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
my-program on the second Sunday of every month, a Guile
script like the following should suffice (it is left as an exercise to
the student to understand how this works!). FIXME: TEST THIS EXAMPLE.
(job (lambda (current-time)
(let* ((next-month (next-month-from current-time))
(first-day (tm:wday (localtime next-month)))
(second-sunday (if (eqv? first-day 0)
8
(- 15 first-day))))
(+ next-month (* 24 60 60 second-sunday))))
"my-program")
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(job '(next-hour-from (next-day) '(1 2))
"my-program")
|
Rather than running the my-program program at one o'clock and two o'clock every day, it will only run it at one o'clock. This is because each time mcron has to compute the next time to run the command, it first obtains the next day, and then finds the earliest hour in that day to run at. Thus, after running the command at one o'clock, the program first skips forwards to the next midnight (missing the two o'clock appointment), and then finds the next one o'clock schedule.
The following simple command is the correct way to specify this behaviour.
(job '(next-hour '(1 2)) "my-program") |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(job '(next-hour-from (next-day) '(16))
"my-program")
|
will run my-program every day at four o'clock in the
afternoon. However, if mcron is started with this script at midday,
the first time the command will run will be four o'clock tomorrow;
today's appointment will be missed (one time only).
The correct way to specify this requirement is simply
(job '(next-hour '(16))
"my-program")
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
my-program program on the
second-to-last day of every month.
(job '(- (next-month-from (next-month)) (* 48 3600))
"my-program")
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are three problems with this specification.
1. It is allowed to specify days of the month in the range 0-31. What does it mean to specify day 0? Looking at the Vixie source code, it seems that if this date appears as part of a list, it has no effect. However, if it appears on its own, the effect is to say "don't run on any particular day of the month, only take the week-day specification into account." Mcron has been coded to mimic this behaviour as a special case (unmodified mcron logic implies that this date specification would cause jobs to run on the last day of the previous month).
2. Similarly to the above (but different), months of the year can be specified in the range 0-12. In the case of mcron (don't know what Vixie cron did) month 12 will cause the program to wait until January of the following year (but don't rely on this).
3. Somewhere it says that cron sets the SHELL environment variable to /bin/sh, and elsewhere it implies that the default behaviour is for the user's default shell to be used to execute commands. Mcron sets the variable and runs the command in the user's default shell, as advertised by the /etc/passwd file.
3.3.1 Paul Vixie's copyright 3.3.2 Crontab files. 3.3.3 Extensions and incompatibilities.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Copyright 1988,1990,1993,1994 by Paul Vixie All rights reservedDistribute freely, except: don't remove my name from the source or documentation (don't take credit for my work), mark your changes (don't get me blamed for your possible bugs), don't alter or remove this notice. May be sold if buildable source is provided to buyer. No warrantee of any kind, express or implied, is included with this software; use at your own risk, responsibility for damages (if any) to anyone resulting from the use of this software rests entirely with the user.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
crontab file contains instructions to the cron daemon
of the general form: "run this command at this time on this date".
Each user has their own crontab, and commands in any given crontab
will be executed as the user who owns the crontab. Uucp and News will
usually have their own crontabs, eliminating the need for explicitly
running su as part of a cron command.
Blank lines and leading spaces and tabs are ignored. Lines whose first non-space character is a pound-sign (#) are comments, and are ignored. Note that comments are not allowed on the same line as cron commands, since they will be taken to be part of the command. Similarly, comments are not allowed on the same line as environment variable settings.
An active line in a crontab will be either an environment setting or a cron command. An environment setting is of the form,
name = value |
where the spaces around the equal-sign (=) are optional, and any
subsequent non-leading spaces in value will be part of the
value assigned to name. The value string may be placed
in quotes (single or double, but matching) to preserve leading or
trailing blanks.
Several environment variables are set up automatically by the
cron daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are
set from the /etc/passwd line of the crontab's owner. HOME and SHELL
may be overridden by settings in the crontab; LOGNAME may not.
(Another note: the LOGNAME variable is sometimes called USER on BSD systems... on these systems, USER will be set also.) (2)
In addition to LOGNAME, HOME, and SHELL, cron will look at
MAILTO if it has any reason to send mail as a result of running
commands in "this" crontab. If MAILTO is defined (and non-empty),
mail is sent to the user so named. If MAILTO is defined but empty
(MAILTO=""), no mail will be sent. Otherwise mail is sent to the
owner of the crontab. This option is useful if you decide on
/bin/mail instead of /usr/lib/sendmail as your mailer when you install
cron -- /bin/mail doesn't do aliasing, and UUCP usually doesn't read
its mail.
The format of a cron command is very much the V7 standard, with a number of
upward-compatible extensions. Each line has five time and date fields,
followed by a user name if this is the system crontab file,
followed by a command. Commands are executed by cron
when the minute, hour, and month of year fields match the current
time, and when at least one of the two day fields (day of month, or day of week)
match the current time (see "Note" below). cron examines cron entries once every minute.
The time and date fields are:
| Field | Allowed values |
| ----- | -------------- |
| minute | 0-59 |
| hour | 0-23 |
| day of month | 0-31 |
| month | 0-12 (or names, see below) |
| day of week | 0-7 (0 or 7 is Sun, or use names) |
A field may be an asterisk (*), which always stands for "first-last".
Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an "hours" entry specifies execution at hours 8, 9, 10 and 11.
Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: "1,2,5,9", "0-4,8-12".
Step values can be used in conjunction with ranges. Following
a range with "/
Names can also be used for the "month" and "day of week" fields. Use the first three letters of the particular day or month (case doesn't matter). Ranges or lists of names are not allowed. (3)
The "sixth" field (the rest of the line) specifies the command to be run. The entire command portion of the line, up to a newline or % character, will be executed by /bin/sh or by the shell specified in the SHELL variable of the cronfile. Percent-signs (%) in the command, unless escaped with backslash (\\), will be changed into newline characters, and all data after the first % will be sent to the command as standard input.
Note: The day of a command's execution can be specified by two fields -- day of month, and day of week. If both fields are restricted (ie, aren't *), the command will be run when either field matches the current time. For example,
"30 4 1,15 * 5"
would cause a command to be run at 4:30 am on the 1st and 15th of each month, plus every Friday.
EXAMPLE CRON FILE
# use /bin/sh to run commands, no matter what /etc/passwd says SHELL=/bin/sh # mail any output to `paul', no matter whose crontab this is MAILTO=paul # # run five minutes after midnight, every day 5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 # run at 2:15pm on the first of every month -- output mailed to paul 15 14 1 * * $HOME/bin/monthly # run at 10 pm on weekdays, annoy Joe 0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% 23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 5 4 * * sun echo "run at 5 after 4 every sunday" |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The recommended way to invoke the program is via the mcron personality described in the next section. The program can also be run as cron by root, and by the SUID program crontab by individual users to gain backwards compatibility with Vixie cron. However, due to the fact that this daemon process is shared by, and under control of, all the users of the system it is possible (though very unlikely) that it may become unusable, hence the recommendation to use the mcron personality.
Furthermore, the Vixie personality is considered deprecated by this author (it offers not a single advantage over the mcron personality, and bloats the code by a factor of three). It is unlikely that this personality will ever actually go away, but the program may in future be split into two distinct parts, and new developments will only take place in the part which implements the mcron personality.
4.1 Running mcron 4.2 Running cron or crond 4.3 Running crontab 4.4 Exit codes
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mcron [OPTION ...] [file ...]
which has the effect of reading all the configuration files specified
(subject to the options) and then waiting until it is time to execute
some command. If no files are given on the command line, then mcron
will look in the user's ~/.cron directory. In either case, files which
end in the extension .vixie or .vix will be assumed to contain
Vixie-style crontabs, and files ending .guile or .gle will be assumed
to contain scheme code and will be executed as such.
The program accepts the following options.
The count, if supplied, indicates the number of commands to display. The default value is 8.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
cron or crond, then
it will read all the files in /var/cron/tabs (which should only
be readable by root) and the file /etc/crontab, and then
detaches itself from the terminal to live forever as a daemon
process. Additionally, it creates a UNIX socket at
/var/cron/socket, and listens for messages sent to that socket
consisting of a user name whose crontabs have been changed. In this
case, the program will re-read that user's crontab. This is for
correct functioning with the crontab program.
Further, if the --noetc option was not used, a job is scheduled
to run every minute to check if /etc/crontab has been modified
recently. If so, this file will also be re-read.
The options which may be used with this program are as follows.
The count, if supplied, indicates the number of commands to display. The default value is 8.
/etc/crontab. It is
recommended that this option be used (and further that the
/etc/crontab file be taken off the system altogether!)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The command is used as
crontab [-u user] file
or
crontab [-u user] ( -l | -e | -r )
Only the root user can use the -u option, to specify the manipulation of another user's crontab file. In the first instance, the entire crontab file of the user is replaced with the contents of the specified file, or standard input if the file is "-".
In the latter case, the program behaves according to which of the (mutually exclusive) options was given (note that the long options are an mcron extension).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
job command has been
seen but the second argument is neither a procedure, list or
string. This argument is the job's action, and needs to be specified
in one of these forms.
job command has been
seen but the first argument is neither a procedure, list or
string. This argument is the job's next-time specification, and needs
to be specified in one of these forms.
-l,
-r, -e. These are mutually exclusive options.
mcron, cron, crond or crontab.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It may be, for example, that a program needs to perform house-keeping functions at certain times of the day, in which case it can spawn (either fork or thread) a sub-process which uses a built-in mcron. Another example may be a program which must sleep until some non-absolute time specified on the Gregorian calendar (the first day of next week, for example). Finally, it may be the wish of the user to provide a program with the functionality of mcron plus a bit extra.
The core module maintains mcron's internal job lists, and provides the main wait-run-wait loop that is mcron's main function. It also introduces the facilities for accumulating a set of environment modifiers, which take effect when jobs run.
5.1 The core module The job list and execution loop. 5.2 The redirect module Sending output of jobs to a mail box. 5.3 The vixie-time module Parsing vixie-style time specifications. 5.4 The job-specifier module All commands for scheme configuration files. 5.5 The vixie-specification module Commands for reading vixie-style crontabs.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This module may be used by including (use-modules (mcron core))
in a program. The main functions are add-job and
run-job-loop, which allow a program to create a list of job
specifications to run, and then to initiate the wait-run-wait loop
firing the jobs off at the requisite times. However, before they are
introduced two functions which manipulate the environment that takes
effect when a job runs are defined.
The environment is a set of name-value pairs which is built up
incrementally. Each time the add-job function is called, the
environment modifiers that have been accumulated up to that point are
stored with the new job specification, and when the job actually runs
these name-value pairs are used to modify the run-time environment in
effect.
run-job-loop procedure again to resume execution of
the mcron core.
The argument user should be a string naming a user (his login name), or an integer UID, or an object representing the user's passwd entry. All jobs on the current job list that are scheduled to be run under this personality are removed from the job list.
run-job-loop is called
after this procedure, the first job to run will be the one after the
last job that was reported in the schedule report. The report itself
is returned to the calling program as a string.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This module is introduced to a program with the command
(use-modules (mcron redirect)).
This module provides the with-mail-out function, described
fully in 3.1 Guile Syntax.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This module is introduced to a program by (use-modules (mcron
vixie-time)).
This module provides a single method for converting a vixie-style time
specification into a procedure which can be used as the
next-time-function to the core add-job procedure, or to
the job-specifier job procedure. See 3.3 Vixie
for full details of the allowed format for the time string.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This module is introduced to a program by (use-modules (mcron
job-specifier)).
This module provides all the functions available to user's Guile
configuration files, namely range, next-year-from,
next-year, next-month-from, next-month,
next-day-from, next-day, next-hour-from,
next-hour, next-minute-from, next-minute,
next-second-from, next-second,
and last but not least, job. See 3.1 Guile Syntax for full
details.
Once this module is loaded, a scheme configuration file can be used to
put jobs onto the job list simply by loading the file.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To use this module, put the command (use-modules (mcron
vixie-specification)) into your program.
This module exports a couple of functions for adding jobs to the internal job list according to a Vixie-style crontab file.
This procedure reads a crontab from the given port, and adds jobs to the job list accordingly, taking care of environment specifications and comments which may appear in such a file.
parse-line should not normally be used, except that if you are
parsing a (deprecated) /etc/crontab file with a slightly
modified syntax, you may pass the value parse-system-vixie-line
as the optional argument.
This procedure attempts to open the named file, and if it fails will
return silently. Otherwise, the behaviour is identical to
read-vixie-port above.
Once this module has been declared in a program, a crontab file can be
used to augment the current job list with a call to
read-vixie-file.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| Jump to: | %
-
/
0
1
A B C D E F G H I J L M N O P R S T U V W Z |
|---|
| Jump to: | %
-
/
0
1
A B C D E F G H I J L M N O P R S T U V W Z |
|---|
| [Top] | [Contents] | [Index] | [ ? ] |
Note that while commands can be scheduled to run at any second, it is unlikely that they will be executed then but some time shortly thereafter, depending on the load on the system and the number of jobs that mcron has to start at the same time.
mcron has not been ported to BSD, so these notes are not relevant.
Mcron allows any alphabetic characters after a name, so full names of days or months are also valid.
| [Top] | [Contents] | [Index] | [ ? ] |
| [Top] | [Contents] | [Index] | [ ? ] |
1. Introducing mcron
2. Simple examples
3. Full available syntax
4. Detailed invoking
5. Guile modules
Index
| [Top] | [Contents] | [Index] | [ ? ] |
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
| [ < ] | Back | previous section in reading order | 1.2.2 |
| [ > ] | Forward | next section in reading order | 1.2.4 |
| [ << ] | FastBack | previous or up-and-previous section | 1.1 |
| [ Up ] | Up | up section | 1.2 |
| [ >> ] | FastForward | next or up-and-next section | 1.3 |
| [Top] | Top | cover (top) of document | |
| [Contents] | Contents | table of contents | |
| [Index] | Index | concept index | |
| [ ? ] | About | this page |