From 627e81918e50e7806aace870d1529adf5d75a15d Mon Sep 17 00:00:00 2001 From: dale_mellor Date: Thu, 22 Jan 2004 13:54:21 +0000 Subject: This is the version 1.0.0 release (many changes have occurred without commiting due to disruption to Savannah, including a skip over the 0.99.4 release). --- ChangeLog | 24 + NEWS | 28 +- README | 64 ++- config.scm.in | 7 + configure.ac | 88 +++- crontab.scm | 14 +- environment.scm | 17 +- main.scm | 20 +- mcron-core.scm | 23 +- mcron.texinfo | 1320 ----------------------------------------------- mcron.texinfo.in | 1320 +++++++++++++++++++++++++++++++++++++++++++++++ vixie-specification.scm | 2 +- 12 files changed, 1538 insertions(+), 1389 deletions(-) delete mode 100644 mcron.texinfo create mode 100644 mcron.texinfo.in diff --git a/ChangeLog b/ChangeLog index b6223d3..d501f35 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,27 @@ +2003-12-11 Dale Mellor + + * Modified all auxiliary files to reflect that we are now a GNU + package. + + * Bumped version to 1.0.0. + + +2003-12-07 Dale Mellor + + * configure.ac: Added switches for files and directories used by + mcron: --spool-dir, --socket-file, --allow-file, --deny-file, + --pid-file and --tmp-dir. All the code has been modified to use + these configure options (including the source for the texinfo + manual). + + +2003-12-05 Dale Mellor + + * configure.ac: Added test for guile version >= 1.6.4. + + * bumped version to 0.99.4. + + 2003-08-03 Dale Mellor * Third cut, fully functional, modular, production quality, still diff --git a/NEWS b/NEWS index 654811c..8ee2233 100644 --- a/NEWS +++ b/NEWS @@ -3,7 +3,26 @@ Historic moments in the life of mcron. -*-text-*- Copyright (C) 2003 Dale Mellor See the end for copying conditions. -Please send bug reports to dale_mellor@users.sourceforge.net. +Please send bug reports to bugs-mcron@gnu.org. + + +Friday, 12th December 2003 + Released version 1.0.0 through rdmp.org. No CVS tag has been created. + + +Tuesday, 2nd December 2003 + Mcron is now officially a GNU program. Unfortunately Savannah, the + development environment, has been mauled so an immediate GNU release is not + likely. No CVS tag has been created. + + +Tuesday, 5th August 2003 + Released version 0.99.3. The CVS tag will be release_0-99-3 (no branch). + + +Sunday, 3rd August 2003 + Broken the code into modules (which is not the same as saying the code is + broken ;-) ). Sunday, 20th July 2003 @@ -20,13 +39,14 @@ Sunday, 20th July 2003 Saturday, 5th July 2003 Released version 0.99.1, with installation of cron and crontab disabled by default (suspect problems with Guile internals are preventing these from - working properly). The CVS tag is release_0-99-1 (no branch has been created - for it). + working properly). The CVS tag is release_0-99-1 (no branch has been + created for it). Friday, 4th July 2003 We have been accepted as a Savannah project. A CVS repository and web home - page have been created. We're still waiting for acceptance as a GNU project. + page have been created. We're still waiting for acceptance as a GNU + project. diff --git a/README b/README index ca1c3f0..d2ee900 100644 --- a/README +++ b/README @@ -2,11 +2,11 @@ Copyright (C) 2003 Dale Mellor -*-text-*- See the end for copying conditions. -This is version 0.99.3 of the mcron program (the third 1.0.0 release -candidate), designed and written by Dale Mellor, which replaces and hugely -enhances Vixie cron. It is functionally complete, production quality code (did -you expect less?), but has not received much testing yet. It has only been built -on a GNU/Linux system, and will most likely fail on others (but you never +This is version 1.0.0 of the mcron program, and is the first release as part of +the GNU system. It is designed and written by Dale Mellor, and replaces and +hugely enhances Vixie cron. It is functionally complete, production quality code +(did you expect less?), but has not received much testing yet. It has only been +built on a GNU/Linux system, and will most likely fail on others (but you never know...). @@ -15,8 +15,8 @@ IMPORTANT NOTICES Read the BUGS file. -Do not (yet) install this software on a machine which relies for its functioning -on its current set of crontabs. +Do not (yet) install this software on a machine which relies for its +functioning on its current set of crontabs. The package must be installed by root. @@ -24,41 +24,49 @@ Before installing this package for the first time, it is necessary to terminate any running cron daemons on your system. If your old cron is not Vixie or accurately Vixie compatible (files in /var/cron/tabs*, /var/cron/allow, /var/cron/deny, /etc/crontab, /var/run/cron.pid) then you will need to clear out -all old crontabs and make new ones afresh. +all old crontabs and make new ones afresh - or else look very carefully at the +options you pass to the package configure script, as follows. + +It is often the case that GNU/Linux distributions and other Unices hacked the +cron daemon to use different directories to those above. You can use configure +options --spool-dir, --socket-file, --allow-file, --deny-file, --pid-file and +--tmp-dir to make mcron behave similarly. Note that, with the exception of +tmp-dir, none of these files or directories should be accessible by ordinary +(non-root) users. If your old cron is Vixie, or very similar, mcron should fall right into place -where your old cron was (the binaries cron and crontab will be replaced), and -you should be able to continue to use your existing crontabs without noticing -any changes. Bear in mind that if you use /etc/crontab, then changes to this -file will *not* take immediate effect (this is the 1% incompatibility between -mcron and Vixie cron); you may want to add a comment to this file with a note to -this effect. Alternatively, use the new mcron program, it's better! - -If you don't want to clobber your existing cron executables, you can specify the ---program-prefix option to configure with a prefix ending in a non-alphabetic -character, for example "m.", and then run the programs as m.mcron, m.cron and -m.crontab. +where your old cron was (the binaries cron and crontab will be replaced, but if +your existing system has a binary called crond, you should make this a link +to mcron), and you should be able to continue to use your existing crontabs +without noticing any changes. + +If you don't want to clobber your existing cron executables, you can specify +the --program-prefix option to configure with a prefix ending in a +non-alphabetic character, for example "m.", and then run the programs as +m.mcron, m.cron (or m.crond) and m.crontab. ---------------------------------------------------------------------- See the file INSTALL for generic building and installation instructions. -After installation, read the info file for full instructions for use (type -`info mcron' at the command line). Notes for end users, sysadmins, and -developers who wish to incorporate mcron into their own programs are included -here. +After installation, read the info file for full instructions for use (typing +`info mcron' at the command line should suffice). Notes for end users, +sysadmins, and developers who wish to incorporate mcron into their own programs +are included here. Known bugs are noted in the BUGS file, and features which might be implemented sometime sooner or later are noted in the TODO file. -Please send all other bug reports either via Savannah (preferred) at - https://savannah.nongnu.org/bugs/?func=addbug&group=mcron -or else by electronic mail to: - dale_mellor@users.sourceforge.net +Please send all other bug reports to bugs-mcron@gnu.org. Other mailing lists you +could subscribe to are help-mcron@gnu.org (for help and advice from the +community, including the author) and info-mcron@gnu.org (for news as it +happens). Mcron is free software. See the file COPYING for copying conditions. -The mcron development home page is at http://www.nongnu.org/mcron. +The mcron development home page is at http://www.gnu.org/software/mcron (also +temporarily at http://rdmp.org/mcron), and can be obtained from +ftp://ftp.gnu.org/mcron (or temporarily from ftp://rdmp.org/mcron). diff --git a/config.scm.in b/config.scm.in index 6bd71cb..2ccbd49 100644 --- a/config.scm.in +++ b/config.scm.in @@ -26,3 +26,10 @@ (define-public config-package-string "@PACKAGE_STRING@") (define-public config-package-bugreport "@PACKAGE_BUGREPORT@") (define-public config-sendmail "@SENDMAIL@") + +(define-public config-spool-dir "@CONFIG_SPOOL_DIR@") +(define-public config-socket-file "@CONFIG_SOCKET_FILE@") +(define-public config-allow-file "@CONFIG_ALLOW_FILE@") +(define-public config-deny-file "@CONFIG_DENY_FILE@") +(define-public config-pid-file "@CONFIG_PID_FILE@") +(define-public config-tmp-dir "@CONFIG_TMP_DIR@") diff --git a/configure.ac b/configure.ac index 9b4c2de..6807c39 100644 --- a/configure.ac +++ b/configure.ac @@ -2,7 +2,7 @@ # Process this file with autoconf to produce a configure script. AC_PREREQ(2.57) -AC_INIT(mcron, 0.99.3, dale_mellor@users.sourceforge.net) +AC_INIT(mcron, 1.0.0, dale_mellor@users.sourceforge.net) AM_INIT_AUTOMAKE @@ -21,12 +21,24 @@ fi AC_SUBST(CONFIG_DEBUG) +AC_PROG_AWK +AC_PROG_EGREP AC_PROG_CC GUILE_PROGS GUILE_FLAGS GUILE_SITE_DIR - + + # Checks for programs. + +AC_CHECK_PROGS(SED, sed) +if test "x$ac_cv_prog_SED" = "x"; then + AC_MSG_ERROR(sed not found) +fi +AC_CHECK_PROGS(HEAD, head) +if test "x$ac_cv_prog_HEAD" = "x"; then + AC_MSG_ERROR(head not found) +fi AC_CHECK_PROGS(ED, ed) if test "x$ac_cv_prog_ED" = "x"; then AC_MSG_ERROR(ed not found) @@ -40,7 +52,18 @@ if test "x$ac_cv_prog_CP" = "x"; then AC_MSG_ERROR(cp not found) fi + +# Check the Guile version. +AC_MSG_CHECKING(for guile version >= 1.6.4) +if [$GUILE --version | $HEAD -1 | $AWK '{print $2}' | \ + $EGREP -q '^(1\.(6\.([4-9]|[1-3][^.])|[7-9]|[1-5][^.])|[2-9])']; then + AC_MSG_RESULT(OK) +else + AC_MSG_ERROR([Sorry, Guile 1.6.4 or greater is needed to run mcron]) +fi + + # Now find a sendmail or equivalent. AC_CHECK_PROGS(SENDMAIL, sendmail) @@ -63,11 +86,70 @@ fi SENDMAIL=$ac_cv_prog_SENDMAIL +# Configure the various files that mcron uses at runtime. + +AC_MSG_CHECKING([which spool directory to use]) +AC_ARG_WITH(spool-dir, + AC_HELP_STRING([--with-spool-dir], + [the crontab spool directory (/var/cron/tabs)]), + CONFIG_SPOOL_DIR=$withval, + CONFIG_SPOOL_DIR=[/var/cron/tabs]) +AC_MSG_RESULT($CONFIG_SPOOL_DIR) +AC_SUBST(CONFIG_SPOOL_DIR) + +AC_MSG_CHECKING([name of socket]) +AC_ARG_WITH(socket-file, + AC_HELP_STRING([--with-socket-file], + [unix pathname for cron socket (/var/cron/socket)]), + CONFIG_SOCKET_FILE=$withval, + CONFIG_SOCKET_FILE=[/var/cron/socket]) +AC_MSG_RESULT($CONFIG_SOCKET_FILE) +AC_SUBST(CONFIG_SOCKET_FILE) + +AC_MSG_CHECKING([name of allow file]) +AC_ARG_WITH(allow-file, + AC_HELP_STRING([--with-allow-file], + [the file of allowed users (/var/cron/allow)]), + CONFIG_ALLOW_FILE=$withval, + CONFIG_ALLOW_FILE=[/var/cron/allow]) +AC_MSG_RESULT($CONFIG_ALLOW_FILE) +AC_SUBST(CONFIG_ALLOW_FILE) + +AC_MSG_CHECKING([name of deny file]) +AC_ARG_WITH(deny-file, + AC_HELP_STRING([--with-deny-file], + [the file of barred users (/var/cron/deny)]), + CONFIG_DENY_FILE=$withval, + CONFIG_DENY_FILE=[/var/cron/deny]) +AC_MSG_RESULT($CONFIG_DENY_FILE) +AC_SUBST(CONFIG_DENY_FILE) + +AC_MSG_CHECKING([name of PID file]) +AC_ARG_WITH(pid-file, + AC_HELP_STRING([--with-pid-file], + [the file to record cron's PID (/var/run/cron.pid)]), + CONFIG_PID_FILE=$withval, + CONFIG_PID_FILE=[/var/run/cron.pid]) +AC_MSG_RESULT($CONFIG_PID_FILE) +AC_SUBST(CONFIG_PID_FILE) + +AC_MSG_CHECKING([directory to hold temporary files]) +AC_ARG_WITH(tmp-dir, + AC_HELP_STRING([--with-tmp-dir], + [directory to hold temporary files (/tmp)]), + CONFIG_TMP_DIR=$withval, + CONFIG_TMP_DIR=[/tmp]) +AC_MSG_RESULT($CONFIG_TMP_DIR) +AC_SUBST(CONFIG_TMP_DIR) + + + + # This is to support `make DESTDIR=...' real_program_prefix=`echo $program_prefix | sed s/NONE//` AC_SUBST(real_program_prefix) -AC_CONFIG_FILES(makefile config.scm) +AC_CONFIG_FILES(makefile config.scm mcron.texinfo) AC_OUTPUT diff --git a/crontab.scm b/crontab.scm index 266311a..d347445 100644 --- a/crontab.scm +++ b/crontab.scm @@ -29,8 +29,8 @@ (define (hit-server user-name) (catch #t (lambda () - (let* ((socket (socket AF_UNIX SOCK_STREAM 0))) - (connect socket AF_UNIX "/var/cron/socket") + (let ((socket (socket AF_UNIX SOCK_STREAM 0))) + (connect socket AF_UNIX config-socket-file) (display user-name socket) (close socket))) (lambda (key . args) @@ -65,8 +65,8 @@ ;; If the real user is not allowed to use crontab due to the /var/cron/allow ;; and/or /var/cron/deny files, bomb out now. -(if (or (eq? (in-access-file? "/var/cron/allow" crontab-real-user) #f) - (eq? (in-access-file? "/var/cron/deny" crontab-real-user) #t)) +(if (or (eq? (in-access-file? config-allow-file crontab-real-user) #f) + (eq? (in-access-file? config-deny-file crontab-real-user) #t)) (begin (display "Access denied by system operator.\n") (primitive-exit 6))) @@ -103,7 +103,7 @@ ;; So now we know which crontab file we will be manipulating. -(define crontab-file (string-append "/var/cron/tabs/" crontab-user)) +(define crontab-file (string-append config-spool-dir "/" crontab-user)) @@ -139,7 +139,9 @@ ;; crontab, wake the cron daemon up, and remove the temporary file. ((option-ref options 'edit #f) - (let ((temp-file (string-append "/tmp/crontab." (number->string (getpid))))) + (let ((temp-file (string-append config-tmp-dir + "/crontab." + (number->string (getpid))))) (catch #t (lambda () (copy-file crontab-file temp-file)) (lambda (key . args) (with-output-to-file temp-file noop))) (chown temp-file (getuid) (getgid)) diff --git a/environment.scm b/environment.scm index b340330..82c3a27 100644 --- a/environment.scm +++ b/environment.scm @@ -24,8 +24,8 @@ ;; and represents the cumulated environment settings in a configuration ;; file. When a job definition is seen in a configuration file, the ;; current-environment-mods are copied into the internal job description, and -;; when the job actually runs these environment modifications are applied to the -;; UNIX environment in which the job runs. +;; when the job actually runs these environment modifications are applied to +;; the UNIX environment in which the job runs. @@ -76,8 +76,8 @@ -;; Each time a job is added to the system, we take a snapshot of the current set -;; of environment modifiers. +;; Each time a job is added to the system, we take a snapshot of the current +;; set of environment modifiers. (define (get-current-environment-mods-copy) (list-copy current-environment-mods)) @@ -93,10 +93,11 @@ -;; Procedure to add another environment setting to the alist above. This is used -;; both implicitly by the Vixie parser, and can be used directly by users in -;; scheme configuration files. The return value is purely for the convenience of -;; the parse-vixie-environment in the vixie-specification module (yuk). +;; Procedure to add another environment setting to the alist above. This is +;; used both implicitly by the Vixie parser, and can be used directly by users +;; in scheme configuration files. The return value is purely for the +;; convenience of the parse-vixie-environment in the vixie-specification module +;; (yuk). (define (append-environment-mods name value) (set! current-environment-mods (append current-environment-mods diff --git a/main.scm b/main.scm index 94cb004..0795324 100644 --- a/main.scm +++ b/main.scm @@ -162,8 +162,8 @@ Report bugs to " config-package-bugreport ".\n ;; running. (define (delete-run-file) - (catch #t (lambda () (delete-file "/var/run/cron.pid") - (delete-file "/var/cron/socket")) + (catch #t (lambda () (delete-file config-pid-file) + (delete-file config-socket-file)) noop) (quit)) @@ -187,14 +187,14 @@ Report bugs to " config-package-bugreport ".\n (display "This program must be run by the root user (and should ") (display "have been installed as such).\n") (primitive-exit 16))) - (if (access? "/var/run/cron.pid" F_OK) + (if (access? config-pid-file F_OK) (begin (display "A cron daemon is already running.\n") (display " (If you are sure this is not true, remove the file\n") - (display " /var/run/cron.pid.)\n") + (display " " config-pid-file ".)\n") (primitive-exit 1))) (if (not (option-ref options 'schedule #f)) - (with-output-to-file "/var/run/cron.pid" noop)) + (with-output-to-file config-pid-file noop)) (setenv "MAILTO" #f) (c-set-cron-signals))) @@ -294,12 +294,12 @@ Report bugs to " config-package-bugreport ".\n (define (process-files-in-system-directory) (catch #t (lambda () - (let ((directory (opendir "/var/cron/tabs"))) + (let ((directory (opendir config-spool-dir))) (do ((file-name (readdir directory) (readdir directory))) ((eof-object? file-name)) (and-let* ((user (valid-user file-name))) (set-configuration-user user) - (read-vixie-file (string-append "/var/cron/tabs/" + (read-vixie-file (string-append config-spool-dir file-name)))))) (lambda (key . args) (display "You do not have permission to access the system crontabs.\n") @@ -366,7 +366,7 @@ option.\n") (quit)) (setsid) (if (eq? command-type 'cron) - (with-output-to-file "/var/run/cron.pid" + (with-output-to-file config-pid-file (lambda () (display (getpid)) (newline)))))) @@ -380,7 +380,7 @@ option.\n") (if (eq? command-type 'cron) (let ((socket (socket AF_UNIX SOCK_STREAM 0))) - (bind socket AF_UNIX "/var/cron/socket") + (bind socket AF_UNIX config-socket-file) (listen socket 5) (set! fd-list (list socket)))) @@ -406,7 +406,7 @@ option.\n") (let ((user (getpw user-name))) (remove-user-jobs user) (set-configuration-user user) - (read-vixie-file (string-append "/var/cron/tabs/" user-name)))))) + (read-vixie-file (string-append config-spool-dir "/" user-name)))))) diff --git a/mcron-core.scm b/mcron-core.scm index 90e1da9..0aaacc6 100644 --- a/mcron-core.scm +++ b/mcron-core.scm @@ -40,10 +40,9 @@ ;; ;; (vector user next-time-function action environment displayable next-time) ;; -;; where action may be a string (indicating a shell command) or a list -;; (indicating scheme code) or a procedure, and the environment is an alist of +;; where action must be a procedure, and the environment is an alist of ;; modifications that need making to the UNIX environment before the action is -;; run. The next-time elements is the only one that is modified during the +;; run. The next-time element is the only one that is modified during the ;; running of a cron process (i.e. all the others are set once and for all at ;; configuration time). ;; @@ -158,16 +157,16 @@ -;; If the user has requested a schedule of jobs that will run, we provide the -;; information here and then get out. +;; Create a string containing a textual list of the next count jobs to run. ;; -;; Start by determining the number of time points in the future that output is -;; required for. This may be provided on the command line as a parameter to the -;; --schedule option, or else we assume a default of 8. Having determined this -;; count we enter a loop of displaying the next set of jobs to run, artificially +;; Enter a loop of displaying the next set of jobs to run, artificially ;; forwarding the time to the next time point (instead of waiting for it to ;; occur as we would do in a normal run of mcron), and recurse around the loop ;; count times. +;; +;; Note that this has the effect of mutating the job timings. Thus the program +;; must exit after calling this function; the internal data state will be left +;; unusable. (define (get-schedule count) (with-output-to-string @@ -219,6 +218,12 @@ ;; ones to run (may be more than one). Set an alarm and go to sleep. When we ;; wake, run the jobs and reap any children (old jobs) that have ;; completed. Repeat ad infinitum. +;; +;; Note that, if we wake ahead of time, it can only mean that a signal has been +;; sent by a crontab job to tell us to re-read a crontab file. In this case we +;; break out of the loop here, and let the main procedure deal with the +;; situation (it will eventually re-call this function, thus maintaining the +;; loop). (define (run-job-loop . fd-list) diff --git a/mcron.texinfo b/mcron.texinfo deleted file mode 100644 index 1eef0e7..0000000 --- a/mcron.texinfo +++ /dev/null @@ -1,1320 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename mcron.info -@settitle mcron 1.0.0 -@c %**end of header - -@syncodeindex fn cp - -@copying -Copyright (C) 2003 Dale Mellor -This is free software. See the source files for the terms of the -copyright. - -@ignore -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Foundation. -@end ignore -@end copying - - -@ifinfo - -@dircategory Individual utilities - -@direntry -* mcron: (mcron). Run jobs at scheduled times. -@end direntry - -@end ifinfo - - -@titlepage -@title mcron - Mellor's cron daemon -@author Dale Mellor - -@page -@vskip 0pt plus 1fill -@c @insertcopying - -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top mcron - -This file documents the @code{mcron} command (Mellor's cron) for -running jobs at scheduled times. - -@c @insertcopying -@end ifnottex - -@menu -* 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. - -@detailmenu - --- 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 - -* Running mcron:: -* Running cron or crond:: -* Running crontab:: -* 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. - -@end detailmenu -@end menu - -@node Introduction, Simple examples, Top, Top -@chapter Introducing mcron -@cindex introduction -@cindex 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. - -@cindex advantages of mcron -@itemize @bullet -@item -Does not consume CPU resources when not needed. Many cron daemons only -run jobs once an hour, or even just once a day. -@item -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. -@item -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. -@item -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. -@item -Turns out to be easy to provide complete backwards compatibility with -Vixie cron. -@item -Each user looks after his own files in his own directory. He can use -more than one to break up complicated cron specifications. -@item -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. -@item -The user can obtain an advance schedule of all the jobs that are due -to run. -@item -Vixie cron is implemented in 4500 lines of C code; mcron is 1500 lines -of scheme, despite the fact that it offers many more features and much -more flexibility, and complete compatibility with Vixie cron. -@end itemize - -A full discussion of the design and philosophy of mcron can be found -in the white paper at http://.../mcron.html [FIXME]. - - -@node Simple examples, Syntax, Introduction, Top -@chapter 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. -@menu -* Guile Simple Examples:: -* Vixie Simple Examples:: -@end menu - -@node Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples -@section Guile -@cindex guile examples -@cindex examples, guile -@cindex 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{~/.cron} with the following contents - -@example -(job '(next-hour) "my-program") -@end 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 - -@example -(job - '(next-minute-from - (next-hour (range 0 24 2)) - 15) - "my-program") -@end example - -and run the command @code{mcron}. - -Or, if you are not comfortable with Scheme, you could use (and see -also the next section) - -@example -(job "15 */2 * * *" "my-program") -@end 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{.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. - - -@node Vixie Simple Examples, , Guile Simple Examples, Simple examples -@section Vixie -@cindex examples -@cindex examples, vixie -@cindex 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 -@code{~/.cron} with the following contents - -@example -0 * * * * my-program -@end example - -then run the command @code{mcron}. - -@cindex vixie compatibility -@cindex compatibility -Alternatively (full compatibility with Vixie cron), set your -environment variable @code{EDITOR} to your favorite editor, run -@code{crontab -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, by root. - -@node Syntax, Invoking, Simple examples, Top -@chapter Full available syntax -@menu -* Guile Syntax:: -* Extended Guile examples:: -* Vixie Syntax:: -@end menu -@node Guile Syntax, Extended Guile examples, Syntax, Syntax -@section Guile Syntax -@subsection Job specification -@cindex guile syntax -@cindex syntax, guile -@findex 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. - -@cindex time specification, procedure -@cindex 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: - -@findex next-second-from -@code{(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.} - -@findex next-minute-from -@findex next-hour-from -@findex next-day-from -@findex next-week-from -@findex next-month-from -@findex next-year-from -Similarly to @code{next-second-from}, there are also -@code{next-minute-from}, @code{next-hour-from}, @code{next-day-from}, -@code{next-week-from}, @code{next-month-from}, @code{next-year-from}. - -@findex range -Furthermore, the optional argument can be fulfilled by the function -@code{(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)}. - -@findex next-second -@findex next-minute -@findex next-hour -@findex next-day -@findex next-week -@findex next-month -@findex next-year -@cindex time specification, list -@cindex 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). - -@cindex time specification -@cindex time specification, string -@cindex string time specification -@cindex time specification, vixie-style -@cindex 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. - -@cindex job execution -@cindex command execution -@cindex 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. - -@subsection Sending output as e-mail -@cindex email output -@cindex email from guile script -@cindex standard input to commands -@findex 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. - -@subsection Setting environment variables -@cindex environment variables in scheme -@cindex setting environment variables -@findex 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. - - -@node Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax -@section Extended Guile examples -@cindex examples, extended guile -@cindex 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. - -@menu -* AT commands:: -* Every second Sunday:: -* Two hours every day:: -* Missing the first appointment:: -* Penultimate day of every month:: -@end menu - -@node AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples -@subsection Synthesizing ``at'' commands -@cindex 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 should work. FIXME: TEST -THIS EXAMPLE. - -@example -(define my-program-flag #t) - -(job (lambda (current-time) - (if my-program-flag - (begin - (set! my-program-flag #f) - (next-day-from current-time)) - 99999999)) - (lambda () (system "my-program") - (kill (getppid)))) -@end example - -@node Every second Sunday, Two hours every day, AT commands, Extended Guile examples -@subsection Every second Sunday -@cindex 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!). FIXME: TEST THIS EXAMPLE. - -@example -(job (lambda (current-time) - (let* ((next-month (next-month-from current-time)) - (first-day (tm:wday (localtime next-month))) - (second-sunday (if (eqv? first-day 0) - 8 - (- 15 first-day)))) - (+ next-month (* 24 60 60 second-sunday)))) - "my-program") -@end example - - -@node Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples -@subsection Two hours every day -@cindex examples, two hours every day -@cindex pitfalls, two hours every day -Surprisingly perhaps, the following will @strong{not} have the desired -effect. - -@example -(job '(next-hour-from (next-day) '(1 2)) - "my-program") -@end 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. - -@example -(job '(next-hour '(1 2)) "my-program") -@end example - - -@node Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples -@subsection Missing the first appointment -@cindex examples, missing the first appointment -@cindex pitfalls, missing the first appointment -The command - -@example -(job '(next-hour-from (next-day) '(16)) - "my-program") -@end 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 - -@example -(job '(next-hour '(16)) - "my-program") -@end example - - -@node Penultimate day of every month, , Missing the first appointment, Extended Guile examples -@subsection Penultimate day of every month -@cindex examples, penultimate day of every month -The following will run the @code{my-program} program on the -second-to-last day of every month. - -@example -(job '(- (next-month-from (next-month)) (* 48 3600)) - "my-program") -@end example - - - -@node Vixie Syntax, , Extended Guile examples, Syntax -@section Vixie -@cindex syntax, vixie -@cindex vixie syntax -@cindex vixie definition -@cindex vixie compatibility -@cindex compatibility, vixie -@emph{NOTE} 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. - -@cindex zero'th day of month -@cindex 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). - -@cindex thirteenth month of year -@cindex 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). - -@cindex shell -@cindex environment variables, shell -@cindex /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. - -@menu -* Paul Vixie's copyright:: -* Crontab file:: -* Incompatibilities with old Unices:: -@end menu - - -@node Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax -@subsection Paul Vixie's copyright -@cindex copyright, Paul Vixie's -@cindex Paul Vixie's copyright -@quotation -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. -@end quotation - - - - -@node Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax -@subsection Crontab files. -@cindex crontab file -@cindex 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. - -@cindex 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, - -@cindex environment setting, vixie-style -@example -name = value -@end 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. - -@cindex environment variables, SHELL -@cindex environment variables, LOGNAME -@cindex environment variables, HOME -@cindex SHELL environment variable -@cindex LOGNAME environment variable -@cindex HOME environment variable -@cindex /etc/passwd -Several environment variables are set up automatically by the -@code{cron} daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are -set from the /etc/passwd line of the crontab's owner. HOME and SHELL -may be overridden by settings in the crontab; LOGNAME may not. - -@cindex environment variables, USER -@cindex USER environment variable -@cindex 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.} - -@cindex environment variables, MAILTO -@cindex 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: - -@cindex vixie time specification fields -@cindex fields, vixie time specification -@multitable @columnfractions .2 .5 -@item Field @tab Allowed values -@item ----- @tab -------------- -@item minute @tab 0-59 -@item hour @tab 0-23 -@item day of month @tab 0-31 -@item month @tab 0-12 (or names, see below) -@item day of week @tab 0-7 (0 or 7 is Sun, or use names) -@end multitable - -A field may be an asterisk (*), which always stands for ``first-last''. - -@cindex 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. - -@cindex 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''. - -@cindex 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''. - -@cindex 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.} - -@cindex % character on vixie-style commands -@cindex 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. - -@cindex day specification, vixie-style -@cindex 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 -@emph{either} -field matches the current time. For example, - -``30 4 1,15 * 5'' - -would cause a command to be run at 4:30 am on the 1st and 15th of each -month, plus every Friday. - -EXAMPLE CRON FILE - -@example -# 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" -@end example - -@node Incompatibilities with old Unices, , Crontab file, Vixie Syntax -@subsection Extensions and incompatibilities. -@cindex incompatibilities with old Unices -@cindex 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. - -@itemize @bullet -@item -@cindex 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. - -@item -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. - -@item -Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". - -@item -Names of months or days of the week can be specified by name. - -@item -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. - -@item -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). - -@end itemize - - -@node Invoking, Guile modules, Syntax, Top -@chapter Detailed invoking -@cindex invoking -@cindex personality -@cindex mcron program -@cindex cron program -@cindex crond program -@cindex 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. - -@cindex 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. - - - -@menu -* Running mcron:: -* Running cron or crond:: -* Running crontab:: -* Exit codes:: -@end menu - -@node Running mcron, Running cron or crond, Invoking, Invoking -@section Running mcron -@cindex invoking mcron -@cindex mcron options -@cindex mcron arguments -@cindex command line, mcron -@cindex 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 directory. In either case, files which -end in the extension .vixie or .vix will be assumed to contain -Vixie-style crontabs, and files ending .guile or .gle will be assumed -to contain scheme code and will be executed as such. - -The program accepts the following options. - -@table @option -@item -s [count] -@itemx --schedule[=count] -@cindex printout of jobs schedule -@cindex schedule of jobs, listing -@cindex options, schedule -@cindex options, -s -@cindex -s option -@cindex --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. - -@cindex daemon option -@cindex options, daemon -@cindex options, -d -@cindex -d option -@cindex --daemon option -@item -d -@itemx --daemon -With this option the program will detach itself from the controlling -terminal and run as a daemon process. - -@cindex stdin option -@cindex options, stdin -@cindex options, -i -@cindex -i option -@cindex --stdin option -@cindex standard input, configuring from -@cindex configuring from standard input -@item -i (vixie|guile) -@itemx --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. - -@cindex -v option -@cindex --version option -@cindex options, -v -@cindex options, version -@item -v -@itemx --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - -@cindex -h option -@cindex --help option -@cindex options, -h -@cindex options, --help -@item -h -@itemx --help -This causes a short but complete usage message to be displayed on -standard output. - -@end table - -@node Running cron or crond, Running crontab, Running mcron, Invoking -@section Running cron or crond -@cindex cron, invokation -@cindex running cron -@cindex crond, invokation -@cindex running crond -@cindex /var/cron/tabs -@cindex /var/run/cron.pid -If the program runs by the name of @code{cron} or @code{crond}, then -it will read all the files in @code{/var/cron/tabs} (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 -@code{/var/cron/socket}, and listens for messages sent to that socket -consisting of a user name whose crontabs have been changed. In this -case, the program will re-read that user's crontab. This is for -correct functioning with the crontab program. - -Further, if the @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. - -@table @option - -@cindex -v option -@cindex --version option -@cindex options, -v -@cindex options, version -@item -v -@itemx --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - -@cindex -h option -@cindex --help option -@cindex options, -h -@cindex options, --help -@item -h -@itemx --help -This causes a short but complete usage message to be displayed on -standard output. - -@item -s [count] -@itemx --schedule[=count] -@cindex printout of jobs schedule -@cindex schedule of jobs, listing -@cindex options, schedule -@cindex options, -s -@cindex -s option -@cindex --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. - -@cindex -n option -@cindex --noetc option -@cindex options, -n -@cindex options, --noetc -@item -n -@itemx --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 -@code{/etc/crontab} file be taken off the system altogether!) - -@end table - -@node Running crontab, Exit codes, Running cron or crond, Invoking -@section Running crontab -@cindex crontab, invoking -@cindex running 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 - -@code{crontab [-u user] file} - -or - -@code{crontab [-u user] ( -l | -e | -r )} - -Only the root user can use the -u option, to specify the manipulation -of another user's crontab file. In the first instance, the entire -crontab file of the user is replaced with the contents of the -specified file, or standard input if the file is ``-''. - -In the latter case, the program behaves according to which of the -(mutually exclusive) options was given (note that the long options are -an mcron extension). - -@table @option - -@cindex -l option -@cindex list option, crontab -@cindex options, -l -@cindex options, --list -@cindex viewing a crontab -@cindex listing a crontab -@item -l -@itemx --list -Print the user's crontab file to the standard output, and exit. - -@cindex -r option -@cindex remove option -@cindex options, -r -@cindex options, --remove -@cindex deleting a crontab -@cindex removing a crontab -@item -r -@item --remove -Delete the user's crontab file, and exit. - -@cindex -e option -@cindex edit option -@cindex options, -e -@cindex options, --edit -@cindex editing a crontab -@cindex creating a crontab -@item -e -@item --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. - -@end table - - - -@node Exit codes, , Running crontab, Invoking -@section Exit codes -@cindex exit codes -@cindex error conditions -@cindex errors -The following are the status codes returned to the operating system -when the program terminates. - -@table @asis -@item 0 -No problems. - -@item 1 -An attempt has been made to start cron but there is already a -/var/run/cron.pid 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. - -@item 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. - -@item 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. - -@item 4 -An attempt to run cron has been made by a user who does not have -permission to access the crontabs in /var/cron/tabs. These files -should be readable only by root, and the cron daemon must be run as -root. - -@item 5 -An attempt to run mcron has been made, but there are no jobs to -schedule! - -@item 6 -The system administrator has blocked this user from using crontab with -the files /var/cron/allow and /var/cron/deny. - -@item 7 -Crontab has been run with more than one of the arguments @code{-l}, -@code{-r}, @code{-e}. These are mutually exclusive options. - -@item 8 -Crontab has been run with the -u option by a user other than -root. Only root is allowed to use this option. - -@item 9 -An invalid vixie-style time specification has been supplied. - -@item 10 -An invalid vixie-style job specification has been supplied. - -@item 11 -A bad line has been seen in /etc/crontab. - -@item 12 -The last component of the name of the program was not one of -@code{mcron}, @code{cron}, @code{crond} or @code{crontab}. - -@item 13 -Either the ~/.cron directory does not exist, or there is a problem -reading the files there. - -@item 14 -There is a problem writing to /var/cron/update. This is probably -because the crontab program is not installed SUID root, as it should -be. - -@item 15 -Crontab has been run without any arguments at all. There is no default -behaviour in this case. - -@item 16 -Cron has been run by a user other than root. - -@end table - - - -@node Guile modules, Index, Invoking, Top -@chapter 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. - -@menu -* 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. -@end menu - -@node The core module, The redirect module, Guile modules, Guile modules -@section The core module -@cindex guile module -@cindex core module -@cindex 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 -@code{run-job-loop}, which allow a program to create a list of job -specifications to run, and then to initiate the wait-run-wait loop -firing the jobs off at the requisite times. However, before they are -introduced two functions which manipulate the environment that takes -effect when a job runs are defined. - -@cindex 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. - -@deffn{Scheme procedure} append-environment-mods name value -When a job is run make sure the environment variable @var{name} has -the value @var{value}. -@end deffn - -@deffn{Scheme procedure} clear-environment-mods -This procedure causes all the environment modifiers that have been -specified so far to be forgotten. -@end deffn - -@deffn{Scheme 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. -@end deffn - -@deffn{Scheme procedure} run-job-loop . fd-list -@cindex file descriptors -@cindex 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. -@end deffn - -@deffn{Scheme 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. -@end deffn - -@deffn{Scheme procedure} get-schedule count -@cindex 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. -@end deffn - -@node The redirect module, The vixie-time module, The core module, Guile modules -@section The redirect module -@cindex redirect module -@cindex modules, redirect - -This module is introduced to a program with the command -@code{(use-modules (mcron redirect))}. - -This module provides the @code{with-mail-out} function, described -fully in @ref{Guile Syntax}. - -@node The vixie-time module, The job-specifier module, The redirect module, Guile modules -@section The vixie-time module -@cindex vixie-time module -@cindex 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 -@code{next-time-function} 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. - -@deffn{Scheme 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. -@end deffn - - -@node The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules -@section The job-specifier module -@cindex job-specifier module -@cindex 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}, -@code{next-year}, @code{next-month-from}, @code{next-month}, -@code{next-day-from}, @code{next-day}, @code{next-hour-from}, -@code{next-hour}, @code{next-minute-from}, @code{next-minute}, -@code{next-second-from}, @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. - -@node The vixie-specification module, , The job-specifier module, Guile modules -@section The vixie-specification module -@cindex vixie-specification module -@cindex 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. - -@deffn{Scheme 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. - -@var{parse-line} 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. - -@end deffn - -@deffn{Scheme 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 -@code{read-vixie-port} above. - -@end 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 -@code{read-vixie-file}. - -@node Index, , Guile modules, Top -@unnumbered Index - -@printindex cp - -@bye diff --git a/mcron.texinfo.in b/mcron.texinfo.in new file mode 100644 index 0000000..41c4b73 --- /dev/null +++ b/mcron.texinfo.in @@ -0,0 +1,1320 @@ +\input texinfo +@c %**start of header +@setfilename mcron.info +@settitle mcron 1.0.0 +@c %**end of header + +@syncodeindex fn cp + +@copying +Copyright (C) 2003 Dale Mellor +This is free software. See the source files for the terms of the +copyright. + +@ignore +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ignore +@end copying + + +@ifinfo + +@dircategory Individual utilities + +@direntry +* mcron: (mcron). Run jobs at scheduled times. +@end direntry + +@end ifinfo + + +@titlepage +@title mcron - Mellor's cron daemon +@author Dale Mellor + +@page +@vskip 0pt plus 1fill +@c @insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top mcron + +This file documents the @code{mcron} command (Mellor's cron) for +running jobs at scheduled times. + +@c @insertcopying +@end ifnottex + +@menu +* 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. + +@detailmenu + --- 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 + +* Running mcron:: +* Running cron or crond:: +* Running crontab:: +* 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. + +@end detailmenu +@end menu + +@node Introduction, Simple examples, Top, Top +@chapter Introducing mcron +@cindex introduction +@cindex 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. + +@cindex advantages of mcron +@itemize @bullet +@item +Does not consume CPU resources when not needed. Many cron daemons only +run jobs once an hour, or even just once a day. +@item +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. +@item +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. +@item +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. +@item +Turns out to be easy to provide complete backwards compatibility with +Vixie cron. +@item +Each user looks after his own files in his own directory. He can use +more than one to break up complicated cron specifications. +@item +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. +@item +The user can obtain an advance schedule of all the jobs that are due +to run. +@item +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. +@end itemize + +A full discussion of the design and philosophy of mcron can be found +in the white paper at http://rdmp.org:20202/mcron.html. + + +@node Simple examples, Syntax, Introduction, Top +@chapter 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. +@menu +* Guile Simple Examples:: +* Vixie Simple Examples:: +@end menu + +@node Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples +@section Guile +@cindex guile examples +@cindex examples, guile +@cindex 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{~/.cron} with the following contents + +@example +(job '(next-hour) "my-program") +@end 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 + +@example +(job + '(next-minute-from + (next-hour (range 0 24 2)) + 15) + "my-program") +@end example + +and run the command @code{mcron}. + +Or, if you are not comfortable with Scheme, you could use (and see +also the next section) + +@example +(job "15 */2 * * *" "my-program") +@end 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{.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. + + +@node Vixie Simple Examples, , Guile Simple Examples, Simple examples +@section Vixie +@cindex examples +@cindex examples, vixie +@cindex 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 +@code{~/.cron} with the following contents + +@example +0 * * * * my-program +@end example + +then run the command @code{mcron}. + +@cindex vixie compatibility +@cindex compatibility +Alternatively (full compatibility with Vixie cron), set your +environment variable @code{EDITOR} to your favorite editor, run +@code{crontab -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, by root. + +@node Syntax, Invoking, Simple examples, Top +@chapter Full available syntax +@menu +* Guile Syntax:: +* Extended Guile examples:: +* Vixie Syntax:: +@end menu +@node Guile Syntax, Extended Guile examples, Syntax, Syntax +@section Guile Syntax +@subsection Job specification +@cindex guile syntax +@cindex syntax, guile +@findex 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. + +@cindex time specification, procedure +@cindex 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: + +@findex next-second-from +@code{(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.} + +@findex next-minute-from +@findex next-hour-from +@findex next-day-from +@findex next-week-from +@findex next-month-from +@findex next-year-from +Similarly to @code{next-second-from}, there are also +@code{next-minute-from}, @code{next-hour-from}, @code{next-day-from}, +@code{next-week-from}, @code{next-month-from}, @code{next-year-from}. + +@findex range +Furthermore, the optional argument can be fulfilled by the function +@code{(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)}. + +@findex next-second +@findex next-minute +@findex next-hour +@findex next-day +@findex next-week +@findex next-month +@findex next-year +@cindex time specification, list +@cindex 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). + +@cindex time specification +@cindex time specification, string +@cindex string time specification +@cindex time specification, vixie-style +@cindex 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. + +@cindex job execution +@cindex command execution +@cindex 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. + +@subsection Sending output as e-mail +@cindex email output +@cindex email from guile script +@cindex standard input to commands +@findex 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. + +@subsection Setting environment variables +@cindex environment variables in scheme +@cindex setting environment variables +@findex 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. + + +@node Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax +@section Extended Guile examples +@cindex examples, extended guile +@cindex 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. + +@menu +* AT commands:: +* Every second Sunday:: +* Two hours every day:: +* Missing the first appointment:: +* Penultimate day of every month:: +@end menu + +@node AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples +@subsection Synthesizing ``at'' commands +@cindex 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 should work. FIXME: TEST +THIS EXAMPLE. + +@example +(define my-program-flag #t) + +(job (lambda (current-time) + (if my-program-flag + (begin + (set! my-program-flag #f) + (next-day-from current-time)) + 99999999)) + (lambda () (system "my-program") + (kill (getppid)))) +@end example + +@node Every second Sunday, Two hours every day, AT commands, Extended Guile examples +@subsection Every second Sunday +@cindex 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!). FIXME: TEST THIS EXAMPLE. + +@example +(job (lambda (current-time) + (let* ((next-month (next-month-from current-time)) + (first-day (tm:wday (localtime next-month))) + (second-sunday (if (eqv? first-day 0) + 8 + (- 15 first-day)))) + (+ next-month (* 24 60 60 second-sunday)))) + "my-program") +@end example + + +@node Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples +@subsection Two hours every day +@cindex examples, two hours every day +@cindex pitfalls, two hours every day +Surprisingly perhaps, the following will @strong{not} have the desired +effect. + +@example +(job '(next-hour-from (next-day) '(1 2)) + "my-program") +@end 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. + +@example +(job '(next-hour '(1 2)) "my-program") +@end example + + +@node Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples +@subsection Missing the first appointment +@cindex examples, missing the first appointment +@cindex pitfalls, missing the first appointment +The command + +@example +(job '(next-hour-from (next-day) '(16)) + "my-program") +@end 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 + +@example +(job '(next-hour '(16)) + "my-program") +@end example + + +@node Penultimate day of every month, , Missing the first appointment, Extended Guile examples +@subsection Penultimate day of every month +@cindex examples, penultimate day of every month +The following will run the @code{my-program} program on the +second-to-last day of every month. + +@example +(job '(- (next-month-from (next-month)) (* 48 3600)) + "my-program") +@end example + + + +@node Vixie Syntax, , Extended Guile examples, Syntax +@section Vixie +@cindex syntax, vixie +@cindex vixie syntax +@cindex vixie definition +@cindex vixie compatibility +@cindex compatibility, vixie +@emph{NOTE} 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. + +@cindex zero'th day of month +@cindex 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). + +@cindex thirteenth month of year +@cindex 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). + +@cindex shell +@cindex environment variables, shell +@cindex /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. + +@menu +* Paul Vixie's copyright:: +* Crontab file:: +* Incompatibilities with old Unices:: +@end menu + + +@node Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax +@subsection Paul Vixie's copyright +@cindex copyright, Paul Vixie's +@cindex Paul Vixie's copyright +@quotation +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. +@end quotation + + + + +@node Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax +@subsection Crontab files. +@cindex crontab file +@cindex 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. + +@cindex 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, + +@cindex environment setting, vixie-style +@example +name = value +@end 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. + +@cindex environment variables, SHELL +@cindex environment variables, LOGNAME +@cindex environment variables, HOME +@cindex SHELL environment variable +@cindex LOGNAME environment variable +@cindex HOME environment variable +@cindex /etc/passwd +Several environment variables are set up automatically by the +@code{cron} daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are +set from the /etc/passwd line of the crontab's owner. HOME and SHELL +may be overridden by settings in the crontab; LOGNAME may not. + +@cindex environment variables, USER +@cindex USER environment variable +@cindex 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.} + +@cindex environment variables, MAILTO +@cindex 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: + +@cindex vixie time specification fields +@cindex fields, vixie time specification +@multitable @columnfractions .2 .5 +@item Field @tab Allowed values +@item ----- @tab -------------- +@item minute @tab 0-59 +@item hour @tab 0-23 +@item day of month @tab 0-31 +@item month @tab 0-12 (or names, see below) +@item day of week @tab 0-7 (0 or 7 is Sun, or use names) +@end multitable + +A field may be an asterisk (*), which always stands for ``first-last''. + +@cindex 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. + +@cindex 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''. + +@cindex 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''. + +@cindex 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.} + +@cindex % character on vixie-style commands +@cindex 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. + +@cindex day specification, vixie-style +@cindex 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 +@emph{either} +field matches the current time. For example, + +``30 4 1,15 * 5'' + +would cause a command to be run at 4:30 am on the 1st and 15th of each +month, plus every Friday. + +EXAMPLE CRON FILE + +@example +# 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" +@end example + +@node Incompatibilities with old Unices, , Crontab file, Vixie Syntax +@subsection Extensions and incompatibilities. +@cindex incompatibilities with old Unices +@cindex 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. + +@itemize @bullet +@item +@cindex 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. + +@item +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. + +@item +Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". + +@item +Names of months or days of the week can be specified by name. + +@item +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. + +@item +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). + +@end itemize + + +@node Invoking, Guile modules, Syntax, Top +@chapter Detailed invoking +@cindex invoking +@cindex personality +@cindex mcron program +@cindex cron program +@cindex crond program +@cindex 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. + +@cindex 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. + + + +@menu +* Running mcron:: +* Running cron or crond:: +* Running crontab:: +* Exit codes:: +@end menu + +@node Running mcron, Running cron or crond, Invoking, Invoking +@section Running mcron +@cindex invoking mcron +@cindex mcron options +@cindex mcron arguments +@cindex command line, mcron +@cindex 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 directory. In either case, files which +end in the extension .vixie or .vix will be assumed to contain +Vixie-style crontabs, and files ending .guile or .gle will be assumed +to contain scheme code and will be executed as such. + +The program accepts the following options. + +@table @option +@item -s [count] +@itemx --schedule[=count] +@cindex printout of jobs schedule +@cindex schedule of jobs, listing +@cindex options, schedule +@cindex options, -s +@cindex -s option +@cindex --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. + +@cindex daemon option +@cindex options, daemon +@cindex options, -d +@cindex -d option +@cindex --daemon option +@item -d +@itemx --daemon +With this option the program will detach itself from the controlling +terminal and run as a daemon process. + +@cindex stdin option +@cindex options, stdin +@cindex options, -i +@cindex -i option +@cindex --stdin option +@cindex standard input, configuring from +@cindex configuring from standard input +@item -i (vixie|guile) +@itemx --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. + +@cindex -v option +@cindex --version option +@cindex options, -v +@cindex options, version +@item -v +@itemx --version +This option causes a message to be printed on the standard output with +information about the version and copyright for the current program. + +@cindex -h option +@cindex --help option +@cindex options, -h +@cindex options, --help +@item -h +@itemx --help +This causes a short but complete usage message to be displayed on +standard output. + +@end table + +@node Running cron or crond, Running crontab, Running mcron, Invoking +@section Running cron or crond +@cindex cron, invokation +@cindex running cron +@cindex crond, invokation +@cindex running crond +@cindex @CONFIG_SPOOL_DIR@ +@cindex @CONFIG_SOCKET_FILE@ +If the program runs by the name of @code{cron} or @code{crond}, then +it will read all the files in @code{@CONFIG_SPOOL_DIR@} (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 +@code{@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. + +@table @option + +@cindex -v option +@cindex --version option +@cindex options, -v +@cindex options, version +@item -v +@itemx --version +This option causes a message to be printed on the standard output with +information about the version and copyright for the current program. + +@cindex -h option +@cindex --help option +@cindex options, -h +@cindex options, --help +@item -h +@itemx --help +This causes a short but complete usage message to be displayed on +standard output. + +@item -s [count] +@itemx --schedule[=count] +@cindex printout of jobs schedule +@cindex schedule of jobs, listing +@cindex options, schedule +@cindex options, -s +@cindex -s option +@cindex --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. + +@cindex -n option +@cindex --noetc option +@cindex options, -n +@cindex options, --noetc +@item -n +@itemx --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 +@code{/etc/crontab} file be taken off the system altogether!) + +@end table + +@node Running crontab, Exit codes, Running cron or crond, Invoking +@section Running crontab +@cindex crontab, invoking +@cindex running 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 + +@code{crontab [-u user] file} + +or + +@code{crontab [-u user] ( -l | -e | -r )} + +Only the root user can use the -u option, to specify the manipulation +of another user's crontab file. In the first instance, the entire +crontab file of the user is replaced with the contents of the +specified file, or standard input if the file is ``-''. + +In the latter case, the program behaves according to which of the +(mutually exclusive) options was given (note that the long options are +an mcron extension). + +@table @option + +@cindex -l option +@cindex list option, crontab +@cindex options, -l +@cindex options, --list +@cindex viewing a crontab +@cindex listing a crontab +@item -l +@itemx --list +Print the user's crontab file to the standard output, and exit. + +@cindex -r option +@cindex remove option +@cindex options, -r +@cindex options, --remove +@cindex deleting a crontab +@cindex removing a crontab +@item -r +@item --remove +Delete the user's crontab file, and exit. + +@cindex -e option +@cindex edit option +@cindex options, -e +@cindex options, --edit +@cindex editing a crontab +@cindex creating a crontab +@item -e +@item --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. + +@end table + + + +@node Exit codes, , Running crontab, Invoking +@section Exit codes +@cindex exit codes +@cindex error conditions +@cindex errors +The following are the status codes returned to the operating system +when the program terminates. + +@table @asis +@item 0 +No problems. + +@item 1 +An attempt has been made to start cron but there is already a +@CONFIG_PID_FILE@ 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. + +@item 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. + +@item 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. + +@item 4 +An attempt to run cron has been made by a user who does not have +permission to access the crontabs in @CONFIG_SPOOL_DIR@. These files +should be readable only by root, and the cron daemon must be run as +root. + +@item 5 +An attempt to run mcron has been made, but there are no jobs to +schedule! + +@item 6 +The system administrator has blocked this user from using crontab with +the files @CONFIG_ALLOW_FILE@ and @CONFIG_DENY_FILE@. + +@item 7 +Crontab has been run with more than one of the arguments @code{-l}, +@code{-r}, @code{-e}. These are mutually exclusive options. + +@item 8 +Crontab has been run with the -u option by a user other than +root. Only root is allowed to use this option. + +@item 9 +An invalid vixie-style time specification has been supplied. + +@item 10 +An invalid vixie-style job specification has been supplied. + +@item 11 +A bad line has been seen in /etc/crontab. + +@item 12 +The last component of the name of the program was not one of +@code{mcron}, @code{cron}, @code{crond} or @code{crontab}. + +@item 13 +Either the ~/.cron directory does not exist, or there is a problem +reading the files there. + +@c @item 14 +@c There is a problem writing to /var/cron/update. This is probably +@c because the crontab program is not installed SUID root, as it should +@c be. + +@item 15 +Crontab has been run without any arguments at all. There is no default +behaviour in this case. + +@item 16 +Cron has been run by a user other than root. + +@end table + + + +@node Guile modules, Index, Invoking, Top +@chapter 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. + +@menu +* 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. +@end menu + +@node The core module, The redirect module, Guile modules, Guile modules +@section The core module +@cindex guile module +@cindex core module +@cindex 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 +@code{run-job-loop}, which allow a program to create a list of job +specifications to run, and then to initiate the wait-run-wait loop +firing the jobs off at the requisite times. However, before they are +introduced two functions which manipulate the environment that takes +effect when a job runs are defined. + +@cindex 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. + +@deffn{Scheme procedure} append-environment-mods name value +When a job is run make sure the environment variable @var{name} has +the value @var{value}. +@end deffn + +@deffn{Scheme procedure} clear-environment-mods +This procedure causes all the environment modifiers that have been +specified so far to be forgotten. +@end deffn + +@deffn{Scheme 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. +@end deffn + +@deffn{Scheme procedure} run-job-loop . fd-list +@cindex file descriptors +@cindex 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. +@end deffn + +@deffn{Scheme 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. +@end deffn + +@deffn{Scheme procedure} get-schedule count +@cindex 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. +@end deffn + +@node The redirect module, The vixie-time module, The core module, Guile modules +@section The redirect module +@cindex redirect module +@cindex modules, redirect + +This module is introduced to a program with the command +@code{(use-modules (mcron redirect))}. + +This module provides the @code{with-mail-out} function, described +fully in @ref{Guile Syntax}. + +@node The vixie-time module, The job-specifier module, The redirect module, Guile modules +@section The vixie-time module +@cindex vixie-time module +@cindex 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 +@code{next-time-function} 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. + +@deffn{Scheme 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. +@end deffn + + +@node The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules +@section The job-specifier module +@cindex job-specifier module +@cindex 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}, +@code{next-year}, @code{next-month-from}, @code{next-month}, +@code{next-day-from}, @code{next-day}, @code{next-hour-from}, +@code{next-hour}, @code{next-minute-from}, @code{next-minute}, +@code{next-second-from}, @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. + +@node The vixie-specification module, , The job-specifier module, Guile modules +@section The vixie-specification module +@cindex vixie-specification module +@cindex 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. + +@deffn{Scheme 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. + +@var{parse-line} 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. + +@end deffn + +@deffn{Scheme 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 +@code{read-vixie-port} above. + +@end 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 +@code{read-vixie-file}. + +@node Index, , Guile modules, Top +@unnumbered Index + +@printindex cp + +@bye diff --git a/vixie-specification.scm b/vixie-specification.scm index 89c89f4..4af327f 100644 --- a/vixie-specification.scm +++ b/vixie-specification.scm @@ -186,6 +186,6 @@ (let ((mtime (stat:mtime (stat "/etc/crontab")))) (if (> mtime (- (current-time) 60)) (let ((socket (socket AF_UNIX SOCK_STREAM 0))) - (connect socket AF_UNIX "/var/cron/socket") + (connect socket AF_UNIX config-socket-file) (display "/etc/crontab" socket) (close socket))))))) -- cgit v1.2.3