3.1 Guile Syntax

3.1.1 Job specification

In Guile-formatted configuration files each command that needs executing is introduced with the job function. This function takes two mandatory 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. Additionally a user keyword argument can be supplied to use a different user than the one defined in the configuration-user global variable.

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 given time. If an extra argument is supplied, it should 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). ²

Similarly to next-second-from, there are also next-minute-from, next-hour-from, next-day-from, next-month-from, next-year-from.

Furthermore, the optional argument can be fulfilled by the Guile function (iota count . start step), which will provide a list of count values from start, with the step if given. For example (iota 10 0 2) will yield the list '(0 2 4 6 8).

As a convenience, mcron itself provides a function range, such that (range start end . step) 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 also 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 (technically known as an S-expression) made up of the functions (next-second . args), (next-minute...), etc, where the optional arguments can be supplied with the iota or range functions above (these functions are analogous to the ones above except that they implicitly assume the current time; it is supplied by mcron when the list is eval’d).

If the first argument to the job function is a string, it is expected to be a POSIX crontab-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. The command is executed in the home directory and with the UID of user. 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.

3.1.2 Sending output as e-mail

When jobs are specified in a POSIX-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 in mcron 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 standard 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 POSIX specifications, and information is piped to the shell command’s standard input.

3.1.3 Setting environment variables

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.