In Guile-formatted configuration files each command that needs
executing is introduced with the 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.
When jobs are specified in a vixie-style configuration, the command is broken at a percentage sign, and the stuff that comes after this is sent into the command's standard input. Furthermore, any output from the command is mailed to the user. This functionality is provided for compatibility with Vixie cron, but it is also available to scheme configuration files. The command (with-mail-out action . user) can be used to direct output from the action (which may be a procedure, list, or string) into an e-mail to the user.
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.
Also for compatibility with Vixie cron, mcron has the ability to set environment variables in configuration files. To access this functionality from a scheme configuration file, use the command (append-environment-mods name value), where name is the name of an environment variable, and value is the value put to it. A value of #f will remove the variable from the environment.
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.
[1] 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.