>From b71a9d9ddcff21d366e0e0fb14f494f74ac3d008 Mon Sep 17 00:00:00 2001 From: Mathieu Lirzin Date: Fri, 26 Jun 2015 23:17:01 +0200 Subject: [PATCH 2/4] Fix build of the manual. --- .gitignore | 9 +- ChangeLog | 9 + README--git | 11 +- configure.ac | 7 +- doc/config.texi.in | 5 + doc/mcron.texi | 1337 ++++++++++++++++++++++++++++++++++++++++++++++++++++ makefile.am | 9 +- mcron.texinfo.in | 1335 --------------------------------------------------- 8 files changed, 1372 insertions(+), 1350 deletions(-) create mode 100644 doc/config.texi.in create mode 100644 doc/mcron.texi delete mode 100644 mcron.texinfo.in diff --git a/.gitignore b/.gitignore index 00fa239..2bedd6e 100644 --- a/.gitignore +++ b/.gitignore @@ -10,13 +10,18 @@ config.status configure core.scm depcomp +/doc/.dirstamp +/doc/config.texi +/doc/mcron.info +/doc/mcron.1 +/doc/stamp-vti +/doc/version.texi install-sh makefile makefile.in /mcron mcron.c -mcron.info +/mdate-sh *.o -mcron.texinfo missing texinfo.tex diff --git a/ChangeLog b/ChangeLog index cccecbe..806a03f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,14 @@ 2015-06-26 Mathieu Lirzin + Fix build of the manual. + * mcron.texinfo.in: Move to ... + * doc/mcron.texi: ... Here. New file. + * doc/config.texi.in: New file. + * configure.ac: Adapt to it. + * makefile.am: Likewise. + * .gitignore: Likewise. + * README--git: Likewise. + Add missing 'makefile.am'. * scm/mcron/makefile.am: New file. * .gitignore: Ignore 'mcron' only in the top-level directory. diff --git a/README--git b/README--git index 43e9890..9ebaa0d 100644 --- a/README--git +++ b/README--git @@ -1,6 +1,7 @@ GNU mcron --- README--git -*-text-*- Copyright (C) 2012, 2014 Dale Mellor + Copyright (C) 2015 Mathieu Lirzin Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright @@ -10,13 +11,9 @@ GNU mcron --- README--git -*-text-*- If you have pulled mcron from the GIT repository, these are the steps you will need to take to build it the first time: -1) aclocal -2) autoconf -3) automake -a (will error) -4) ./configure (will error) -5) automake -a -6) ./configure --prefix={wherever} -7) make install +1) autoreconf -vfi +2) ./configure --prefix={wherever} +3) make install After that it should just be a simple matter of typing `make install' when you diff --git a/configure.ac b/configure.ac index c819d4d..7422469 100644 --- a/configure.ac +++ b/configure.ac @@ -3,6 +3,7 @@ # Copyright (C) 2003, 2005, 2012, 2014 Dale Mellor +# Copyright (C) 2015 Mathieu Lirzin # # This file is part of GNU mcron. # @@ -170,6 +171,8 @@ AC_SUBST(CONFIG_TMP_DIR) real_program_prefix=`echo $program_prefix | sed s/NONE//` AC_SUBST(real_program_prefix) - -AC_CONFIG_FILES(mcron.texinfo makefile scm/mcron/makefile scm/mcron/config.scm) +AC_CONFIG_FILES([doc/config.texi + makefile + scm/mcron/makefile + scm/mcron/config.scm]) AC_OUTPUT diff --git a/doc/config.texi.in b/doc/config.texi.in new file mode 100644 index 0000000..50d9a18 --- /dev/null +++ b/doc/config.texi.in @@ -0,0 +1,5 @@ address@hidden CONFIG_SOCKET_FILE @CONFIG_SOCKET_FILE@ address@hidden CONFIG_SPOOL_DIR @CONFIG_SPOOL_DIR@ address@hidden CONFIG_PID_FILE @CONFIG_PID_FILE@ address@hidden CONFIG_ALLOW_FILE @CONFIG_ALLOW_FILE@ address@hidden CONFIG_DENY_FILE @CONFIG_DENY_FILE@ diff --git a/doc/mcron.texi b/doc/mcron.texi new file mode 100644 index 0000000..cb97a06 --- /dev/null +++ b/doc/mcron.texi @@ -0,0 +1,1337 @@ +\input texinfo address@hidden %**start of header address@hidden mcron.info address@hidden config.texi address@hidden version.texi address@hidden mcron @value{VERSION} address@hidden %**end of header + address@hidden fn cp + address@hidden This manual is for GNU mcron (version @value{VERSION}), which is a +program for running jobs at scheduled times. + +Copyright @copyright{} 2003, 2005, 2006, 2012, 2014 Dale Mellor + address@hidden +Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, +Version 1.3 or any later version published by the Free Software +Foundation; with no Invariant Sections, no Front-Cover Texts and +no Back-Cover Texts. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. address@hidden quotation address@hidden copying + + address@hidden + address@hidden Individual utilities + address@hidden +* mcron: (mcron). Run jobs at scheduled times. address@hidden direntry + address@hidden ifinfo + + address@hidden address@hidden mcron - Mellor's cron daemon address@hidden Dale Mellor + address@hidden address@hidden 0pt plus 1fill address@hidden @insertcopying + address@hidden titlepage + address@hidden + address@hidden address@hidden Top, Introduction, (dir), (dir) address@hidden mcron + +This file documents the @code{mcron} command (Mellor's cron) for +running jobs at scheduled times. + address@hidden @insertcopying address@hidden ifnottex + address@hidden +* Introduction:: Introducing mcron. +* Simple examples:: How to use mcron 99.9% of the time. +* Syntax:: All the possibilities for configuring cron jobs. +* Invoking:: What happens when you run the mcron command. +* Guile modules:: Incorporating mcron into another Guile program. +* Index:: The complete index. + address@hidden + --- The Detailed Node Listing --- + +Simple examples + +* Guile Simple Examples:: +* Vixie Simple Examples:: + +Full available syntax + +* Guile Syntax:: +* Extended Guile examples:: +* Vixie Syntax:: + +Extended Guile examples + +* AT commands:: +* Every second Sunday:: +* Two hours every day:: +* Missing the first appointment:: +* Penultimate day of every month:: + +Vixie + +* Paul Vixie's copyright:: +* Crontab file:: +* Incompatibilities with old Unices:: + +Detailed invoking + +* Invoking mcron:: +* Invoking cron or crond:: +* Invoking crontab:: +* Behaviour on laptops:: +* Exit codes:: + +Guile modules + +* The core module:: The job list and execution loop. +* The redirect module:: Sending output of jobs to a mail box. +* The vixie-time module:: Parsing vixie-style time specifications. +* The job-specifier module:: All commands for scheme configuration files. +* The vixie-specification module:: Commands for reading vixie-style crontabs. + address@hidden detailmenu address@hidden menu + address@hidden Introduction, Simple examples, Top, Top address@hidden Introducing mcron address@hidden introduction address@hidden mcron +The mcron program represents a complete re-think of the cron concept +originally found in the Berkeley and AT&T unices, and subsequently +rationalized by Paul Vixie. The original idea was to have a daemon +that wakes up every minute, scans a set of files under a special +directory, and determines from those files if any shell commands +should be executed in this minute. + +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. (Changes to user crontabs are signalled +directly to mcron by the crontab program; cron must still scan the +/etc/crontab file once every minute, although use of this file is +highly discouraged and this behaviour can be turned off). + address@hidden advantages of mcron address@hidden @bullet address@hidden +Does not consume CPU resources when not needed. Many cron daemons only +run jobs once an hour, or even just once a day. address@hidden +Can easily allow for finer time-points to be specified, +i.e. seconds. In principle this could be extended to microseconds, but +this is not implemented. address@hidden +Times can be more or less regular. For example, a job that runs +every 17 hours can be specified, or a job that runs on the first +Sunday of every month. address@hidden +Times can be dynamic. Arbitrary Guile (scheme) code can be provided to +compute the next time that a command needs to be run. This could, for +example, take the system load into consideration. address@hidden +Turns out to be easy to provide complete backwards compatibility with +Vixie cron. address@hidden +Each user looks after his own files in his own directory. He can use +more than one to break up complicated cron specifications. address@hidden +Each user can run his own daemon. This removes the need for suid +programs to manipulate the crontabs, and eliminates many security +concerns that surround all existing cron programs. address@hidden +The user can obtain an advance schedule of all the jobs that are due +to run. address@hidden +Vixie cron is implemented in 4500 lines of C code; mcron is 2000 lines +of scheme, despite the fact that it offers many more features and much +more flexibility, and complete compatibility with Vixie cron. address@hidden itemize + +A full discussion of the design and philosophy of mcron can be found +in the white paper at address@hidden://www.gnu.org/software/mcron/design.html}. + + address@hidden Simple examples, Syntax, Introduction, Top address@hidden Simple examples +The vast majority of uses of cron are sublimely simple: run a program +every hour, or every day. With this in mind the design of mcron has +been to allow such simple specifications to be made easily. The +examples show how to create the command descriptions, and subsequently +how to run mcron to make them happen. address@hidden +* Guile Simple Examples:: +* Vixie Simple Examples:: address@hidden menu + address@hidden Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples address@hidden Guile address@hidden guile examples address@hidden examples, guile address@hidden example, run a program every hour +You have an executable @code{my-program} in your home directory, which +you want to run every hour. Create a file @code{job.guile} in +directory @code{~/.config/cron} (this path may be altered by the address@hidden environment variable) with the following +contents + address@hidden +(job '(next-hour) "my-program") address@hidden example + +then run the command @code{mcron}. + +Want the program to run fifteen minutes past the hour, every two +hours? Edit the file to read + address@hidden +(job + '(next-minute-from + (next-hour (range 0 24 2)) + 15) + "my-program") address@hidden example + +and run the command @code{mcron}. + +Or, if you are not comfortable with Scheme, you could use (and see +also the next section) + address@hidden +(job "15 */2 * * *" "my-program") address@hidden example + +and run the @code{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 @code{.config/cron} directory +with the @code{.guile} extension. Alternatively, you can use any file +you want and pass it as an argument to @code{mcron}, or even pipe the +commands into the standard input. + + address@hidden Vixie Simple Examples, , Guile Simple Examples, Simple examples address@hidden Vixie address@hidden examples address@hidden examples, vixie address@hidden vixie examples +You have an executable @code{my-program} in your home directory, which +you want to run every hour. Create a file @code{job.vixie} in directory address@hidden/.cron} with the following contents + address@hidden +0 * * * * my-program address@hidden example + +then run the command @code{mcron}. + address@hidden vixie compatibility address@hidden compatibility +Alternatively (full compatibility with Vixie cron), set your +environment variable @code{EDITOR} to your favorite editor, run address@hidden -e}, put the above line into the edit buffer, save and +exit. For this to work the @code{cron} daemon must be already running +on your system, as root. + address@hidden Syntax, Invoking, Simple examples, Top address@hidden Full available syntax address@hidden +* Guile Syntax:: +* Extended Guile examples:: +* Vixie Syntax:: address@hidden menu address@hidden Guile Syntax, Extended Guile examples, Syntax, Syntax address@hidden Guile Syntax address@hidden Job specification address@hidden guile syntax address@hidden syntax, guile address@hidden job +In Guile-formatted configuration files each command that needs +executing is introduced with the @code{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. + address@hidden time specification, procedure address@hidden procedure time specification +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: + address@hidden next-second-from address@hidden(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). @footnote{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.} + address@hidden next-minute-from address@hidden next-hour-from address@hidden next-day-from address@hidden next-week-from address@hidden next-month-from address@hidden next-year-from +Similarly to @code{next-second-from}, there are also address@hidden, @code{next-hour-from}, @code{next-day-from}, address@hidden, @code{next-month-from}, @code{next-year-from}. + address@hidden range +Furthermore, the optional argument can be fulfilled by the function address@hidden(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 @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}. + address@hidden next-second address@hidden next-minute address@hidden next-hour address@hidden next-day address@hidden next-week address@hidden next-month address@hidden next-year address@hidden time specification, list address@hidden list time specification +If the first argument to the @code{job} function is a list, it is +taken to be program code made up of the functions @code{(next-second +. args)}, @code{(next-minute...)}, etc, where the optional arguments +can be supplied with the @code{(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). + address@hidden time specification address@hidden time specification, string address@hidden string time specification address@hidden time specification, vixie-style address@hidden vixie-style time specification +If the first argument to the @code{job} function is a string, it is +expected to be a Vixie cron-style time specification. See the section +on Vixie syntax for this. + address@hidden job execution address@hidden command execution address@hidden execution +The second argument to the @code{(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. + address@hidden Sending output as e-mail address@hidden email output address@hidden email from guile script address@hidden standard input to commands address@hidden with-mail-out +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. + address@hidden Setting environment variables address@hidden environment variables in scheme address@hidden setting environment variables address@hidden append-environment-mods +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. + + address@hidden Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax address@hidden Extended Guile examples address@hidden examples, extended guile address@hidden extended guile examples +While Guile gives you flexibility to do anything, and the power to +represent complex requirements succinctly, things are not always as +they seem. The following examples illustrate some pitfalls, and +demonstrate how to code around them. + address@hidden +* AT commands:: +* Every second Sunday:: +* Two hours every day:: +* Missing the first appointment:: +* Penultimate day of every month:: address@hidden menu + address@hidden AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples address@hidden Synthesizing ``at'' commands address@hidden at command +The current implementation of mcron does not provide for an at command +(a command-line program that allows the user to specify that a job +runs exactly once at a certain time). This can, however, be achieved. + +Suppose the program @code{my-program} needs to be run at midnight +tonight. A Guile script like the following would work (but a printed +schedule, obtained with the @code{--schedule} option, will show +superfluous entries). + address@hidden +(job '(next-day) + (lambda () (system "my-program") + (kill (getppid) SIGINT))) address@hidden example + address@hidden Every second Sunday, Two hours every day, AT commands, Extended Guile examples address@hidden Every second Sunday address@hidden examples, every second sunday +To run @code{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!). + address@hidden +(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 + (- 14 first-day)))) + (+ next-month (* 24 60 60 second-sunday)))) + "my-program") address@hidden example + + address@hidden Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples address@hidden Two hours every day address@hidden examples, two hours every day address@hidden pitfalls, two hours every day +Surprisingly perhaps, the following will @strong{not} have the desired +effect. + address@hidden +(job '(next-hour-from (next-day) '(1 2)) + "my-program") address@hidden example + +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. + address@hidden +(job '(next-hour '(1 2)) "my-program") address@hidden example + + address@hidden Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples address@hidden Missing the first appointment address@hidden examples, missing the first appointment address@hidden pitfalls, missing the first appointment +The command + address@hidden +(job '(next-hour-from (next-day) '(16)) + "my-program") address@hidden example + +will run @code{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 + address@hidden +(job '(next-hour '(16)) + "my-program") address@hidden example + + address@hidden Penultimate day of every month, , Missing the first appointment, Extended Guile examples address@hidden Penultimate day of every month address@hidden examples, penultimate day of every month +The following will run the @code{my-program} program on the +second-to-last day of every month. + address@hidden +(job '(- (next-month-from (next-month)) (* 48 3600)) + "my-program") address@hidden example + + + address@hidden Vixie Syntax, , Extended Guile examples, Syntax address@hidden Vixie address@hidden syntax, vixie address@hidden vixie syntax address@hidden vixie definition address@hidden vixie compatibility address@hidden compatibility, vixie address@hidden that this section is definitive. If there is a difference in +behaviour between the mcron program and this part of the manual, then +there is a bug in the program. This section is also copied verbatim +from Paul Vixie's documentation for his cron program, and his +copyright notice is duly reproduced below. + +There are three problems with this specification. + address@hidden zero'th day of month address@hidden 0'th day of month +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). + address@hidden thirteenth month of year address@hidden 13th month of year +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). + address@hidden shell address@hidden environment variables, shell address@hidden /etc/passwd +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. + address@hidden +* Paul Vixie's copyright:: +* Crontab file:: +* Incompatibilities with old Unices:: address@hidden menu + + address@hidden Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax address@hidden Paul Vixie's copyright address@hidden copyright, Paul Vixie's address@hidden Paul Vixie's copyright address@hidden +Copyright 1988,1990,1993,1994 by Paul Vixie +All rights reserved + +Distribute 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. address@hidden quotation + + + + address@hidden Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax address@hidden Crontab files address@hidden crontab file address@hidden vixie crontab file +A @code{crontab} file contains instructions to the @code{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 @code{su} as part of a cron command. + address@hidden comments, vixie-style +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, + address@hidden environment setting, vixie-style address@hidden +name = value address@hidden example + +where the spaces around the equal-sign (=) are optional, and any +subsequent non-leading spaces in @code{value} will be part of the +value assigned to @code{name}. The @code{value} string may be placed +in quotes (single or double, but matching) to preserve leading or +trailing blanks. + address@hidden environment variables, SHELL address@hidden environment variables, LOGNAME address@hidden environment variables, HOME address@hidden SHELL environment variable address@hidden LOGNAME environment variable address@hidden HOME environment variable address@hidden /etc/passwd +Several environment variables are set up automatically by the address@hidden 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. + address@hidden environment variables, USER address@hidden USER environment variable address@hidden BSD +(Another note: the LOGNAME variable is sometimes called USER on BSD systems... +on these systems, USER will be set also.) @footnote{mcron has not been +ported to BSD, so these notes are not relevant.} + address@hidden environment variables, MAILTO address@hidden MAILTO environment variable +In addition to LOGNAME, HOME, and SHELL, @code{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 @code{cron} +when the minute, hour, and month of year fields match the current +time, @strong{and} when at least one of the two day fields (day of month, or day of week) +match the current time (see ``Note'' below). @code{cron} examines cron entries once every minute. +The time and date fields are: + address@hidden vixie time specification fields address@hidden fields, vixie time specification address@hidden @columnfractions .2 .5 address@hidden Field @tab Allowed values address@hidden ----- @tab -------------- address@hidden minute @tab 0-59 address@hidden hour @tab 0-23 address@hidden day of month @tab 0-31 address@hidden month @tab 0-12 (or names, see below) address@hidden day of week @tab 0-7 (0 or 7 is Sun, or use names) address@hidden multitable + +A field may be an asterisk (*), which always stands for ``first-last''. + address@hidden ranges in vixie time specifications +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. + address@hidden lists in vixie time specifications +Lists are allowed. A list is a set of numbers (or ranges) +separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''. + address@hidden steps in vixie time specifications +Step values can be used in conjunction with ranges. Following +a range with ``/'' specifies skips of the number's value +through the range. For example, ``0-23/2'' can be used in the hours +field to specify command execution every other hour (the alternative +in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are +also permitted after an asterisk, so if you want to say ``every two +hours'', just use ``*/2''. + address@hidden names in vixie-style time specifications +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. @footnote{Mcron allows any alphabetic +characters after a name, so full names of days or months are also valid.} + address@hidden % character on vixie-style commands address@hidden standard input, vixie-style +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. + address@hidden day specification, vixie-style address@hidden vixie-style day specification +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 address@hidden +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 + address@hidden +# 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" address@hidden example + address@hidden Incompatibilities with old Unices, , Crontab file, Vixie Syntax address@hidden Extensions and incompatibilities address@hidden incompatibilities with old Unices address@hidden extensions, vixie over old Unices +This section lists differences between Paul Vixie's cron and the +olde-worlde BSD and AT&T programs, for the benefit of system +administrators and users who are upgrading all the way. + address@hidden @bullet address@hidden address@hidden day 7 +When specifying day of week, both day 0 and day 7 will be considered Sunday. +BSD and AT&T seem to disagree about this. + address@hidden +Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would +be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY. + address@hidden +Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". + address@hidden +Names of months or days of the week can be specified by name. + address@hidden +Environment variables can be set in the crontab. In BSD or AT&T, the +environment handed to child processes is basically the one from /etc/rc. + address@hidden +Command output is mailed to the crontab owner (BSD can't do this), can be +mailed to a person other than the crontab owner (SysV can't do this), or the +feature can be turned off and no mail will be sent at all (SysV can't do this +either). + address@hidden itemize + + address@hidden Invoking, Guile modules, Syntax, Top address@hidden Detailed invoking address@hidden invoking address@hidden personality address@hidden mcron program address@hidden cron program address@hidden crond program address@hidden crontab program +The program adopts one of three different personalities depending on +the name used to invoke it. In a standard installation, the program is +installed in the system under the names mcron, cron and crontab +(installed SUID). + +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. + address@hidden deprecated, vixie 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. + + + address@hidden +* Invoking mcron:: +* Invoking cron or crond:: +* Invoking crontab:: +* Behaviour on laptops:: +* Exit codes:: address@hidden menu + address@hidden Invoking mcron, Invoking cron or crond, Invoking, Invoking address@hidden Invoking mcron address@hidden invoking mcron address@hidden mcron options address@hidden mcron arguments address@hidden command line, mcron address@hidden mcron command line +Mcron should be run by the user who wants to schedule his jobs. It +may be made a background job using the facilities of the shell. The +basic command is @code{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 configuration directories: these are ~/.cron +(deprecated), the directory indicated by the @code{XDG_CONFIG_HOME} +environment variable, or ~/.config/cron if this variable is not set. +In any 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; ANY OTHER FILES WILL BE IGNORED - specify a file name of ``-'' +and then pipe the files into the standard input if you really want to +read them, possibly using the @code{stdin} option to specify the type +of file. + +The program accepts the following options. + address@hidden @option address@hidden -s count address@hidden --schedule=count address@hidden printout of jobs schedule address@hidden schedule of jobs, listing address@hidden options, schedule address@hidden options, -s address@hidden -s option address@hidden --schedule option +With this option specified no commands are run. Instead, the program +computes the times the commands would be run and prints the +information to the screen, and then immediately exits. + +The count indicates the number of commands to display. + address@hidden daemon option address@hidden options, daemon address@hidden options, -d address@hidden -d option address@hidden --daemon option address@hidden -d address@hidden --daemon +With this option the program will detach itself from the controlling +terminal and run as a daemon process. + address@hidden stdin option address@hidden options, stdin address@hidden options, -i address@hidden -i option address@hidden --stdin option address@hidden standard input, configuring from address@hidden configuring from standard input address@hidden -i (vixie|guile) address@hidden --stdin=(vixie|guile) +This option is used to indicate whether the configuration information +being passed on the standard input is in Vixie format or Guile +format. Guile is the default. + address@hidden -v option address@hidden --version option address@hidden options, -v address@hidden options, version address@hidden -v address@hidden --version +This option causes a message to be printed on the standard output with +information about the version and copyright for the current program. + address@hidden -h option address@hidden --help option address@hidden options, -h address@hidden options, --help address@hidden -h address@hidden --help +This causes a short but complete usage message to be displayed on +standard output. + address@hidden table + address@hidden Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking address@hidden Invoking cron or crond address@hidden cron, invokation address@hidden invoking cron address@hidden crond, invokation address@hidden invoking crond address@hidden @value{CONFIG_SPOOL_DIR} address@hidden @value{CONFIG_SOCKET_FILE} +NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or address@hidden, and @code{crontab} PROGRAMS HAVE BEEN INSTALLED BY THE +SYSTEM ADMINISTRATOR. + +If the program runs by the name of @code{cron} or @code{crond}, then +it will read all the files in @address@hidden (which +should only be readable by root) and the file @code{/etc/crontab}, and +then detaches itself from the terminal to live forever as a daemon +process. Additionally, it creates a UNIX socket at address@hidden@value{CONFIG_SOCKET_FILE}}, 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 @code{--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. + address@hidden @option + address@hidden -v option address@hidden --version option address@hidden options, -v address@hidden options, version address@hidden -v address@hidden --version +This option causes a message to be printed on the standard output with +information about the version and copyright for the current program. + address@hidden -h option address@hidden --help option address@hidden options, -h address@hidden options, --help address@hidden -h address@hidden --help +This causes a short but complete usage message to be displayed on +standard output. + address@hidden -s [count] address@hidden --schedule[=count] address@hidden printout of jobs schedule address@hidden schedule of jobs, listing address@hidden options, schedule address@hidden options, -s address@hidden -s option address@hidden --schedule option +With this option specified no commands are run. Instead, the program +computes the times the commands would be run and prints the +information to the screen, and then immediately exits. + +The count, if supplied, indicates the number of commands to +display. The default value is 8. + address@hidden -n option address@hidden --noetc option address@hidden options, -n address@hidden options, --noetc address@hidden -n address@hidden --noetc +This tells cron not to add a job to the system which wakes up every +minute to check for modifications to @code{/etc/crontab}. It is +recommended that this option be used (and further that the address@hidden/etc/crontab} file be taken off the system altogether!) + address@hidden table + address@hidden Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking address@hidden Invoking crontab address@hidden crontab, invoking address@hidden invoking crontab +This program is run by individual users to inspect or modify their +crontab files. If a change is made to the file, then the root daemon +process will be given a kick, and will immediately read the new +configuration. A warning will be issued to standard output if it +appears that a cron daemon is not running. + +The command is used as + address@hidden [-u user] file} + +or + address@hidden [-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). + address@hidden @option + address@hidden -l option address@hidden list option, crontab address@hidden options, -l address@hidden options, --list address@hidden viewing a crontab address@hidden listing a crontab address@hidden -l address@hidden --list +Print the user's crontab file to the standard output, and exit. + address@hidden -r option address@hidden remove option address@hidden options, -r address@hidden options, --remove address@hidden deleting a crontab address@hidden removing a crontab address@hidden -r address@hidden --remove +Delete the user's crontab file, and exit. + address@hidden -e option address@hidden edit option address@hidden options, -e address@hidden options, --edit address@hidden editing a crontab address@hidden creating a crontab address@hidden -e address@hidden --edit +Using the editor specified in the user's VISUAL or EDITOR environment +variables, allow the user to edit his crontab. Once the user exits the +editor, the crontab is checked for parseability, and if it is okay +then it is installed as the user's new crontab and the daemon is +notified that a change has taken place, so that the new file will +become immediately effective. + address@hidden table + + address@hidden Behaviour on laptops, Exit codes, Invoking crontab, Invoking address@hidden Behaviour on laptops address@hidden laptops address@hidden power suspend +While mcron has not been designed to work anachronistically, the behaviour of +mcron when a laptop emerges from a suspended state is well defined, and the +following description explains what happens in this situation. + +When a laptop awakes from a suspended state, all jobs which would have run while +the laptop was suspended will run exactly once immediately (and simultaneously) +when the laptop awakes, and then the next time that those jobs run will be +computed based on the time the laptop was awoken. Any jobs which would not have +run during the suspense period will be unaffected, and will still run at their +proper times. + + address@hidden Exit codes, , Behaviour on laptops, Invoking address@hidden Exit codes address@hidden exit codes address@hidden error conditions address@hidden errors +The following are the status codes returned to the operating system +when the program terminates. + address@hidden @asis address@hidden 0 +No problems. + address@hidden 1 +An attempt has been made to start cron but there is already a address@hidden file. If there really is no other cron daemon +running (this does not include invokations of mcron) then you should +remove this file before attempting to run cron. + address@hidden 2 +In parsing a guile configuration file, a @code{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. + address@hidden 3 +In parsing a guile configuration file, a @code{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. + address@hidden 4 +An attempt to run cron has been made by a user who does not have +permission to access the crontabs in @value{CONFIG_SPOOL_DIR}. These +files should be readable only by root, and the cron daemon must be run +as root. + address@hidden 5 +An attempt to run mcron has been made, but there are no jobs to +schedule! + address@hidden 6 +The system administrator has blocked this user from using crontab with +the files @value{CONFIG_ALLOW_FILE} and @value{CONFIG_DENY_FILE}. + address@hidden 7 +Crontab has been run with more than one of the arguments @code{-l}, address@hidden, @code{-e}. These are mutually exclusive options. + address@hidden 8 +Crontab has been run with the -u option by a user other than +root. Only root is allowed to use this option. + address@hidden 9 +An invalid vixie-style time specification has been supplied. + address@hidden 10 +An invalid vixie-style job specification has been supplied. + address@hidden 11 +A bad line has been seen in /etc/crontab. + address@hidden 12 +The last component of the name of the program was not one of address@hidden, @code{cron}, @code{crond} or @code{crontab}. + address@hidden 13 +Either none of the user's configuration directories exist, or there is a problem +reading the files there. The configuration directories are ~/.cron +and the directory pointed to by the @code{XDG_CONFIG_HOME} environment +variable, or ~/.config/cron if this is not set. + address@hidden @item 14 address@hidden There is a problem writing to /var/cron/update. This is probably address@hidden because the crontab program is not installed SUID root, as it should address@hidden be. + address@hidden 15 +Crontab has been run without any arguments at all. There is no default +behaviour in this case. + address@hidden 16 +Cron has been run by a user other than root. + address@hidden table + + + address@hidden Guile modules, Index, Invoking, Top address@hidden Guile modules +Some of the key parts of mcron are implemented as modules so they can +be incorporated into other Guile programs, or even into C-sourced +programs if they are linked against libguile. + +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. + address@hidden +* The core module:: The job list and execution loop. +* The redirect module:: Sending output of jobs to a mail box. +* The vixie-time module:: Parsing vixie-style time specifications. +* The job-specifier module:: All commands for scheme configuration files. +* The vixie-specification module:: Commands for reading vixie-style crontabs. address@hidden menu + address@hidden The core module, The redirect module, Guile modules, Guile modules address@hidden The core module address@hidden guile module address@hidden core module address@hidden modules, core + +This module may be used by including @code{(use-modules (mcron core))} +in a program. The main functions are @code{add-job} and address@hidden, 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. + address@hidden environment +The environment is a set of name-value pairs which is built up +incrementally. Each time the @code{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. + address@hidden procedure} append-environment-mods name value +When a job is run make sure the environment variable @var{name} has +the value @var{value}. address@hidden deffn + address@hidden procedure} clear-environment-mods +This procedure causes all the environment modifiers that have been +specified so far to be forgotten. address@hidden deffn + address@hidden procedure} add-job time-proc action displayable configuration-time configuration-user +This procedure adds a job specification to the list of all jobs to +run. @var{time-proc} should be a procedure taking exactly one argument +which will be a UNIX time. This procedure must compute the next time +that the job should run, and return the result. @var{action} should be +a procedure taking no arguments, and contains the instructions that +actually get executed whenever the job is scheduled to +run. @var{displayable} should be a string, and is only for the use of +humans; it can be anything which identifies or simply gives a clue as +to the purpose or function of this job. @var{configuration-time} is +the time from which the first invokation of this job should be +computed. Finally, @var{configuration-user} should be the passwd entry +for the user under whose personality the job is to run. address@hidden deffn + address@hidden procedure} run-job-loop . fd-list address@hidden file descriptors address@hidden interrupting the mcron loop +This procedure returns only under exceptional circumstances, but +usually loops forever waiting for the next time to arrive when a job +needs to run, running that job, recomputing the next run time, and +then waiting again. However, the wait can be interrupted by data +becoming available for reading on one of the file descriptors in the +fd-list, if supplied. Only in this case will the procedure return to +the calling program, which may then make modifications to the job list +before calling the @code{run-job-loop} procedure again to resume execution of +the mcron core. address@hidden deffn + address@hidden procedure} remove-user-jobs user + +The argument @var{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. address@hidden deffn + address@hidden procedure} get-schedule count address@hidden schedule of jobs +The argument @var{count} should be an integer value giving the number +of time-points in the future to report that jobs will run as. Note +that this procedure is disruptive; if @code{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. address@hidden deffn + address@hidden The redirect module, The vixie-time module, The core module, Guile modules address@hidden The redirect module address@hidden redirect module address@hidden modules, redirect + +This module is introduced to a program with the command address@hidden(use-modules (mcron redirect))}. + +This module provides the @code{with-mail-out} function, described +fully in @ref{Guile Syntax}. + address@hidden The vixie-time module, The job-specifier module, The redirect module, Guile modules address@hidden The vixie-time module address@hidden vixie-time module address@hidden modules, vixie-time + +This module is introduced to a program by @code{(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 address@hidden to the core @code{add-job} procedure, or to +the @code{job-specifier} @code{job} procedure. See @ref{Vixie Syntax} +for full details of the allowed format for the time string. + address@hidden procedure} parse-vixie-time time-string +The single argument @var{time-string} should be a string containing a +vixie-style time specification, and the return value is the required +procedure. address@hidden deffn + + address@hidden The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules address@hidden The job-specifier module address@hidden job-specifier module address@hidden modules, job-specifier + +This module is introduced to a program by @code{(use-modules (mcron +job-specifier))}. + +This module provides all the functions available to user's Guile +configuration files, namely @code{range}, @code{next-year-from}, address@hidden, @code{next-month-from}, @code{next-month}, address@hidden, @code{next-day}, @code{next-hour-from}, address@hidden, @code{next-minute-from}, @code{next-minute}, address@hidden, @code{next-second}, + and last but not least, @code{job}. See @ref{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 @code{load}ing the file. + address@hidden The vixie-specification module, , The job-specifier module, Guile modules address@hidden The vixie-specification module address@hidden vixie-specification module address@hidden modules, vixie-specification + +To use this module, put the command @code{(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. + address@hidden procedure} read-vixie-port port . parse-line + +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. + address@hidden should not normally be used, except that if you are +parsing a (deprecated) @code{/etc/crontab} file with a slightly +modified syntax, you may pass the value @var{parse-system-vixie-line} +as the optional argument. + address@hidden deffn + address@hidden procedure} read-vixie-file name . parse-line + +This procedure attempts to open the named file, and if it fails will +return silently. Otherwise, the behaviour is identical to address@hidden above. + address@hidden deffn + +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 address@hidden + address@hidden Index, , Guile modules, Top address@hidden Index + address@hidden cp + address@hidden diff --git a/makefile.am b/makefile.am index 1b27e7a..5d19aa2 100644 --- a/makefile.am +++ b/makefile.am @@ -1,5 +1,6 @@ ## Makefile for the toplevel directory of mcron. ## Copyright (C) 2003 Dale Mellor +## Copyright (C) 2015 Mathieu Lirzin ## # This file is part of GNU mcron. # @@ -31,9 +32,9 @@ CLEANFILES = mcron.c core.scm EXTRA_DIST = makefile.ed mcron.c.template BUGS -info_TEXINFOS = mcron.texinfo +info_TEXINFOS = doc/mcron.texi -dist_man_MANS = mcron.1 +dist_man_MANS = doc/mcron.1 bin_PROGRAMS = mcron mcron_SOURCES = mcron.c @@ -79,6 +80,6 @@ uninstall-hook: # Not part of formal package building, but a rule for manual use to get the # elemental man page. Will only work once the mcron program is installed. -mcron.1 : mcron.c +$(dist_man_MANS): mcron.c $(HELP2MAN) -n 'a program to run tasks at regular (or not) intervals' \ - ./mcron > mcron.1 + ./mcron > $@ diff --git a/mcron.texinfo.in b/mcron.texinfo.in deleted file mode 100644 index bbf8e5b..0000000 --- a/mcron.texinfo.in +++ /dev/null @@ -1,1335 +0,0 @@ -\input texinfo address@hidden %**start of header address@hidden mcron.info address@hidden mcron @VERSION@ address@hidden %**end of header - address@hidden fn cp - address@hidden This manual is for GNU mcron (version @VERSION@), which is a -program for running jobs at scheduled times. - -Copyright @copyright{} 2003, 2005, 2006, 2012, 2014 Dale Mellor - address@hidden -Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, -Version 1.3 or any later version published by the Free Software -Foundation; with no Invariant Sections, no Front-Cover Texts and -no Back-Cover Texts. A copy of the license is included in the -section entitled ``GNU Free Documentation License''. address@hidden quotation address@hidden copying - - address@hidden - address@hidden Individual utilities - address@hidden -* mcron: (mcron). Run jobs at scheduled times. address@hidden direntry - address@hidden ifinfo - - address@hidden address@hidden mcron - Mellor's cron daemon address@hidden Dale Mellor - address@hidden address@hidden 0pt plus 1fill address@hidden @insertcopying - address@hidden titlepage - address@hidden - address@hidden address@hidden Top, Introduction, (dir), (dir) address@hidden mcron - -This file documents the @code{mcron} command (Mellor's cron) for -running jobs at scheduled times. - address@hidden @insertcopying address@hidden ifnottex - address@hidden -* Introduction:: Introducing mcron. -* Simple examples:: How to use mcron 99.9% of the time. -* Syntax:: All the possibilities for configuring cron jobs. -* Invoking:: What happens when you run the mcron command. -* Guile modules:: Incorporating mcron into another Guile program. -* Index:: The complete index. - address@hidden - --- The Detailed Node Listing --- - -Simple examples - -* Guile Simple Examples:: -* Vixie Simple Examples:: - -Full available syntax - -* Guile Syntax:: -* Extended Guile examples:: -* Vixie Syntax:: - -Extended Guile examples - -* AT commands:: -* Every second Sunday:: -* Two hours every day:: -* Missing the first appointment:: -* Penultimate day of every month:: - -Vixie - -* Paul Vixie's copyright:: -* Crontab file:: -* Incompatibilities with old Unices:: - -Detailed invoking - -* Invoking mcron:: -* Invoking cron or crond:: -* Invoking crontab:: -* Behaviour on laptops:: -* Exit codes:: - -Guile modules - -* The core module:: The job list and execution loop. -* The redirect module:: Sending output of jobs to a mail box. -* The vixie-time module:: Parsing vixie-style time specifications. -* The job-specifier module:: All commands for scheme configuration files. -* The vixie-specification module:: Commands for reading vixie-style crontabs. - address@hidden detailmenu address@hidden menu - address@hidden Introduction, Simple examples, Top, Top address@hidden Introducing mcron address@hidden introduction address@hidden mcron -The mcron program represents a complete re-think of the cron concept -originally found in the Berkeley and AT&T unices, and subsequently -rationalized by Paul Vixie. The original idea was to have a daemon -that wakes up every minute, scans a set of files under a special -directory, and determines from those files if any shell commands -should be executed in this minute. - -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. (Changes to user crontabs are signalled -directly to mcron by the crontab program; cron must still scan the -/etc/crontab file once every minute, although use of this file is -highly discouraged and this behaviour can be turned off). - address@hidden advantages of mcron address@hidden @bullet address@hidden -Does not consume CPU resources when not needed. Many cron daemons only -run jobs once an hour, or even just once a day. address@hidden -Can easily allow for finer time-points to be specified, -i.e. seconds. In principle this could be extended to microseconds, but -this is not implemented. address@hidden -Times can be more or less regular. For example, a job that runs -every 17 hours can be specified, or a job that runs on the first -Sunday of every month. address@hidden -Times can be dynamic. Arbitrary Guile (scheme) code can be provided to -compute the next time that a command needs to be run. This could, for -example, take the system load into consideration. address@hidden -Turns out to be easy to provide complete backwards compatibility with -Vixie cron. address@hidden -Each user looks after his own files in his own directory. He can use -more than one to break up complicated cron specifications. address@hidden -Each user can run his own daemon. This removes the need for suid -programs to manipulate the crontabs, and eliminates many security -concerns that surround all existing cron programs. address@hidden -The user can obtain an advance schedule of all the jobs that are due -to run. address@hidden -Vixie cron is implemented in 4500 lines of C code; mcron is 2000 lines -of scheme, despite the fact that it offers many more features and much -more flexibility, and complete compatibility with Vixie cron. address@hidden itemize - -A full discussion of the design and philosophy of mcron can be found -in the white paper at address@hidden://www.gnu.org/software/mcron/design.html}. - - address@hidden Simple examples, Syntax, Introduction, Top address@hidden Simple examples -The vast majority of uses of cron are sublimely simple: run a program -every hour, or every day. With this in mind the design of mcron has -been to allow such simple specifications to be made easily. The -examples show how to create the command descriptions, and subsequently -how to run mcron to make them happen. address@hidden -* Guile Simple Examples:: -* Vixie Simple Examples:: address@hidden menu - address@hidden Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples address@hidden Guile address@hidden guile examples address@hidden examples, guile address@hidden example, run a program every hour -You have an executable @code{my-program} in your home directory, which -you want to run every hour. Create a file @code{job.guile} in -directory @code{~/.config/cron} (this path may be altered by the address@hidden environment variable) with the following -contents - address@hidden -(job '(next-hour) "my-program") address@hidden example - -then run the command @code{mcron}. - -Want the program to run fifteen minutes past the hour, every two -hours? Edit the file to read - address@hidden -(job - '(next-minute-from - (next-hour (range 0 24 2)) - 15) - "my-program") address@hidden example - -and run the command @code{mcron}. - -Or, if you are not comfortable with Scheme, you could use (and see -also the next section) - address@hidden -(job "15 */2 * * *" "my-program") address@hidden example - -and run the @code{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 @code{.config/cron} directory -with the @code{.guile} extension. Alternatively, you can use any file -you want and pass it as an argument to @code{mcron}, or even pipe the -commands into the standard input. - - address@hidden Vixie Simple Examples, , Guile Simple Examples, Simple examples address@hidden Vixie address@hidden examples address@hidden examples, vixie address@hidden vixie examples -You have an executable @code{my-program} in your home directory, which -you want to run every hour. Create a file @code{job.vixie} in directory address@hidden/.cron} with the following contents - address@hidden -0 * * * * my-program address@hidden example - -then run the command @code{mcron}. - address@hidden vixie compatibility address@hidden compatibility -Alternatively (full compatibility with Vixie cron), set your -environment variable @code{EDITOR} to your favorite editor, run address@hidden -e}, put the above line into the edit buffer, save and -exit. For this to work the @code{cron} daemon must be already running -on your system, as root. - address@hidden Syntax, Invoking, Simple examples, Top address@hidden Full available syntax address@hidden -* Guile Syntax:: -* Extended Guile examples:: -* Vixie Syntax:: address@hidden menu address@hidden Guile Syntax, Extended Guile examples, Syntax, Syntax address@hidden Guile Syntax address@hidden Job specification address@hidden guile syntax address@hidden syntax, guile address@hidden job -In Guile-formatted configuration files each command that needs -executing is introduced with the @code{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. - address@hidden time specification, procedure address@hidden procedure time specification -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: - address@hidden next-second-from address@hidden(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). @footnote{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.} - address@hidden next-minute-from address@hidden next-hour-from address@hidden next-day-from address@hidden next-week-from address@hidden next-month-from address@hidden next-year-from -Similarly to @code{next-second-from}, there are also address@hidden, @code{next-hour-from}, @code{next-day-from}, address@hidden, @code{next-month-from}, @code{next-year-from}. - address@hidden range -Furthermore, the optional argument can be fulfilled by the function address@hidden(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 @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}. - address@hidden next-second address@hidden next-minute address@hidden next-hour address@hidden next-day address@hidden next-week address@hidden next-month address@hidden next-year address@hidden time specification, list address@hidden list time specification -If the first argument to the @code{job} function is a list, it is -taken to be program code made up of the functions @code{(next-second -. args)}, @code{(next-minute...)}, etc, where the optional arguments -can be supplied with the @code{(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). - address@hidden time specification address@hidden time specification, string address@hidden string time specification address@hidden time specification, vixie-style address@hidden vixie-style time specification -If the first argument to the @code{job} function is a string, it is -expected to be a Vixie cron-style time specification. See the section -on Vixie syntax for this. - address@hidden job execution address@hidden command execution address@hidden execution -The second argument to the @code{(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. - address@hidden Sending output as e-mail address@hidden email output address@hidden email from guile script address@hidden standard input to commands address@hidden with-mail-out -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. - address@hidden Setting environment variables address@hidden environment variables in scheme address@hidden setting environment variables address@hidden append-environment-mods -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. - - address@hidden Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax address@hidden Extended Guile examples address@hidden examples, extended guile address@hidden extended guile examples -While Guile gives you flexibility to do anything, and the power to -represent complex requirements succinctly, things are not always as -they seem. The following examples illustrate some pitfalls, and -demonstrate how to code around them. - address@hidden -* AT commands:: -* Every second Sunday:: -* Two hours every day:: -* Missing the first appointment:: -* Penultimate day of every month:: address@hidden menu - address@hidden AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples address@hidden Synthesizing ``at'' commands address@hidden at command -The current implementation of mcron does not provide for an at command -(a command-line program that allows the user to specify that a job -runs exactly once at a certain time). This can, however, be achieved. - -Suppose the program @code{my-program} needs to be run at midnight -tonight. A Guile script like the following would work (but a printed -schedule, obtained with the @code{--schedule} option, will show -superfluous entries). - address@hidden -(job '(next-day) - (lambda () (system "my-program") - (kill (getppid) SIGINT))) address@hidden example - address@hidden Every second Sunday, Two hours every day, AT commands, Extended Guile examples address@hidden Every second Sunday address@hidden examples, every second sunday -To run @code{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!). - address@hidden -(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 - (- 14 first-day)))) - (+ next-month (* 24 60 60 second-sunday)))) - "my-program") address@hidden example - - address@hidden Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples address@hidden Two hours every day address@hidden examples, two hours every day address@hidden pitfalls, two hours every day -Surprisingly perhaps, the following will @strong{not} have the desired -effect. - address@hidden -(job '(next-hour-from (next-day) '(1 2)) - "my-program") address@hidden example - -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. - address@hidden -(job '(next-hour '(1 2)) "my-program") address@hidden example - - address@hidden Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples address@hidden Missing the first appointment address@hidden examples, missing the first appointment address@hidden pitfalls, missing the first appointment -The command - address@hidden -(job '(next-hour-from (next-day) '(16)) - "my-program") address@hidden example - -will run @code{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 - address@hidden -(job '(next-hour '(16)) - "my-program") address@hidden example - - address@hidden Penultimate day of every month, , Missing the first appointment, Extended Guile examples address@hidden Penultimate day of every month address@hidden examples, penultimate day of every month -The following will run the @code{my-program} program on the -second-to-last day of every month. - address@hidden -(job '(- (next-month-from (next-month)) (* 48 3600)) - "my-program") address@hidden example - - - address@hidden Vixie Syntax, , Extended Guile examples, Syntax address@hidden Vixie address@hidden syntax, vixie address@hidden vixie syntax address@hidden vixie definition address@hidden vixie compatibility address@hidden compatibility, vixie address@hidden that this section is definitive. If there is a difference in -behaviour between the mcron program and this part of the manual, then -there is a bug in the program. This section is also copied verbatim -from Paul Vixie's documentation for his cron program, and his -copyright notice is duly reproduced below. - -There are three problems with this specification. - address@hidden zero'th day of month address@hidden 0'th day of month -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). - address@hidden thirteenth month of year address@hidden 13th month of year -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). - address@hidden shell address@hidden environment variables, shell address@hidden /etc/passwd -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. - address@hidden -* Paul Vixie's copyright:: -* Crontab file:: -* Incompatibilities with old Unices:: address@hidden menu - - address@hidden Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax address@hidden Paul Vixie's copyright address@hidden copyright, Paul Vixie's address@hidden Paul Vixie's copyright address@hidden -Copyright 1988,1990,1993,1994 by Paul Vixie -All rights reserved - -Distribute 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. address@hidden quotation - - - - address@hidden Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax address@hidden Crontab files address@hidden crontab file address@hidden vixie crontab file -A @code{crontab} file contains instructions to the @code{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 @code{su} as part of a cron command. - address@hidden comments, vixie-style -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, - address@hidden environment setting, vixie-style address@hidden -name = value address@hidden example - -where the spaces around the equal-sign (=) are optional, and any -subsequent non-leading spaces in @code{value} will be part of the -value assigned to @code{name}. The @code{value} string may be placed -in quotes (single or double, but matching) to preserve leading or -trailing blanks. - address@hidden environment variables, SHELL address@hidden environment variables, LOGNAME address@hidden environment variables, HOME address@hidden SHELL environment variable address@hidden LOGNAME environment variable address@hidden HOME environment variable address@hidden /etc/passwd -Several environment variables are set up automatically by the address@hidden 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. - address@hidden environment variables, USER address@hidden USER environment variable address@hidden BSD -(Another note: the LOGNAME variable is sometimes called USER on BSD systems... -on these systems, USER will be set also.) @footnote{mcron has not been -ported to BSD, so these notes are not relevant.} - address@hidden environment variables, MAILTO address@hidden MAILTO environment variable -In addition to LOGNAME, HOME, and SHELL, @code{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 @code{cron} -when the minute, hour, and month of year fields match the current -time, @strong{and} when at least one of the two day fields (day of month, or day of week) -match the current time (see ``Note'' below). @code{cron} examines cron entries once every minute. -The time and date fields are: - address@hidden vixie time specification fields address@hidden fields, vixie time specification address@hidden @columnfractions .2 .5 address@hidden Field @tab Allowed values address@hidden ----- @tab -------------- address@hidden minute @tab 0-59 address@hidden hour @tab 0-23 address@hidden day of month @tab 0-31 address@hidden month @tab 0-12 (or names, see below) address@hidden day of week @tab 0-7 (0 or 7 is Sun, or use names) address@hidden multitable - -A field may be an asterisk (*), which always stands for ``first-last''. - address@hidden ranges in vixie time specifications -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. - address@hidden lists in vixie time specifications -Lists are allowed. A list is a set of numbers (or ranges) -separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''. - address@hidden steps in vixie time specifications -Step values can be used in conjunction with ranges. Following -a range with ``/'' specifies skips of the number's value -through the range. For example, ``0-23/2'' can be used in the hours -field to specify command execution every other hour (the alternative -in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are -also permitted after an asterisk, so if you want to say ``every two -hours'', just use ``*/2''. - address@hidden names in vixie-style time specifications -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. @footnote{Mcron allows any alphabetic -characters after a name, so full names of days or months are also valid.} - address@hidden % character on vixie-style commands address@hidden standard input, vixie-style -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. - address@hidden day specification, vixie-style address@hidden vixie-style day specification -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 address@hidden -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 - address@hidden -# 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" address@hidden example - address@hidden Incompatibilities with old Unices, , Crontab file, Vixie Syntax address@hidden Extensions and incompatibilities address@hidden incompatibilities with old Unices address@hidden extensions, vixie over old Unices -This section lists differences between Paul Vixie's cron and the -olde-worlde BSD and AT&T programs, for the benefit of system -administrators and users who are upgrading all the way. - address@hidden @bullet address@hidden address@hidden day 7 -When specifying day of week, both day 0 and day 7 will be considered Sunday. -BSD and AT&T seem to disagree about this. - address@hidden -Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would -be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY. - address@hidden -Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". - address@hidden -Names of months or days of the week can be specified by name. - address@hidden -Environment variables can be set in the crontab. In BSD or AT&T, the -environment handed to child processes is basically the one from /etc/rc. - address@hidden -Command output is mailed to the crontab owner (BSD can't do this), can be -mailed to a person other than the crontab owner (SysV can't do this), or the -feature can be turned off and no mail will be sent at all (SysV can't do this -either). - address@hidden itemize - - address@hidden Invoking, Guile modules, Syntax, Top address@hidden Detailed invoking address@hidden invoking address@hidden personality address@hidden mcron program address@hidden cron program address@hidden crond program address@hidden crontab program -The program adopts one of three different personalities depending on -the name used to invoke it. In a standard installation, the program is -installed in the system under the names mcron, cron and crontab -(installed SUID). - -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. - address@hidden deprecated, vixie 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. - - - address@hidden -* Invoking mcron:: -* Invoking cron or crond:: -* Invoking crontab:: -* Behaviour on laptops:: -* Exit codes:: address@hidden menu - address@hidden Invoking mcron, Invoking cron or crond, Invoking, Invoking address@hidden Invoking mcron address@hidden invoking mcron address@hidden mcron options address@hidden mcron arguments address@hidden command line, mcron address@hidden mcron command line -Mcron should be run by the user who wants to schedule his jobs. It -may be made a background job using the facilities of the shell. The -basic command is @code{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 configuration directories: these are ~/.cron -(deprecated), the directory indicated by the @code{XDG_CONFIG_HOME} -environment variable, or ~/.config/cron if this variable is not set. -In any 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; ANY OTHER FILES WILL BE IGNORED - specify a file name of ``-'' -and then pipe the files into the standard input if you really want to -read them, possibly using the @code{stdin} option to specify the type -of file. - -The program accepts the following options. - address@hidden @option address@hidden -s count address@hidden --schedule=count address@hidden printout of jobs schedule address@hidden schedule of jobs, listing address@hidden options, schedule address@hidden options, -s address@hidden -s option address@hidden --schedule option -With this option specified no commands are run. Instead, the program -computes the times the commands would be run and prints the -information to the screen, and then immediately exits. - -The count indicates the number of commands to display. - address@hidden daemon option address@hidden options, daemon address@hidden options, -d address@hidden -d option address@hidden --daemon option address@hidden -d address@hidden --daemon -With this option the program will detach itself from the controlling -terminal and run as a daemon process. - address@hidden stdin option address@hidden options, stdin address@hidden options, -i address@hidden -i option address@hidden --stdin option address@hidden standard input, configuring from address@hidden configuring from standard input address@hidden -i (vixie|guile) address@hidden --stdin=(vixie|guile) -This option is used to indicate whether the configuration information -being passed on the standard input is in Vixie format or Guile -format. Guile is the default. - address@hidden -v option address@hidden --version option address@hidden options, -v address@hidden options, version address@hidden -v address@hidden --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - address@hidden -h option address@hidden --help option address@hidden options, -h address@hidden options, --help address@hidden -h address@hidden --help -This causes a short but complete usage message to be displayed on -standard output. - address@hidden table - address@hidden Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking address@hidden Invoking cron or crond address@hidden cron, invokation address@hidden invoking cron address@hidden crond, invokation address@hidden invoking crond address@hidden @CONFIG_SPOOL_DIR@ address@hidden @CONFIG_SOCKET_FILE@ -NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or address@hidden, and @code{crontab} PROGRAMS HAVE BEEN INSTALLED BY THE -SYSTEM ADMINISTRATOR. - -If the program runs by the name of @code{cron} or @code{crond}, then -it will read all the files in @address@hidden@} (which should only -be readable by root) and the file @code{/etc/crontab}, and then -detaches itself from the terminal to live forever as a daemon -process. Additionally, it creates a UNIX socket at address@hidden@address@hidden, 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 @code{--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. - address@hidden @option - address@hidden -v option address@hidden --version option address@hidden options, -v address@hidden options, version address@hidden -v address@hidden --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - address@hidden -h option address@hidden --help option address@hidden options, -h address@hidden options, --help address@hidden -h address@hidden --help -This causes a short but complete usage message to be displayed on -standard output. - address@hidden -s [count] address@hidden --schedule[=count] address@hidden printout of jobs schedule address@hidden schedule of jobs, listing address@hidden options, schedule address@hidden options, -s address@hidden -s option address@hidden --schedule option -With this option specified no commands are run. Instead, the program -computes the times the commands would be run and prints the -information to the screen, and then immediately exits. - -The count, if supplied, indicates the number of commands to -display. The default value is 8. - address@hidden -n option address@hidden --noetc option address@hidden options, -n address@hidden options, --noetc address@hidden -n address@hidden --noetc -This tells cron not to add a job to the system which wakes up every -minute to check for modifications to @code{/etc/crontab}. It is -recommended that this option be used (and further that the address@hidden/etc/crontab} file be taken off the system altogether!) - address@hidden table - address@hidden Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking address@hidden Invoking crontab address@hidden crontab, invoking address@hidden invoking crontab -This program is run by individual users to inspect or modify their -crontab files. If a change is made to the file, then the root daemon -process will be given a kick, and will immediately read the new -configuration. A warning will be issued to standard output if it -appears that a cron daemon is not running. - -The command is used as - address@hidden [-u user] file} - -or - address@hidden [-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). - address@hidden @option - address@hidden -l option address@hidden list option, crontab address@hidden options, -l address@hidden options, --list address@hidden viewing a crontab address@hidden listing a crontab address@hidden -l address@hidden --list -Print the user's crontab file to the standard output, and exit. - address@hidden -r option address@hidden remove option address@hidden options, -r address@hidden options, --remove address@hidden deleting a crontab address@hidden removing a crontab address@hidden -r address@hidden --remove -Delete the user's crontab file, and exit. - address@hidden -e option address@hidden edit option address@hidden options, -e address@hidden options, --edit address@hidden editing a crontab address@hidden creating a crontab address@hidden -e address@hidden --edit -Using the editor specified in the user's VISUAL or EDITOR environment -variables, allow the user to edit his crontab. Once the user exits the -editor, the crontab is checked for parseability, and if it is okay -then it is installed as the user's new crontab and the daemon is -notified that a change has taken place, so that the new file will -become immediately effective. - address@hidden table - - address@hidden Behaviour on laptops, Exit codes, Invoking crontab, Invoking address@hidden Behaviour on laptops address@hidden laptops address@hidden power suspend -While mcron has not been designed to work anachronistically, the behaviour of -mcron when a laptop emerges from a suspended state is well defined, and the -following description explains what happens in this situation. - -When a laptop awakes from a suspended state, all jobs which would have run while -the laptop was suspended will run exactly once immediately (and simultaneously) -when the laptop awakes, and then the next time that those jobs run will be -computed based on the time the laptop was awoken. Any jobs which would not have -run during the suspense period will be unaffected, and will still run at their -proper times. - - address@hidden Exit codes, , Behaviour on laptops, Invoking address@hidden Exit codes address@hidden exit codes address@hidden error conditions address@hidden errors -The following are the status codes returned to the operating system -when the program terminates. - address@hidden @asis address@hidden 0 -No problems. - address@hidden 1 -An attempt has been made to start cron but there is already a address@hidden@ file. If there really is no other cron daemon -running (this does not include invokations of mcron) then you should -remove this file before attempting to run cron. - address@hidden 2 -In parsing a guile configuration file, a @code{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. - address@hidden 3 -In parsing a guile configuration file, a @code{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. - address@hidden 4 -An attempt to run cron has been made by a user who does not have -permission to access the crontabs in @address@hidden These files -should be readable only by root, and the cron daemon must be run as -root. - address@hidden 5 -An attempt to run mcron has been made, but there are no jobs to -schedule! - address@hidden 6 -The system administrator has blocked this user from using crontab with -the files @CONFIG_ALLOW_FILE@ and @address@hidden - address@hidden 7 -Crontab has been run with more than one of the arguments @code{-l}, address@hidden, @code{-e}. These are mutually exclusive options. - address@hidden 8 -Crontab has been run with the -u option by a user other than -root. Only root is allowed to use this option. - address@hidden 9 -An invalid vixie-style time specification has been supplied. - address@hidden 10 -An invalid vixie-style job specification has been supplied. - address@hidden 11 -A bad line has been seen in /etc/crontab. - address@hidden 12 -The last component of the name of the program was not one of address@hidden, @code{cron}, @code{crond} or @code{crontab}. - address@hidden 13 -Either none of the user's configuration directories exist, or there is a problem -reading the files there. The configuration directories are ~/.cron -and the directory pointed to by the @code{XDG_CONFIG_HOME} environment -variable, or ~/.config/cron if this is not set. - address@hidden @item 14 address@hidden There is a problem writing to /var/cron/update. This is probably address@hidden because the crontab program is not installed SUID root, as it should address@hidden be. - address@hidden 15 -Crontab has been run without any arguments at all. There is no default -behaviour in this case. - address@hidden 16 -Cron has been run by a user other than root. - address@hidden table - - - address@hidden Guile modules, Index, Invoking, Top address@hidden Guile modules -Some of the key parts of mcron are implemented as modules so they can -be incorporated into other Guile programs, or even into C-sourced -programs if they are linked against libguile. - -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. - address@hidden -* The core module:: The job list and execution loop. -* The redirect module:: Sending output of jobs to a mail box. -* The vixie-time module:: Parsing vixie-style time specifications. -* The job-specifier module:: All commands for scheme configuration files. -* The vixie-specification module:: Commands for reading vixie-style crontabs. address@hidden menu - address@hidden The core module, The redirect module, Guile modules, Guile modules address@hidden The core module address@hidden guile module address@hidden core module address@hidden modules, core - -This module may be used by including @code{(use-modules (mcron core))} -in a program. The main functions are @code{add-job} and address@hidden, 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. - address@hidden environment -The environment is a set of name-value pairs which is built up -incrementally. Each time the @code{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. - address@hidden procedure} append-environment-mods name value -When a job is run make sure the environment variable @var{name} has -the value @var{value}. address@hidden deffn - address@hidden procedure} clear-environment-mods -This procedure causes all the environment modifiers that have been -specified so far to be forgotten. address@hidden deffn - address@hidden procedure} add-job time-proc action displayable configuration-time configuration-user -This procedure adds a job specification to the list of all jobs to -run. @var{time-proc} should be a procedure taking exactly one argument -which will be a UNIX time. This procedure must compute the next time -that the job should run, and return the result. @var{action} should be -a procedure taking no arguments, and contains the instructions that -actually get executed whenever the job is scheduled to -run. @var{displayable} should be a string, and is only for the use of -humans; it can be anything which identifies or simply gives a clue as -to the purpose or function of this job. @var{configuration-time} is -the time from which the first invokation of this job should be -computed. Finally, @var{configuration-user} should be the passwd entry -for the user under whose personality the job is to run. address@hidden deffn - address@hidden procedure} run-job-loop . fd-list address@hidden file descriptors address@hidden interrupting the mcron loop -This procedure returns only under exceptional circumstances, but -usually loops forever waiting for the next time to arrive when a job -needs to run, running that job, recomputing the next run time, and -then waiting again. However, the wait can be interrupted by data -becoming available for reading on one of the file descriptors in the -fd-list, if supplied. Only in this case will the procedure return to -the calling program, which may then make modifications to the job list -before calling the @code{run-job-loop} procedure again to resume execution of -the mcron core. address@hidden deffn - address@hidden procedure} remove-user-jobs user - -The argument @var{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. address@hidden deffn - address@hidden procedure} get-schedule count address@hidden schedule of jobs -The argument @var{count} should be an integer value giving the number -of time-points in the future to report that jobs will run as. Note -that this procedure is disruptive; if @code{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. address@hidden deffn - address@hidden The redirect module, The vixie-time module, The core module, Guile modules address@hidden The redirect module address@hidden redirect module address@hidden modules, redirect - -This module is introduced to a program with the command address@hidden(use-modules (mcron redirect))}. - -This module provides the @code{with-mail-out} function, described -fully in @ref{Guile Syntax}. - address@hidden The vixie-time module, The job-specifier module, The redirect module, Guile modules address@hidden The vixie-time module address@hidden vixie-time module address@hidden modules, vixie-time - -This module is introduced to a program by @code{(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 address@hidden to the core @code{add-job} procedure, or to -the @code{job-specifier} @code{job} procedure. See @ref{Vixie Syntax} -for full details of the allowed format for the time string. - address@hidden procedure} parse-vixie-time time-string -The single argument @var{time-string} should be a string containing a -vixie-style time specification, and the return value is the required -procedure. address@hidden deffn - - address@hidden The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules address@hidden The job-specifier module address@hidden job-specifier module address@hidden modules, job-specifier - -This module is introduced to a program by @code{(use-modules (mcron -job-specifier))}. - -This module provides all the functions available to user's Guile -configuration files, namely @code{range}, @code{next-year-from}, address@hidden, @code{next-month-from}, @code{next-month}, address@hidden, @code{next-day}, @code{next-hour-from}, address@hidden, @code{next-minute-from}, @code{next-minute}, address@hidden, @code{next-second}, - and last but not least, @code{job}. See @ref{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 @code{load}ing the file. - address@hidden The vixie-specification module, , The job-specifier module, Guile modules address@hidden The vixie-specification module address@hidden vixie-specification module address@hidden modules, vixie-specification - -To use this module, put the command @code{(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. - address@hidden procedure} read-vixie-port port . parse-line - -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. - address@hidden should not normally be used, except that if you are -parsing a (deprecated) @code{/etc/crontab} file with a slightly -modified syntax, you may pass the value @var{parse-system-vixie-line} -as the optional argument. - address@hidden deffn - address@hidden procedure} read-vixie-file name . parse-line - -This procedure attempts to open the named file, and if it fails will -return silently. Otherwise, the behaviour is identical to address@hidden above. - address@hidden deffn - -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 address@hidden - address@hidden Index, , Guile modules, Top address@hidden Index - address@hidden cp - address@hidden -- 2.1.4