>From b71a9d9ddcff21d366e0e0fb14f494f74ac3d008 Mon Sep 17 00:00:00 2001
From: Mathieu Lirzin
Date: Fri, 26 Jun 2015 23:17:01 +0200
Subject: [PATCH 2/4] Fix build of the manual.
---
.gitignore | 9 +-
ChangeLog | 9 +
README--git | 11 +-
configure.ac | 7 +-
doc/config.texi.in | 5 +
doc/mcron.texi | 1337 ++++++++++++++++++++++++++++++++++++++++++++++++++++
makefile.am | 9 +-
mcron.texinfo.in | 1335 ---------------------------------------------------
8 files changed, 1372 insertions(+), 1350 deletions(-)
create mode 100644 doc/config.texi.in
create mode 100644 doc/mcron.texi
delete mode 100644 mcron.texinfo.in
diff --git a/.gitignore b/.gitignore
index 00fa239..2bedd6e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,13 +10,18 @@ config.status
configure
core.scm
depcomp
+/doc/.dirstamp
+/doc/config.texi
+/doc/mcron.info
+/doc/mcron.1
+/doc/stamp-vti
+/doc/version.texi
install-sh
makefile
makefile.in
/mcron
mcron.c
-mcron.info
+/mdate-sh
*.o
-mcron.texinfo
missing
texinfo.tex
diff --git a/ChangeLog b/ChangeLog
index cccecbe..806a03f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2015-06-26 Mathieu Lirzin
+ Fix build of the manual.
+ * mcron.texinfo.in: Move to ...
+ * doc/mcron.texi: ... Here. New file.
+ * doc/config.texi.in: New file.
+ * configure.ac: Adapt to it.
+ * makefile.am: Likewise.
+ * .gitignore: Likewise.
+ * README--git: Likewise.
+
Add missing 'makefile.am'.
* scm/mcron/makefile.am: New file.
* .gitignore: Ignore 'mcron' only in the top-level directory.
diff --git a/README--git b/README--git
index 43e9890..9ebaa0d 100644
--- a/README--git
+++ b/README--git
@@ -1,6 +1,7 @@
GNU mcron --- README--git -*-text-*-
Copyright (C) 2012, 2014 Dale Mellor
+ Copyright (C) 2015 Mathieu Lirzin
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
@@ -10,13 +11,9 @@ GNU mcron --- README--git -*-text-*-
If you have pulled mcron from the GIT repository, these are the steps you will
need to take to build it the first time:
-1) aclocal
-2) autoconf
-3) automake -a (will error)
-4) ./configure (will error)
-5) automake -a
-6) ./configure --prefix={wherever}
-7) make install
+1) autoreconf -vfi
+2) ./configure --prefix={wherever}
+3) make install
After that it should just be a simple matter of typing `make install' when you
diff --git a/configure.ac b/configure.ac
index c819d4d..7422469 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3,6 +3,7 @@
# Copyright (C) 2003, 2005, 2012, 2014 Dale Mellor
+# Copyright (C) 2015 Mathieu Lirzin
#
# This file is part of GNU mcron.
#
@@ -170,6 +171,8 @@ AC_SUBST(CONFIG_TMP_DIR)
real_program_prefix=`echo $program_prefix | sed s/NONE//`
AC_SUBST(real_program_prefix)
-
-AC_CONFIG_FILES(mcron.texinfo makefile scm/mcron/makefile scm/mcron/config.scm)
+AC_CONFIG_FILES([doc/config.texi
+ makefile
+ scm/mcron/makefile
+ scm/mcron/config.scm])
AC_OUTPUT
diff --git a/doc/config.texi.in b/doc/config.texi.in
new file mode 100644
index 0000000..50d9a18
--- /dev/null
+++ b/doc/config.texi.in
@@ -0,0 +1,5 @@
address@hidden CONFIG_SOCKET_FILE @CONFIG_SOCKET_FILE@
address@hidden CONFIG_SPOOL_DIR @CONFIG_SPOOL_DIR@
address@hidden CONFIG_PID_FILE @CONFIG_PID_FILE@
address@hidden CONFIG_ALLOW_FILE @CONFIG_ALLOW_FILE@
address@hidden CONFIG_DENY_FILE @CONFIG_DENY_FILE@
diff --git a/doc/mcron.texi b/doc/mcron.texi
new file mode 100644
index 0000000..cb97a06
--- /dev/null
+++ b/doc/mcron.texi
@@ -0,0 +1,1337 @@
+\input texinfo
address@hidden %**start of header
address@hidden mcron.info
address@hidden config.texi
address@hidden version.texi
address@hidden mcron @value{VERSION}
address@hidden %**end of header
+
address@hidden fn cp
+
address@hidden This manual is for GNU mcron (version @value{VERSION}), which is a
+program for running jobs at scheduled times.
+
+Copyright @copyright{} 2003, 2005, 2006, 2012, 2014 Dale Mellor
+
address@hidden
+Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License,
+Version 1.3 or any later version published by the Free Software
+Foundation; with no Invariant Sections, no Front-Cover Texts and
+no Back-Cover Texts. A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
address@hidden quotation
address@hidden copying
+
+
address@hidden
+
address@hidden Individual utilities
+
address@hidden
+* mcron: (mcron). Run jobs at scheduled times.
address@hidden direntry
+
address@hidden ifinfo
+
+
address@hidden
address@hidden mcron - Mellor's cron daemon
address@hidden Dale Mellor
+
address@hidden
address@hidden 0pt plus 1fill
address@hidden @insertcopying
+
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top, Introduction, (dir), (dir)
address@hidden mcron
+
+This file documents the @code{mcron} command (Mellor's cron) for
+running jobs at scheduled times.
+
address@hidden @insertcopying
address@hidden ifnottex
+
address@hidden
+* Introduction:: Introducing mcron.
+* Simple examples:: How to use mcron 99.9% of the time.
+* Syntax:: All the possibilities for configuring cron jobs.
+* Invoking:: What happens when you run the mcron command.
+* Guile modules:: Incorporating mcron into another Guile program.
+* Index:: The complete index.
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Simple examples
+
+* Guile Simple Examples::
+* Vixie Simple Examples::
+
+Full available syntax
+
+* Guile Syntax::
+* Extended Guile examples::
+* Vixie Syntax::
+
+Extended Guile examples
+
+* AT commands::
+* Every second Sunday::
+* Two hours every day::
+* Missing the first appointment::
+* Penultimate day of every month::
+
+Vixie
+
+* Paul Vixie's copyright::
+* Crontab file::
+* Incompatibilities with old Unices::
+
+Detailed invoking
+
+* Invoking mcron::
+* Invoking cron or crond::
+* Invoking crontab::
+* Behaviour on laptops::
+* Exit codes::
+
+Guile modules
+
+* The core module:: The job list and execution loop.
+* The redirect module:: Sending output of jobs to a mail box.
+* The vixie-time module:: Parsing vixie-style time specifications.
+* The job-specifier module:: All commands for scheme configuration files.
+* The vixie-specification module:: Commands for reading vixie-style crontabs.
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Introduction, Simple examples, Top, Top
address@hidden Introducing mcron
address@hidden introduction
address@hidden mcron
+The mcron program represents a complete re-think of the cron concept
+originally found in the Berkeley and AT&T unices, and subsequently
+rationalized by Paul Vixie. The original idea was to have a daemon
+that wakes up every minute, scans a set of files under a special
+directory, and determines from those files if any shell commands
+should be executed in this minute.
+
+The new idea is to read the required command instructions, work out
+which command needs to be executed next, and then sleep until the
+inferred time has arrived. On waking the commands are run, and the
+time of the next command is computed. Furthermore, the specifications
+are written in scheme, allowing at the same time simple command
+execution instructions and very much more flexible ones to be composed
+than the original Vixie format. This has several useful advantages
+over the original idea. (Changes to user crontabs are signalled
+directly to mcron by the crontab program; cron must still scan the
+/etc/crontab file once every minute, although use of this file is
+highly discouraged and this behaviour can be turned off).
+
address@hidden advantages of mcron
address@hidden @bullet
address@hidden
+Does not consume CPU resources when not needed. Many cron daemons only
+run jobs once an hour, or even just once a day.
address@hidden
+Can easily allow for finer time-points to be specified,
+i.e. seconds. In principle this could be extended to microseconds, but
+this is not implemented.
address@hidden
+Times can be more or less regular. For example, a job that runs
+every 17 hours can be specified, or a job that runs on the first
+Sunday of every month.
address@hidden
+Times can be dynamic. Arbitrary Guile (scheme) code can be provided to
+compute the next time that a command needs to be run. This could, for
+example, take the system load into consideration.
address@hidden
+Turns out to be easy to provide complete backwards compatibility with
+Vixie cron.
address@hidden
+Each user looks after his own files in his own directory. He can use
+more than one to break up complicated cron specifications.
address@hidden
+Each user can run his own daemon. This removes the need for suid
+programs to manipulate the crontabs, and eliminates many security
+concerns that surround all existing cron programs.
address@hidden
+The user can obtain an advance schedule of all the jobs that are due
+to run.
address@hidden
+Vixie cron is implemented in 4500 lines of C code; mcron is 2000 lines
+of scheme, despite the fact that it offers many more features and much
+more flexibility, and complete compatibility with Vixie cron.
address@hidden itemize
+
+A full discussion of the design and philosophy of mcron can be found
+in the white paper at
address@hidden://www.gnu.org/software/mcron/design.html}.
+
+
address@hidden Simple examples, Syntax, Introduction, Top
address@hidden Simple examples
+The vast majority of uses of cron are sublimely simple: run a program
+every hour, or every day. With this in mind the design of mcron has
+been to allow such simple specifications to be made easily. The
+examples show how to create the command descriptions, and subsequently
+how to run mcron to make them happen.
address@hidden
+* Guile Simple Examples::
+* Vixie Simple Examples::
address@hidden menu
+
address@hidden Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples
address@hidden Guile
address@hidden guile examples
address@hidden examples, guile
address@hidden example, run a program every hour
+You have an executable @code{my-program} in your home directory, which
+you want to run every hour. Create a file @code{job.guile} in
+directory @code{~/.config/cron} (this path may be altered by the
address@hidden environment variable) with the following
+contents
+
address@hidden
+(job '(next-hour) "my-program")
address@hidden example
+
+then run the command @code{mcron}.
+
+Want the program to run fifteen minutes past the hour, every two
+hours? Edit the file to read
+
address@hidden
+(job
+ '(next-minute-from
+ (next-hour (range 0 24 2))
+ 15)
+ "my-program")
address@hidden example
+
+and run the command @code{mcron}.
+
+Or, if you are not comfortable with Scheme, you could use (and see
+also the next section)
+
address@hidden
+(job "15 */2 * * *" "my-program")
address@hidden example
+
+and run the @code{mcron} command.
+
+If you want to run other jobs, you can either add more lines to this
+file, or you can create other files in your @code{.config/cron} directory
+with the @code{.guile} extension. Alternatively, you can use any file
+you want and pass it as an argument to @code{mcron}, or even pipe the
+commands into the standard input.
+
+
address@hidden Vixie Simple Examples, , Guile Simple Examples, Simple examples
address@hidden Vixie
address@hidden examples
address@hidden examples, vixie
address@hidden vixie examples
+You have an executable @code{my-program} in your home directory, which
+you want to run every hour. Create a file @code{job.vixie} in directory
address@hidden/.cron} with the following contents
+
address@hidden
+0 * * * * my-program
address@hidden example
+
+then run the command @code{mcron}.
+
address@hidden vixie compatibility
address@hidden compatibility
+Alternatively (full compatibility with Vixie cron), set your
+environment variable @code{EDITOR} to your favorite editor, run
address@hidden -e}, put the above line into the edit buffer, save and
+exit. For this to work the @code{cron} daemon must be already running
+on your system, as root.
+
address@hidden Syntax, Invoking, Simple examples, Top
address@hidden Full available syntax
address@hidden
+* Guile Syntax::
+* Extended Guile examples::
+* Vixie Syntax::
address@hidden menu
address@hidden Guile Syntax, Extended Guile examples, Syntax, Syntax
address@hidden Guile Syntax
address@hidden Job specification
address@hidden guile syntax
address@hidden syntax, guile
address@hidden job
+In Guile-formatted configuration files each command that needs
+executing is introduced with the @code{job} function. This function
+always takes two arguments, the first a time specification, and the
+second a command specification. An optional third argument may contain
+a string to display when this job is listed in a schedule.
+
address@hidden time specification, procedure
address@hidden procedure time specification
+The first argument can be a procedure, a list, or a string. If a
+function is supplied, it must take exactly one argument, which will be
+the ``current'' time in UNIX format, and the return value of the
+function must be the time in UNIX format when this action should next
+be run. The following functions are available to facilitate the
+computation:
+
address@hidden next-second-from
address@hidden(next-second-from time . args)} without arguments this
+returns the second after the current one. With the extra arguments,
+these form a list of seconds in the minute when the action should run,
+and the function will return the time of the next allowed second
+(which may be in the next minute of the hour). @footnote{Note that
+while commands can be scheduled to run at any second, it is unlikely
+that they will be executed then but some time shortly thereafter,
+depending on the load on the system and the number of jobs that mcron
+has to start at the same time.}
+
address@hidden next-minute-from
address@hidden next-hour-from
address@hidden next-day-from
address@hidden next-week-from
address@hidden next-month-from
address@hidden next-year-from
+Similarly to @code{next-second-from}, there are also
address@hidden, @code{next-hour-from}, @code{next-day-from},
address@hidden, @code{next-month-from}, @code{next-year-from}.
+
address@hidden range
+Furthermore, the optional argument can be fulfilled by the function
address@hidden(range start end . step)}, which will provide a list of values
+from start to (but not including) end, with the step if given. For
+example @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}.
+
address@hidden next-second
address@hidden next-minute
address@hidden next-hour
address@hidden next-day
address@hidden next-week
address@hidden next-month
address@hidden next-year
address@hidden time specification, list
address@hidden list time specification
+If the first argument to the @code{job} function is a list, it is
+taken to be program code made up of the functions @code{(next-second
+. args)}, @code{(next-minute...)}, etc, where the optional arguments
+can be supplied with the @code{(range)} function above (these
+functions are analogous to the ones above except that they implicitly
+assume the current time; it is supplied by the mcron core when the
+list is eval'd).
+
address@hidden time specification
address@hidden time specification, string
address@hidden string time specification
address@hidden time specification, vixie-style
address@hidden vixie-style time specification
+If the first argument to the @code{job} function is a string, it is
+expected to be a Vixie cron-style time specification. See the section
+on Vixie syntax for this.
+
address@hidden job execution
address@hidden command execution
address@hidden execution
+The second argument to the @code{(job)} function can be either a
+string, a list, or a function. In all cases the command is executed in
+the user's home directory, under the user's own UID. If a string is
+passed, it is assumed to be shell script and is executed with the
+user's default shell. If a list is passed it is assumed to be scheme
+code and is eval'd as such. A supplied function should take exactly
+zero arguments, and will be called at the pertinent times.
+
address@hidden Sending output as e-mail
address@hidden email output
address@hidden email from guile script
address@hidden standard input to commands
address@hidden with-mail-out
+When jobs are specified in a vixie-style configuration, the command is
+broken at a percentage sign, and the stuff that comes after this is
+sent into the command's standard input. Furthermore, any output from
+the command is mailed to the user. This functionality is provided for
+compatibility with Vixie cron, but it is also available to scheme
+configuration files. The command (with-mail-out action . user) can be
+used to direct output from the action (which may be a procedure, list,
+or string) into an e-mail to the user.
+
+In the case that the action is a string, then percentage signs are
+processed as per the vixie specifications, and information is piped to
+the shell command's standard input.
+
address@hidden Setting environment variables
address@hidden environment variables in scheme
address@hidden setting environment variables
address@hidden append-environment-mods
+Also for compatibility with Vixie cron, mcron has the ability to set
+environment variables in configuration files. To access this
+functionality from a scheme configuration file, use the command
+(append-environment-mods name value), where name is the name of an
+environment variable, and value is the value put to it. A value of #f
+will remove the variable from the environment.
+
+Note that environment modifications are accumulated as the
+configuration file is processed, so when a job actually runs, its
+environment will be modified according to the modifications specified
+before the job specification in the configuration file.
+
+
address@hidden Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax
address@hidden Extended Guile examples
address@hidden examples, extended guile
address@hidden extended guile examples
+While Guile gives you flexibility to do anything, and the power to
+represent complex requirements succinctly, things are not always as
+they seem. The following examples illustrate some pitfalls, and
+demonstrate how to code around them.
+
address@hidden
+* AT commands::
+* Every second Sunday::
+* Two hours every day::
+* Missing the first appointment::
+* Penultimate day of every month::
address@hidden menu
+
address@hidden AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples
address@hidden Synthesizing ``at'' commands
address@hidden at command
+The current implementation of mcron does not provide for an at command
+(a command-line program that allows the user to specify that a job
+runs exactly once at a certain time). This can, however, be achieved.
+
+Suppose the program @code{my-program} needs to be run at midnight
+tonight. A Guile script like the following would work (but a printed
+schedule, obtained with the @code{--schedule} option, will show
+superfluous entries).
+
address@hidden
+(job '(next-day)
+ (lambda () (system "my-program")
+ (kill (getppid) SIGINT)))
address@hidden example
+
address@hidden Every second Sunday, Two hours every day, AT commands, Extended Guile examples
address@hidden Every second Sunday
address@hidden examples, every second sunday
+To run @code{my-program} on the second Sunday of every month, a Guile
+script like the following should suffice (it is left as an exercise to
+the student to understand how this works!).
+
address@hidden
+(job (lambda (current-time)
+ (let* ((next-month (next-month-from current-time))
+ (first-day (tm:wday (localtime next-month)))
+ (second-sunday (if (eqv? first-day 0)
+ 8
+ (- 14 first-day))))
+ (+ next-month (* 24 60 60 second-sunday))))
+ "my-program")
address@hidden example
+
+
address@hidden Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples
address@hidden Two hours every day
address@hidden examples, two hours every day
address@hidden pitfalls, two hours every day
+Surprisingly perhaps, the following will @strong{not} have the desired
+effect.
+
address@hidden
+(job '(next-hour-from (next-day) '(1 2))
+ "my-program")
address@hidden example
+
+Rather than running the my-program program at one o'clock and two
+o'clock every day, it will only run it at one o'clock. This is because
+each time mcron has to compute the next time to run the command, it
+first obtains the next day, and then finds the earliest hour in that
+day to run at. Thus, after running the command at one o'clock, the
+program first skips forwards to the next midnight (missing the two
+o'clock appointment), and then finds the next one o'clock schedule.
+
+The following simple command is the correct way to specify this
+behaviour.
+
address@hidden
+(job '(next-hour '(1 2)) "my-program")
address@hidden example
+
+
address@hidden Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples
address@hidden Missing the first appointment
address@hidden examples, missing the first appointment
address@hidden pitfalls, missing the first appointment
+The command
+
address@hidden
+(job '(next-hour-from (next-day) '(16))
+ "my-program")
address@hidden example
+
+will run @code{my-program} every day at four o'clock in the
+afternoon. However, if mcron is started with this script at midday,
+the first time the command will run will be four o'clock tomorrow;
+today's appointment will be missed (one time only).
+
+The correct way to specify this requirement is simply
+
address@hidden
+(job '(next-hour '(16))
+ "my-program")
address@hidden example
+
+
address@hidden Penultimate day of every month, , Missing the first appointment, Extended Guile examples
address@hidden Penultimate day of every month
address@hidden examples, penultimate day of every month
+The following will run the @code{my-program} program on the
+second-to-last day of every month.
+
address@hidden
+(job '(- (next-month-from (next-month)) (* 48 3600))
+ "my-program")
address@hidden example
+
+
+
address@hidden Vixie Syntax, , Extended Guile examples, Syntax
address@hidden Vixie
address@hidden syntax, vixie
address@hidden vixie syntax
address@hidden vixie definition
address@hidden vixie compatibility
address@hidden compatibility, vixie
address@hidden that this section is definitive. If there is a difference in
+behaviour between the mcron program and this part of the manual, then
+there is a bug in the program. This section is also copied verbatim
+from Paul Vixie's documentation for his cron program, and his
+copyright notice is duly reproduced below.
+
+There are three problems with this specification.
+
address@hidden zero'th day of month
address@hidden 0'th day of month
+1. It is allowed to specify days of the month in the range 0-31. What
+does it mean to specify day 0? Looking at the Vixie source code, it
+seems that if this date appears as part of a list, it has no
+effect. However, if it appears on its own, the effect is to say
+``don't run on any particular day of the month, only take the week-day
+specification into account.'' Mcron has been coded to mimic this
+behaviour as a special case (unmodified mcron logic implies that this
+date specification would cause jobs to run on the last day of the
+previous month).
+
address@hidden thirteenth month of year
address@hidden 13th month of year
+2. Similarly to the above (but different), months of the year can be
+specified in the range 0-12. In the case of mcron (don't know what
+Vixie cron did) month 12 will cause the program to wait until January
+of the following year (but don't rely on this).
+
address@hidden shell
address@hidden environment variables, shell
address@hidden /etc/passwd
+3. Somewhere it says that cron sets the SHELL environment variable to
+/bin/sh, and elsewhere it implies that the default behaviour is for
+the user's default shell to be used to execute commands. Mcron sets
+the variable and runs the command in the user's default shell, as
+advertised by the /etc/passwd file.
+
address@hidden
+* Paul Vixie's copyright::
+* Crontab file::
+* Incompatibilities with old Unices::
address@hidden menu
+
+
address@hidden Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax
address@hidden Paul Vixie's copyright
address@hidden copyright, Paul Vixie's
address@hidden Paul Vixie's copyright
address@hidden
+Copyright 1988,1990,1993,1994 by Paul Vixie
+All rights reserved
+
+Distribute freely, except: don't remove my name from the source or
+documentation (don't take credit for my work), mark your changes (don't
+get me blamed for your possible bugs), don't alter or remove this
+notice. May be sold if buildable source is provided to buyer. No
+warrantee of any kind, express or implied, is included with this
+software; use at your own risk, responsibility for damages (if any) to
+anyone resulting from the use of this software rests entirely with the
+user.
address@hidden quotation
+
+
+
+
address@hidden Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax
address@hidden Crontab files
address@hidden crontab file
address@hidden vixie crontab file
+A @code{crontab} file contains instructions to the @code{cron} daemon
+of the general form: ``run this command at this time on this date''.
+Each user has their own crontab, and commands in any given crontab
+will be executed as the user who owns the crontab. Uucp and News will
+usually have their own crontabs, eliminating the need for explicitly
+running @code{su} as part of a cron command.
+
address@hidden comments, vixie-style
+Blank lines and leading spaces and tabs are ignored. Lines whose first
+non-space character is a pound-sign (#) are comments, and are ignored.
+Note that comments are not allowed on the same line as cron commands, since
+they will be taken to be part of the command. Similarly, comments are not
+allowed on the same line as environment variable settings.
+
+An active line in a crontab will be either an environment setting or a cron
+command. An environment setting is of the form,
+
address@hidden environment setting, vixie-style
address@hidden
+name = value
address@hidden example
+
+where the spaces around the equal-sign (=) are optional, and any
+subsequent non-leading spaces in @code{value} will be part of the
+value assigned to @code{name}. The @code{value} string may be placed
+in quotes (single or double, but matching) to preserve leading or
+trailing blanks.
+
address@hidden environment variables, SHELL
address@hidden environment variables, LOGNAME
address@hidden environment variables, HOME
address@hidden SHELL environment variable
address@hidden LOGNAME environment variable
address@hidden HOME environment variable
address@hidden /etc/passwd
+Several environment variables are set up automatically by the
address@hidden daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are
+set from the /etc/passwd line of the crontab's owner. HOME and SHELL
+may be overridden by settings in the crontab; LOGNAME may not.
+
address@hidden environment variables, USER
address@hidden USER environment variable
address@hidden BSD
+(Another note: the LOGNAME variable is sometimes called USER on BSD systems...
+on these systems, USER will be set also.) @footnote{mcron has not been
+ported to BSD, so these notes are not relevant.}
+
address@hidden environment variables, MAILTO
address@hidden MAILTO environment variable
+In addition to LOGNAME, HOME, and SHELL, @code{cron} will look at
+MAILTO if it has any reason to send mail as a result of running
+commands in ``this'' crontab. If MAILTO is defined (and non-empty),
+mail is sent to the user so named. If MAILTO is defined but empty
+(MAILTO=""), no mail will be sent. Otherwise mail is sent to the
+owner of the crontab. This option is useful if you decide on
+/bin/mail instead of /usr/lib/sendmail as your mailer when you install
+cron -- /bin/mail doesn't do aliasing, and UUCP usually doesn't read
+its mail.
+
+The format of a cron command is very much the V7 standard, with a number of
+upward-compatible extensions. Each line has five time and date fields,
+followed by a user name if this is the system crontab file,
+followed by a command. Commands are executed by @code{cron}
+when the minute, hour, and month of year fields match the current
+time, @strong{and} when at least one of the two day fields (day of month, or day of week)
+match the current time (see ``Note'' below). @code{cron} examines cron entries once every minute.
+The time and date fields are:
+
address@hidden vixie time specification fields
address@hidden fields, vixie time specification
address@hidden @columnfractions .2 .5
address@hidden Field @tab Allowed values
address@hidden ----- @tab --------------
address@hidden minute @tab 0-59
address@hidden hour @tab 0-23
address@hidden day of month @tab 0-31
address@hidden month @tab 0-12 (or names, see below)
address@hidden day of week @tab 0-7 (0 or 7 is Sun, or use names)
address@hidden multitable
+
+A field may be an asterisk (*), which always stands for ``first-last''.
+
address@hidden ranges in vixie time specifications
+Ranges of numbers are allowed. Ranges are two numbers separated
+with a hyphen. The specified range is inclusive. For example,
+8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
+and 11.
+
address@hidden lists in vixie time specifications
+Lists are allowed. A list is a set of numbers (or ranges)
+separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''.
+
address@hidden steps in vixie time specifications
+Step values can be used in conjunction with ranges. Following
+a range with ``/'' specifies skips of the number's value
+through the range. For example, ``0-23/2'' can be used in the hours
+field to specify command execution every other hour (the alternative
+in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are
+also permitted after an asterisk, so if you want to say ``every two
+hours'', just use ``*/2''.
+
address@hidden names in vixie-style time specifications
+Names can also be used for the ``month'' and ``day of week''
+fields. Use the first three letters of the particular
+day or month (case doesn't matter). Ranges or
+lists of names are not allowed. @footnote{Mcron allows any alphabetic
+characters after a name, so full names of days or months are also valid.}
+
address@hidden % character on vixie-style commands
address@hidden standard input, vixie-style
+The ``sixth'' field (the rest of the line) specifies the command to be
+run.
+The entire command portion of the line, up to a newline or %
+character, will be executed by /bin/sh or by the shell
+specified in the SHELL variable of the cronfile.
+Percent-signs (%) in the command, unless escaped with backslash
+(\\), will be changed into newline characters, and all data
+after the first % will be sent to the command as standard
+input.
+
address@hidden day specification, vixie-style
address@hidden vixie-style day specification
+Note: The day of a command's execution can be specified by two
+fields -- day of month, and day of week. If both fields are
+restricted (ie, aren't *), the command will be run when
address@hidden
+field matches the current time. For example,
+
+``30 4 1,15 * 5''
+
+would cause a command to be run at 4:30 am on the 1st and 15th of each
+month, plus every Friday.
+
+EXAMPLE CRON FILE
+
address@hidden
+# use /bin/sh to run commands, no matter what /etc/passwd says
+SHELL=/bin/sh
+# mail any output to `paul', no matter whose crontab this is
+MAILTO=paul
+#
+# run five minutes after midnight, every day
+5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
+# run at 2:15pm on the first of every month -- output mailed to paul
+15 14 1 * * $HOME/bin/monthly
+# run at 10 pm on weekdays, annoy Joe
+0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
+23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
+5 4 * * sun echo "run at 5 after 4 every sunday"
address@hidden example
+
address@hidden Incompatibilities with old Unices, , Crontab file, Vixie Syntax
address@hidden Extensions and incompatibilities
address@hidden incompatibilities with old Unices
address@hidden extensions, vixie over old Unices
+This section lists differences between Paul Vixie's cron and the
+olde-worlde BSD and AT&T programs, for the benefit of system
+administrators and users who are upgrading all the way.
+
address@hidden @bullet
address@hidden
address@hidden day 7
+When specifying day of week, both day 0 and day 7 will be considered Sunday.
+BSD and AT&T seem to disagree about this.
+
address@hidden
+Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would
+be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY.
+
address@hidden
+Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
+
address@hidden
+Names of months or days of the week can be specified by name.
+
address@hidden
+Environment variables can be set in the crontab. In BSD or AT&T, the
+environment handed to child processes is basically the one from /etc/rc.
+
address@hidden
+Command output is mailed to the crontab owner (BSD can't do this), can be
+mailed to a person other than the crontab owner (SysV can't do this), or the
+feature can be turned off and no mail will be sent at all (SysV can't do this
+either).
+
address@hidden itemize
+
+
address@hidden Invoking, Guile modules, Syntax, Top
address@hidden Detailed invoking
address@hidden invoking
address@hidden personality
address@hidden mcron program
address@hidden cron program
address@hidden crond program
address@hidden crontab program
+The program adopts one of three different personalities depending on
+the name used to invoke it. In a standard installation, the program is
+installed in the system under the names mcron, cron and crontab
+(installed SUID).
+
+The recommended way to invoke the program is via the mcron personality
+described in the next section. The program can also be run as cron by
+root, and by the SUID program crontab by individual users to gain
+backwards compatibility with Vixie cron. However, due to the fact that
+this daemon process is shared by, and under control of, all the users
+of the system it is possible (though very unlikely) that it may become
+unusable, hence the recommendation to use the mcron personality.
+
address@hidden deprecated, vixie personality
+Furthermore, the Vixie personality is considered deprecated by this
+author (it offers not a single advantage over the mcron personality,
+and bloats the code by a factor of three). It is unlikely that this
+personality will ever actually go away, but the program may in future
+be split into two distinct parts, and new developments will only take
+place in the part which implements the mcron personality.
+
+
+
address@hidden
+* Invoking mcron::
+* Invoking cron or crond::
+* Invoking crontab::
+* Behaviour on laptops::
+* Exit codes::
address@hidden menu
+
address@hidden Invoking mcron, Invoking cron or crond, Invoking, Invoking
address@hidden Invoking mcron
address@hidden invoking mcron
address@hidden mcron options
address@hidden mcron arguments
address@hidden command line, mcron
address@hidden mcron command line
+Mcron should be run by the user who wants to schedule his jobs. It
+may be made a background job using the facilities of the shell. The
+basic command is @code{mcron [OPTION ...] [file ...]} which has the
+effect of reading all the configuration files specified (subject to
+the options) and then waiting until it is time to execute some
+command. If no files are given on the command line, then mcron will
+look in the user's cron configuration directories: these are ~/.cron
+(deprecated), the directory indicated by the @code{XDG_CONFIG_HOME}
+environment variable, or ~/.config/cron if this variable is not set.
+In any case, files which end in the extension .vixie or .vix will be
+assumed to contain Vixie-style crontabs, and files ending .guile or
+.gle will be assumed to contain scheme code and will be executed as
+such; ANY OTHER FILES WILL BE IGNORED - specify a file name of ``-''
+and then pipe the files into the standard input if you really want to
+read them, possibly using the @code{stdin} option to specify the type
+of file.
+
+The program accepts the following options.
+
address@hidden @option
address@hidden -s count
address@hidden --schedule=count
address@hidden printout of jobs schedule
address@hidden schedule of jobs, listing
address@hidden options, schedule
address@hidden options, -s
address@hidden -s option
address@hidden --schedule option
+With this option specified no commands are run. Instead, the program
+computes the times the commands would be run and prints the
+information to the screen, and then immediately exits.
+
+The count indicates the number of commands to display.
+
address@hidden daemon option
address@hidden options, daemon
address@hidden options, -d
address@hidden -d option
address@hidden --daemon option
address@hidden -d
address@hidden --daemon
+With this option the program will detach itself from the controlling
+terminal and run as a daemon process.
+
address@hidden stdin option
address@hidden options, stdin
address@hidden options, -i
address@hidden -i option
address@hidden --stdin option
address@hidden standard input, configuring from
address@hidden configuring from standard input
address@hidden -i (vixie|guile)
address@hidden --stdin=(vixie|guile)
+This option is used to indicate whether the configuration information
+being passed on the standard input is in Vixie format or Guile
+format. Guile is the default.
+
address@hidden -v option
address@hidden --version option
address@hidden options, -v
address@hidden options, version
address@hidden -v
address@hidden --version
+This option causes a message to be printed on the standard output with
+information about the version and copyright for the current program.
+
address@hidden -h option
address@hidden --help option
address@hidden options, -h
address@hidden options, --help
address@hidden -h
address@hidden --help
+This causes a short but complete usage message to be displayed on
+standard output.
+
address@hidden table
+
address@hidden Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking
address@hidden Invoking cron or crond
address@hidden cron, invokation
address@hidden invoking cron
address@hidden crond, invokation
address@hidden invoking crond
address@hidden @value{CONFIG_SPOOL_DIR}
address@hidden @value{CONFIG_SOCKET_FILE}
+NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or
address@hidden, and @code{crontab} PROGRAMS HAVE BEEN INSTALLED BY THE
+SYSTEM ADMINISTRATOR.
+
+If the program runs by the name of @code{cron} or @code{crond}, then
+it will read all the files in @address@hidden (which
+should only be readable by root) and the file @code{/etc/crontab}, and
+then detaches itself from the terminal to live forever as a daemon
+process. Additionally, it creates a UNIX socket at
address@hidden@value{CONFIG_SOCKET_FILE}}, and listens for messages sent to
+that socket consisting of a user name whose crontabs have been
+changed. In this case, the program will re-read that user's crontab.
+This is for correct functioning with the crontab program.
+
+Further, if the @code{--noetc} option was not used, a job is scheduled
+to run every minute to check if /etc/crontab has been modified
+recently. If so, this file will also be re-read.
+
+The options which may be used with this program are as follows.
+
address@hidden @option
+
address@hidden -v option
address@hidden --version option
address@hidden options, -v
address@hidden options, version
address@hidden -v
address@hidden --version
+This option causes a message to be printed on the standard output with
+information about the version and copyright for the current program.
+
address@hidden -h option
address@hidden --help option
address@hidden options, -h
address@hidden options, --help
address@hidden -h
address@hidden --help
+This causes a short but complete usage message to be displayed on
+standard output.
+
address@hidden -s [count]
address@hidden --schedule[=count]
address@hidden printout of jobs schedule
address@hidden schedule of jobs, listing
address@hidden options, schedule
address@hidden options, -s
address@hidden -s option
address@hidden --schedule option
+With this option specified no commands are run. Instead, the program
+computes the times the commands would be run and prints the
+information to the screen, and then immediately exits.
+
+The count, if supplied, indicates the number of commands to
+display. The default value is 8.
+
address@hidden -n option
address@hidden --noetc option
address@hidden options, -n
address@hidden options, --noetc
address@hidden -n
address@hidden --noetc
+This tells cron not to add a job to the system which wakes up every
+minute to check for modifications to @code{/etc/crontab}. It is
+recommended that this option be used (and further that the
address@hidden/etc/crontab} file be taken off the system altogether!)
+
address@hidden table
+
address@hidden Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking
address@hidden Invoking crontab
address@hidden crontab, invoking
address@hidden invoking crontab
+This program is run by individual users to inspect or modify their
+crontab files. If a change is made to the file, then the root daemon
+process will be given a kick, and will immediately read the new
+configuration. A warning will be issued to standard output if it
+appears that a cron daemon is not running.
+
+The command is used as
+
address@hidden [-u user] file}
+
+or
+
address@hidden [-u user] ( -l | -e | -r )}
+
+Only the root user can use the -u option, to specify the manipulation
+of another user's crontab file. In the first instance, the entire
+crontab file of the user is replaced with the contents of the
+specified file, or standard input if the file is ``-''.
+
+In the latter case, the program behaves according to which of the
+(mutually exclusive) options was given (note that the long options are
+an mcron extension).
+
address@hidden @option
+
address@hidden -l option
address@hidden list option, crontab
address@hidden options, -l
address@hidden options, --list
address@hidden viewing a crontab
address@hidden listing a crontab
address@hidden -l
address@hidden --list
+Print the user's crontab file to the standard output, and exit.
+
address@hidden -r option
address@hidden remove option
address@hidden options, -r
address@hidden options, --remove
address@hidden deleting a crontab
address@hidden removing a crontab
address@hidden -r
address@hidden --remove
+Delete the user's crontab file, and exit.
+
address@hidden -e option
address@hidden edit option
address@hidden options, -e
address@hidden options, --edit
address@hidden editing a crontab
address@hidden creating a crontab
address@hidden -e
address@hidden --edit
+Using the editor specified in the user's VISUAL or EDITOR environment
+variables, allow the user to edit his crontab. Once the user exits the
+editor, the crontab is checked for parseability, and if it is okay
+then it is installed as the user's new crontab and the daemon is
+notified that a change has taken place, so that the new file will
+become immediately effective.
+
address@hidden table
+
+
address@hidden Behaviour on laptops, Exit codes, Invoking crontab, Invoking
address@hidden Behaviour on laptops
address@hidden laptops
address@hidden power suspend
+While mcron has not been designed to work anachronistically, the behaviour of
+mcron when a laptop emerges from a suspended state is well defined, and the
+following description explains what happens in this situation.
+
+When a laptop awakes from a suspended state, all jobs which would have run while
+the laptop was suspended will run exactly once immediately (and simultaneously)
+when the laptop awakes, and then the next time that those jobs run will be
+computed based on the time the laptop was awoken. Any jobs which would not have
+run during the suspense period will be unaffected, and will still run at their
+proper times.
+
+
address@hidden Exit codes, , Behaviour on laptops, Invoking
address@hidden Exit codes
address@hidden exit codes
address@hidden error conditions
address@hidden errors
+The following are the status codes returned to the operating system
+when the program terminates.
+
address@hidden @asis
address@hidden 0
+No problems.
+
address@hidden 1
+An attempt has been made to start cron but there is already a
address@hidden file. If there really is no other cron daemon
+running (this does not include invokations of mcron) then you should
+remove this file before attempting to run cron.
+
address@hidden 2
+In parsing a guile configuration file, a @code{job} command has been
+seen but the second argument is neither a procedure, list or
+string. This argument is the job's action, and needs to be specified
+in one of these forms.
+
address@hidden 3
+In parsing a guile configuration file, a @code{job} command has been
+seen but the first argument is neither a procedure, list or
+string. This argument is the job's next-time specification, and needs
+to be specified in one of these forms.
+
address@hidden 4
+An attempt to run cron has been made by a user who does not have
+permission to access the crontabs in @value{CONFIG_SPOOL_DIR}. These
+files should be readable only by root, and the cron daemon must be run
+as root.
+
address@hidden 5
+An attempt to run mcron has been made, but there are no jobs to
+schedule!
+
address@hidden 6
+The system administrator has blocked this user from using crontab with
+the files @value{CONFIG_ALLOW_FILE} and @value{CONFIG_DENY_FILE}.
+
address@hidden 7
+Crontab has been run with more than one of the arguments @code{-l},
address@hidden, @code{-e}. These are mutually exclusive options.
+
address@hidden 8
+Crontab has been run with the -u option by a user other than
+root. Only root is allowed to use this option.
+
address@hidden 9
+An invalid vixie-style time specification has been supplied.
+
address@hidden 10
+An invalid vixie-style job specification has been supplied.
+
address@hidden 11
+A bad line has been seen in /etc/crontab.
+
address@hidden 12
+The last component of the name of the program was not one of
address@hidden, @code{cron}, @code{crond} or @code{crontab}.
+
address@hidden 13
+Either none of the user's configuration directories exist, or there is a problem
+reading the files there. The configuration directories are ~/.cron
+and the directory pointed to by the @code{XDG_CONFIG_HOME} environment
+variable, or ~/.config/cron if this is not set.
+
address@hidden @item 14
address@hidden There is a problem writing to /var/cron/update. This is probably
address@hidden because the crontab program is not installed SUID root, as it should
address@hidden be.
+
address@hidden 15
+Crontab has been run without any arguments at all. There is no default
+behaviour in this case.
+
address@hidden 16
+Cron has been run by a user other than root.
+
address@hidden table
+
+
+
address@hidden Guile modules, Index, Invoking, Top
address@hidden Guile modules
+Some of the key parts of mcron are implemented as modules so they can
+be incorporated into other Guile programs, or even into C-sourced
+programs if they are linked against libguile.
+
+It may be, for example, that a program needs to perform house-keeping
+functions at certain times of the day, in which case it can spawn
+(either fork or thread) a sub-process which uses a built-in
+mcron. Another example may be a program which must sleep until some
+non-absolute time specified on the Gregorian calendar (the first day
+of next week, for example). Finally, it may be the wish of the user to
+provide a program with the functionality of mcron plus a bit extra.
+
+The core module maintains mcron's internal job lists, and provides the
+main wait-run-wait loop that is mcron's main function. It also
+introduces the facilities for accumulating a set of environment
+modifiers, which take effect when jobs run.
+
address@hidden
+* The core module:: The job list and execution loop.
+* The redirect module:: Sending output of jobs to a mail box.
+* The vixie-time module:: Parsing vixie-style time specifications.
+* The job-specifier module:: All commands for scheme configuration files.
+* The vixie-specification module:: Commands for reading vixie-style crontabs.
address@hidden menu
+
address@hidden The core module, The redirect module, Guile modules, Guile modules
address@hidden The core module
address@hidden guile module
address@hidden core module
address@hidden modules, core
+
+This module may be used by including @code{(use-modules (mcron core))}
+in a program. The main functions are @code{add-job} and
address@hidden, which allow a program to create a list of job
+specifications to run, and then to initiate the wait-run-wait loop
+firing the jobs off at the requisite times. However, before they are
+introduced two functions which manipulate the environment that takes
+effect when a job runs are defined.
+
address@hidden environment
+The environment is a set of name-value pairs which is built up
+incrementally. Each time the @code{add-job} function is called, the
+environment modifiers that have been accumulated up to that point are
+stored with the new job specification, and when the job actually runs
+these name-value pairs are used to modify the run-time environment in
+effect.
+
address@hidden procedure} append-environment-mods name value
+When a job is run make sure the environment variable @var{name} has
+the value @var{value}.
address@hidden deffn
+
address@hidden procedure} clear-environment-mods
+This procedure causes all the environment modifiers that have been
+specified so far to be forgotten.
address@hidden deffn
+
address@hidden procedure} add-job time-proc action displayable configuration-time configuration-user
+This procedure adds a job specification to the list of all jobs to
+run. @var{time-proc} should be a procedure taking exactly one argument
+which will be a UNIX time. This procedure must compute the next time
+that the job should run, and return the result. @var{action} should be
+a procedure taking no arguments, and contains the instructions that
+actually get executed whenever the job is scheduled to
+run. @var{displayable} should be a string, and is only for the use of
+humans; it can be anything which identifies or simply gives a clue as
+to the purpose or function of this job. @var{configuration-time} is
+the time from which the first invokation of this job should be
+computed. Finally, @var{configuration-user} should be the passwd entry
+for the user under whose personality the job is to run.
address@hidden deffn
+
address@hidden procedure} run-job-loop . fd-list
address@hidden file descriptors
address@hidden interrupting the mcron loop
+This procedure returns only under exceptional circumstances, but
+usually loops forever waiting for the next time to arrive when a job
+needs to run, running that job, recomputing the next run time, and
+then waiting again. However, the wait can be interrupted by data
+becoming available for reading on one of the file descriptors in the
+fd-list, if supplied. Only in this case will the procedure return to
+the calling program, which may then make modifications to the job list
+before calling the @code{run-job-loop} procedure again to resume execution of
+the mcron core.
address@hidden deffn
+
address@hidden procedure} remove-user-jobs user
+
+The argument @var{user} should be a string naming a user (his
+login name), or an integer UID, or an object representing the user's passwd
+entry. All jobs on the current job list that are scheduled to be run
+under this personality are removed from the job list.
address@hidden deffn
+
address@hidden procedure} get-schedule count
address@hidden schedule of jobs
+The argument @var{count} should be an integer value giving the number
+of time-points in the future to report that jobs will run as. Note
+that this procedure is disruptive; if @code{run-job-loop} is called
+after this procedure, the first job to run will be the one after the
+last job that was reported in the schedule report. The report itself
+is returned to the calling program as a string.
address@hidden deffn
+
address@hidden The redirect module, The vixie-time module, The core module, Guile modules
address@hidden The redirect module
address@hidden redirect module
address@hidden modules, redirect
+
+This module is introduced to a program with the command
address@hidden(use-modules (mcron redirect))}.
+
+This module provides the @code{with-mail-out} function, described
+fully in @ref{Guile Syntax}.
+
address@hidden The vixie-time module, The job-specifier module, The redirect module, Guile modules
address@hidden The vixie-time module
address@hidden vixie-time module
address@hidden modules, vixie-time
+
+This module is introduced to a program by @code{(use-modules (mcron
+vixie-time))}.
+
+This module provides a single method for converting a vixie-style time
+specification into a procedure which can be used as the
address@hidden to the core @code{add-job} procedure, or to
+the @code{job-specifier} @code{job} procedure. See @ref{Vixie Syntax}
+for full details of the allowed format for the time string.
+
address@hidden procedure} parse-vixie-time time-string
+The single argument @var{time-string} should be a string containing a
+vixie-style time specification, and the return value is the required
+procedure.
address@hidden deffn
+
+
address@hidden The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules
address@hidden The job-specifier module
address@hidden job-specifier module
address@hidden modules, job-specifier
+
+This module is introduced to a program by @code{(use-modules (mcron
+job-specifier))}.
+
+This module provides all the functions available to user's Guile
+configuration files, namely @code{range}, @code{next-year-from},
address@hidden, @code{next-month-from}, @code{next-month},
address@hidden, @code{next-day}, @code{next-hour-from},
address@hidden, @code{next-minute-from}, @code{next-minute},
address@hidden, @code{next-second},
+ and last but not least, @code{job}. See @ref{Guile Syntax} for full
+ details.
+
+Once this module is loaded, a scheme configuration file can be used to
+put jobs onto the job list simply by @code{load}ing the file.
+
address@hidden The vixie-specification module, , The job-specifier module, Guile modules
address@hidden The vixie-specification module
address@hidden vixie-specification module
address@hidden modules, vixie-specification
+
+To use this module, put the command @code{(use-modules (mcron
+vixie-specification))} into your program.
+
+This module exports a couple of functions for adding jobs to the
+internal job list according to a Vixie-style crontab file.
+
address@hidden procedure} read-vixie-port port . parse-line
+
+This procedure reads a crontab from the given port, and adds jobs to
+the job list accordingly, taking care of environment specifications
+and comments which may appear in such a file.
+
address@hidden should not normally be used, except that if you are
+parsing a (deprecated) @code{/etc/crontab} file with a slightly
+modified syntax, you may pass the value @var{parse-system-vixie-line}
+as the optional argument.
+
address@hidden deffn
+
address@hidden procedure} read-vixie-file name . parse-line
+
+This procedure attempts to open the named file, and if it fails will
+return silently. Otherwise, the behaviour is identical to
address@hidden above.
+
address@hidden deffn
+
+Once this module has been declared in a program, a crontab file can be
+used to augment the current job list with a call to
address@hidden
+
address@hidden Index, , Guile modules, Top
address@hidden Index
+
address@hidden cp
+
address@hidden
diff --git a/makefile.am b/makefile.am
index 1b27e7a..5d19aa2 100644
--- a/makefile.am
+++ b/makefile.am
@@ -1,5 +1,6 @@
## Makefile for the toplevel directory of mcron.
## Copyright (C) 2003 Dale Mellor
+## Copyright (C) 2015 Mathieu Lirzin
##
# This file is part of GNU mcron.
#
@@ -31,9 +32,9 @@ CLEANFILES = mcron.c core.scm
EXTRA_DIST = makefile.ed mcron.c.template BUGS
-info_TEXINFOS = mcron.texinfo
+info_TEXINFOS = doc/mcron.texi
-dist_man_MANS = mcron.1
+dist_man_MANS = doc/mcron.1
bin_PROGRAMS = mcron
mcron_SOURCES = mcron.c
@@ -79,6 +80,6 @@ uninstall-hook:
# Not part of formal package building, but a rule for manual use to get the
# elemental man page. Will only work once the mcron program is installed.
-mcron.1 : mcron.c
+$(dist_man_MANS): mcron.c
$(HELP2MAN) -n 'a program to run tasks at regular (or not) intervals' \
- ./mcron > mcron.1
+ ./mcron > $@
diff --git a/mcron.texinfo.in b/mcron.texinfo.in
deleted file mode 100644
index bbf8e5b..0000000
--- a/mcron.texinfo.in
+++ /dev/null
@@ -1,1335 +0,0 @@
-\input texinfo
address@hidden %**start of header
address@hidden mcron.info
address@hidden mcron @VERSION@
address@hidden %**end of header
-
address@hidden fn cp
-
address@hidden This manual is for GNU mcron (version @VERSION@), which is a
-program for running jobs at scheduled times.
-
-Copyright @copyright{} 2003, 2005, 2006, 2012, 2014 Dale Mellor
-
address@hidden
-Permission is granted to copy, distribute and/or modify this
-document under the terms of the GNU Free Documentation License,
-Version 1.3 or any later version published by the Free Software
-Foundation; with no Invariant Sections, no Front-Cover Texts and
-no Back-Cover Texts. A copy of the license is included in the
-section entitled ``GNU Free Documentation License''.
address@hidden quotation
address@hidden copying
-
-
address@hidden
-
address@hidden Individual utilities
-
address@hidden
-* mcron: (mcron). Run jobs at scheduled times.
address@hidden direntry
-
address@hidden ifinfo
-
-
address@hidden
address@hidden mcron - Mellor's cron daemon
address@hidden Dale Mellor
-
address@hidden
address@hidden 0pt plus 1fill
address@hidden @insertcopying
-
address@hidden titlepage
-
address@hidden
-
address@hidden
address@hidden Top, Introduction, (dir), (dir)
address@hidden mcron
-
-This file documents the @code{mcron} command (Mellor's cron) for
-running jobs at scheduled times.
-
address@hidden @insertcopying
address@hidden ifnottex
-
address@hidden
-* Introduction:: Introducing mcron.
-* Simple examples:: How to use mcron 99.9% of the time.
-* Syntax:: All the possibilities for configuring cron jobs.
-* Invoking:: What happens when you run the mcron command.
-* Guile modules:: Incorporating mcron into another Guile program.
-* Index:: The complete index.
-
address@hidden
- --- The Detailed Node Listing ---
-
-Simple examples
-
-* Guile Simple Examples::
-* Vixie Simple Examples::
-
-Full available syntax
-
-* Guile Syntax::
-* Extended Guile examples::
-* Vixie Syntax::
-
-Extended Guile examples
-
-* AT commands::
-* Every second Sunday::
-* Two hours every day::
-* Missing the first appointment::
-* Penultimate day of every month::
-
-Vixie
-
-* Paul Vixie's copyright::
-* Crontab file::
-* Incompatibilities with old Unices::
-
-Detailed invoking
-
-* Invoking mcron::
-* Invoking cron or crond::
-* Invoking crontab::
-* Behaviour on laptops::
-* Exit codes::
-
-Guile modules
-
-* The core module:: The job list and execution loop.
-* The redirect module:: Sending output of jobs to a mail box.
-* The vixie-time module:: Parsing vixie-style time specifications.
-* The job-specifier module:: All commands for scheme configuration files.
-* The vixie-specification module:: Commands for reading vixie-style crontabs.
-
address@hidden detailmenu
address@hidden menu
-
address@hidden Introduction, Simple examples, Top, Top
address@hidden Introducing mcron
address@hidden introduction
address@hidden mcron
-The mcron program represents a complete re-think of the cron concept
-originally found in the Berkeley and AT&T unices, and subsequently
-rationalized by Paul Vixie. The original idea was to have a daemon
-that wakes up every minute, scans a set of files under a special
-directory, and determines from those files if any shell commands
-should be executed in this minute.
-
-The new idea is to read the required command instructions, work out
-which command needs to be executed next, and then sleep until the
-inferred time has arrived. On waking the commands are run, and the
-time of the next command is computed. Furthermore, the specifications
-are written in scheme, allowing at the same time simple command
-execution instructions and very much more flexible ones to be composed
-than the original Vixie format. This has several useful advantages
-over the original idea. (Changes to user crontabs are signalled
-directly to mcron by the crontab program; cron must still scan the
-/etc/crontab file once every minute, although use of this file is
-highly discouraged and this behaviour can be turned off).
-
address@hidden advantages of mcron
address@hidden @bullet
address@hidden
-Does not consume CPU resources when not needed. Many cron daemons only
-run jobs once an hour, or even just once a day.
address@hidden
-Can easily allow for finer time-points to be specified,
-i.e. seconds. In principle this could be extended to microseconds, but
-this is not implemented.
address@hidden
-Times can be more or less regular. For example, a job that runs
-every 17 hours can be specified, or a job that runs on the first
-Sunday of every month.
address@hidden
-Times can be dynamic. Arbitrary Guile (scheme) code can be provided to
-compute the next time that a command needs to be run. This could, for
-example, take the system load into consideration.
address@hidden
-Turns out to be easy to provide complete backwards compatibility with
-Vixie cron.
address@hidden
-Each user looks after his own files in his own directory. He can use
-more than one to break up complicated cron specifications.
address@hidden
-Each user can run his own daemon. This removes the need for suid
-programs to manipulate the crontabs, and eliminates many security
-concerns that surround all existing cron programs.
address@hidden
-The user can obtain an advance schedule of all the jobs that are due
-to run.
address@hidden
-Vixie cron is implemented in 4500 lines of C code; mcron is 2000 lines
-of scheme, despite the fact that it offers many more features and much
-more flexibility, and complete compatibility with Vixie cron.
address@hidden itemize
-
-A full discussion of the design and philosophy of mcron can be found
-in the white paper at
address@hidden://www.gnu.org/software/mcron/design.html}.
-
-
address@hidden Simple examples, Syntax, Introduction, Top
address@hidden Simple examples
-The vast majority of uses of cron are sublimely simple: run a program
-every hour, or every day. With this in mind the design of mcron has
-been to allow such simple specifications to be made easily. The
-examples show how to create the command descriptions, and subsequently
-how to run mcron to make them happen.
address@hidden
-* Guile Simple Examples::
-* Vixie Simple Examples::
address@hidden menu
-
address@hidden Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples
address@hidden Guile
address@hidden guile examples
address@hidden examples, guile
address@hidden example, run a program every hour
-You have an executable @code{my-program} in your home directory, which
-you want to run every hour. Create a file @code{job.guile} in
-directory @code{~/.config/cron} (this path may be altered by the
address@hidden environment variable) with the following
-contents
-
address@hidden
-(job '(next-hour) "my-program")
address@hidden example
-
-then run the command @code{mcron}.
-
-Want the program to run fifteen minutes past the hour, every two
-hours? Edit the file to read
-
address@hidden
-(job
- '(next-minute-from
- (next-hour (range 0 24 2))
- 15)
- "my-program")
address@hidden example
-
-and run the command @code{mcron}.
-
-Or, if you are not comfortable with Scheme, you could use (and see
-also the next section)
-
address@hidden
-(job "15 */2 * * *" "my-program")
address@hidden example
-
-and run the @code{mcron} command.
-
-If you want to run other jobs, you can either add more lines to this
-file, or you can create other files in your @code{.config/cron} directory
-with the @code{.guile} extension. Alternatively, you can use any file
-you want and pass it as an argument to @code{mcron}, or even pipe the
-commands into the standard input.
-
-
address@hidden Vixie Simple Examples, , Guile Simple Examples, Simple examples
address@hidden Vixie
address@hidden examples
address@hidden examples, vixie
address@hidden vixie examples
-You have an executable @code{my-program} in your home directory, which
-you want to run every hour. Create a file @code{job.vixie} in directory
address@hidden/.cron} with the following contents
-
address@hidden
-0 * * * * my-program
address@hidden example
-
-then run the command @code{mcron}.
-
address@hidden vixie compatibility
address@hidden compatibility
-Alternatively (full compatibility with Vixie cron), set your
-environment variable @code{EDITOR} to your favorite editor, run
address@hidden -e}, put the above line into the edit buffer, save and
-exit. For this to work the @code{cron} daemon must be already running
-on your system, as root.
-
address@hidden Syntax, Invoking, Simple examples, Top
address@hidden Full available syntax
address@hidden
-* Guile Syntax::
-* Extended Guile examples::
-* Vixie Syntax::
address@hidden menu
address@hidden Guile Syntax, Extended Guile examples, Syntax, Syntax
address@hidden Guile Syntax
address@hidden Job specification
address@hidden guile syntax
address@hidden syntax, guile
address@hidden job
-In Guile-formatted configuration files each command that needs
-executing is introduced with the @code{job} function. This function
-always takes two arguments, the first a time specification, and the
-second a command specification. An optional third argument may contain
-a string to display when this job is listed in a schedule.
-
address@hidden time specification, procedure
address@hidden procedure time specification
-The first argument can be a procedure, a list, or a string. If a
-function is supplied, it must take exactly one argument, which will be
-the ``current'' time in UNIX format, and the return value of the
-function must be the time in UNIX format when this action should next
-be run. The following functions are available to facilitate the
-computation:
-
address@hidden next-second-from
address@hidden(next-second-from time . args)} without arguments this
-returns the second after the current one. With the extra arguments,
-these form a list of seconds in the minute when the action should run,
-and the function will return the time of the next allowed second
-(which may be in the next minute of the hour). @footnote{Note that
-while commands can be scheduled to run at any second, it is unlikely
-that they will be executed then but some time shortly thereafter,
-depending on the load on the system and the number of jobs that mcron
-has to start at the same time.}
-
address@hidden next-minute-from
address@hidden next-hour-from
address@hidden next-day-from
address@hidden next-week-from
address@hidden next-month-from
address@hidden next-year-from
-Similarly to @code{next-second-from}, there are also
address@hidden, @code{next-hour-from}, @code{next-day-from},
address@hidden, @code{next-month-from}, @code{next-year-from}.
-
address@hidden range
-Furthermore, the optional argument can be fulfilled by the function
address@hidden(range start end . step)}, which will provide a list of values
-from start to (but not including) end, with the step if given. For
-example @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}.
-
address@hidden next-second
address@hidden next-minute
address@hidden next-hour
address@hidden next-day
address@hidden next-week
address@hidden next-month
address@hidden next-year
address@hidden time specification, list
address@hidden list time specification
-If the first argument to the @code{job} function is a list, it is
-taken to be program code made up of the functions @code{(next-second
-. args)}, @code{(next-minute...)}, etc, where the optional arguments
-can be supplied with the @code{(range)} function above (these
-functions are analogous to the ones above except that they implicitly
-assume the current time; it is supplied by the mcron core when the
-list is eval'd).
-
address@hidden time specification
address@hidden time specification, string
address@hidden string time specification
address@hidden time specification, vixie-style
address@hidden vixie-style time specification
-If the first argument to the @code{job} function is a string, it is
-expected to be a Vixie cron-style time specification. See the section
-on Vixie syntax for this.
-
address@hidden job execution
address@hidden command execution
address@hidden execution
-The second argument to the @code{(job)} function can be either a
-string, a list, or a function. In all cases the command is executed in
-the user's home directory, under the user's own UID. If a string is
-passed, it is assumed to be shell script and is executed with the
-user's default shell. If a list is passed it is assumed to be scheme
-code and is eval'd as such. A supplied function should take exactly
-zero arguments, and will be called at the pertinent times.
-
address@hidden Sending output as e-mail
address@hidden email output
address@hidden email from guile script
address@hidden standard input to commands
address@hidden with-mail-out
-When jobs are specified in a vixie-style configuration, the command is
-broken at a percentage sign, and the stuff that comes after this is
-sent into the command's standard input. Furthermore, any output from
-the command is mailed to the user. This functionality is provided for
-compatibility with Vixie cron, but it is also available to scheme
-configuration files. The command (with-mail-out action . user) can be
-used to direct output from the action (which may be a procedure, list,
-or string) into an e-mail to the user.
-
-In the case that the action is a string, then percentage signs are
-processed as per the vixie specifications, and information is piped to
-the shell command's standard input.
-
address@hidden Setting environment variables
address@hidden environment variables in scheme
address@hidden setting environment variables
address@hidden append-environment-mods
-Also for compatibility with Vixie cron, mcron has the ability to set
-environment variables in configuration files. To access this
-functionality from a scheme configuration file, use the command
-(append-environment-mods name value), where name is the name of an
-environment variable, and value is the value put to it. A value of #f
-will remove the variable from the environment.
-
-Note that environment modifications are accumulated as the
-configuration file is processed, so when a job actually runs, its
-environment will be modified according to the modifications specified
-before the job specification in the configuration file.
-
-
address@hidden Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax
address@hidden Extended Guile examples
address@hidden examples, extended guile
address@hidden extended guile examples
-While Guile gives you flexibility to do anything, and the power to
-represent complex requirements succinctly, things are not always as
-they seem. The following examples illustrate some pitfalls, and
-demonstrate how to code around them.
-
address@hidden
-* AT commands::
-* Every second Sunday::
-* Two hours every day::
-* Missing the first appointment::
-* Penultimate day of every month::
address@hidden menu
-
address@hidden AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples
address@hidden Synthesizing ``at'' commands
address@hidden at command
-The current implementation of mcron does not provide for an at command
-(a command-line program that allows the user to specify that a job
-runs exactly once at a certain time). This can, however, be achieved.
-
-Suppose the program @code{my-program} needs to be run at midnight
-tonight. A Guile script like the following would work (but a printed
-schedule, obtained with the @code{--schedule} option, will show
-superfluous entries).
-
address@hidden
-(job '(next-day)
- (lambda () (system "my-program")
- (kill (getppid) SIGINT)))
address@hidden example
-
address@hidden Every second Sunday, Two hours every day, AT commands, Extended Guile examples
address@hidden Every second Sunday
address@hidden examples, every second sunday
-To run @code{my-program} on the second Sunday of every month, a Guile
-script like the following should suffice (it is left as an exercise to
-the student to understand how this works!).
-
address@hidden
-(job (lambda (current-time)
- (let* ((next-month (next-month-from current-time))
- (first-day (tm:wday (localtime next-month)))
- (second-sunday (if (eqv? first-day 0)
- 8
- (- 14 first-day))))
- (+ next-month (* 24 60 60 second-sunday))))
- "my-program")
address@hidden example
-
-
address@hidden Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples
address@hidden Two hours every day
address@hidden examples, two hours every day
address@hidden pitfalls, two hours every day
-Surprisingly perhaps, the following will @strong{not} have the desired
-effect.
-
address@hidden
-(job '(next-hour-from (next-day) '(1 2))
- "my-program")
address@hidden example
-
-Rather than running the my-program program at one o'clock and two
-o'clock every day, it will only run it at one o'clock. This is because
-each time mcron has to compute the next time to run the command, it
-first obtains the next day, and then finds the earliest hour in that
-day to run at. Thus, after running the command at one o'clock, the
-program first skips forwards to the next midnight (missing the two
-o'clock appointment), and then finds the next one o'clock schedule.
-
-The following simple command is the correct way to specify this
-behaviour.
-
address@hidden
-(job '(next-hour '(1 2)) "my-program")
address@hidden example
-
-
address@hidden Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples
address@hidden Missing the first appointment
address@hidden examples, missing the first appointment
address@hidden pitfalls, missing the first appointment
-The command
-
address@hidden
-(job '(next-hour-from (next-day) '(16))
- "my-program")
address@hidden example
-
-will run @code{my-program} every day at four o'clock in the
-afternoon. However, if mcron is started with this script at midday,
-the first time the command will run will be four o'clock tomorrow;
-today's appointment will be missed (one time only).
-
-The correct way to specify this requirement is simply
-
address@hidden
-(job '(next-hour '(16))
- "my-program")
address@hidden example
-
-
address@hidden Penultimate day of every month, , Missing the first appointment, Extended Guile examples
address@hidden Penultimate day of every month
address@hidden examples, penultimate day of every month
-The following will run the @code{my-program} program on the
-second-to-last day of every month.
-
address@hidden
-(job '(- (next-month-from (next-month)) (* 48 3600))
- "my-program")
address@hidden example
-
-
-
address@hidden Vixie Syntax, , Extended Guile examples, Syntax
address@hidden Vixie
address@hidden syntax, vixie
address@hidden vixie syntax
address@hidden vixie definition
address@hidden vixie compatibility
address@hidden compatibility, vixie
address@hidden that this section is definitive. If there is a difference in
-behaviour between the mcron program and this part of the manual, then
-there is a bug in the program. This section is also copied verbatim
-from Paul Vixie's documentation for his cron program, and his
-copyright notice is duly reproduced below.
-
-There are three problems with this specification.
-
address@hidden zero'th day of month
address@hidden 0'th day of month
-1. It is allowed to specify days of the month in the range 0-31. What
-does it mean to specify day 0? Looking at the Vixie source code, it
-seems that if this date appears as part of a list, it has no
-effect. However, if it appears on its own, the effect is to say
-``don't run on any particular day of the month, only take the week-day
-specification into account.'' Mcron has been coded to mimic this
-behaviour as a special case (unmodified mcron logic implies that this
-date specification would cause jobs to run on the last day of the
-previous month).
-
address@hidden thirteenth month of year
address@hidden 13th month of year
-2. Similarly to the above (but different), months of the year can be
-specified in the range 0-12. In the case of mcron (don't know what
-Vixie cron did) month 12 will cause the program to wait until January
-of the following year (but don't rely on this).
-
address@hidden shell
address@hidden environment variables, shell
address@hidden /etc/passwd
-3. Somewhere it says that cron sets the SHELL environment variable to
-/bin/sh, and elsewhere it implies that the default behaviour is for
-the user's default shell to be used to execute commands. Mcron sets
-the variable and runs the command in the user's default shell, as
-advertised by the /etc/passwd file.
-
address@hidden
-* Paul Vixie's copyright::
-* Crontab file::
-* Incompatibilities with old Unices::
address@hidden menu
-
-
address@hidden Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax
address@hidden Paul Vixie's copyright
address@hidden copyright, Paul Vixie's
address@hidden Paul Vixie's copyright
address@hidden
-Copyright 1988,1990,1993,1994 by Paul Vixie
-All rights reserved
-
-Distribute freely, except: don't remove my name from the source or
-documentation (don't take credit for my work), mark your changes (don't
-get me blamed for your possible bugs), don't alter or remove this
-notice. May be sold if buildable source is provided to buyer. No
-warrantee of any kind, express or implied, is included with this
-software; use at your own risk, responsibility for damages (if any) to
-anyone resulting from the use of this software rests entirely with the
-user.
address@hidden quotation
-
-
-
-
address@hidden Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax
address@hidden Crontab files
address@hidden crontab file
address@hidden vixie crontab file
-A @code{crontab} file contains instructions to the @code{cron} daemon
-of the general form: ``run this command at this time on this date''.
-Each user has their own crontab, and commands in any given crontab
-will be executed as the user who owns the crontab. Uucp and News will
-usually have their own crontabs, eliminating the need for explicitly
-running @code{su} as part of a cron command.
-
address@hidden comments, vixie-style
-Blank lines and leading spaces and tabs are ignored. Lines whose first
-non-space character is a pound-sign (#) are comments, and are ignored.
-Note that comments are not allowed on the same line as cron commands, since
-they will be taken to be part of the command. Similarly, comments are not
-allowed on the same line as environment variable settings.
-
-An active line in a crontab will be either an environment setting or a cron
-command. An environment setting is of the form,
-
address@hidden environment setting, vixie-style
address@hidden
-name = value
address@hidden example
-
-where the spaces around the equal-sign (=) are optional, and any
-subsequent non-leading spaces in @code{value} will be part of the
-value assigned to @code{name}. The @code{value} string may be placed
-in quotes (single or double, but matching) to preserve leading or
-trailing blanks.
-
address@hidden environment variables, SHELL
address@hidden environment variables, LOGNAME
address@hidden environment variables, HOME
address@hidden SHELL environment variable
address@hidden LOGNAME environment variable
address@hidden HOME environment variable
address@hidden /etc/passwd
-Several environment variables are set up automatically by the
address@hidden daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are
-set from the /etc/passwd line of the crontab's owner. HOME and SHELL
-may be overridden by settings in the crontab; LOGNAME may not.
-
address@hidden environment variables, USER
address@hidden USER environment variable
address@hidden BSD
-(Another note: the LOGNAME variable is sometimes called USER on BSD systems...
-on these systems, USER will be set also.) @footnote{mcron has not been
-ported to BSD, so these notes are not relevant.}
-
address@hidden environment variables, MAILTO
address@hidden MAILTO environment variable
-In addition to LOGNAME, HOME, and SHELL, @code{cron} will look at
-MAILTO if it has any reason to send mail as a result of running
-commands in ``this'' crontab. If MAILTO is defined (and non-empty),
-mail is sent to the user so named. If MAILTO is defined but empty
-(MAILTO=""), no mail will be sent. Otherwise mail is sent to the
-owner of the crontab. This option is useful if you decide on
-/bin/mail instead of /usr/lib/sendmail as your mailer when you install
-cron -- /bin/mail doesn't do aliasing, and UUCP usually doesn't read
-its mail.
-
-The format of a cron command is very much the V7 standard, with a number of
-upward-compatible extensions. Each line has five time and date fields,
-followed by a user name if this is the system crontab file,
-followed by a command. Commands are executed by @code{cron}
-when the minute, hour, and month of year fields match the current
-time, @strong{and} when at least one of the two day fields (day of month, or day of week)
-match the current time (see ``Note'' below). @code{cron} examines cron entries once every minute.
-The time and date fields are:
-
address@hidden vixie time specification fields
address@hidden fields, vixie time specification
address@hidden @columnfractions .2 .5
address@hidden Field @tab Allowed values
address@hidden ----- @tab --------------
address@hidden minute @tab 0-59
address@hidden hour @tab 0-23
address@hidden day of month @tab 0-31
address@hidden month @tab 0-12 (or names, see below)
address@hidden day of week @tab 0-7 (0 or 7 is Sun, or use names)
address@hidden multitable
-
-A field may be an asterisk (*), which always stands for ``first-last''.
-
address@hidden ranges in vixie time specifications
-Ranges of numbers are allowed. Ranges are two numbers separated
-with a hyphen. The specified range is inclusive. For example,
-8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
-and 11.
-
address@hidden lists in vixie time specifications
-Lists are allowed. A list is a set of numbers (or ranges)
-separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''.
-
address@hidden steps in vixie time specifications
-Step values can be used in conjunction with ranges. Following
-a range with ``/'' specifies skips of the number's value
-through the range. For example, ``0-23/2'' can be used in the hours
-field to specify command execution every other hour (the alternative
-in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are
-also permitted after an asterisk, so if you want to say ``every two
-hours'', just use ``*/2''.
-
address@hidden names in vixie-style time specifications
-Names can also be used for the ``month'' and ``day of week''
-fields. Use the first three letters of the particular
-day or month (case doesn't matter). Ranges or
-lists of names are not allowed. @footnote{Mcron allows any alphabetic
-characters after a name, so full names of days or months are also valid.}
-
address@hidden % character on vixie-style commands
address@hidden standard input, vixie-style
-The ``sixth'' field (the rest of the line) specifies the command to be
-run.
-The entire command portion of the line, up to a newline or %
-character, will be executed by /bin/sh or by the shell
-specified in the SHELL variable of the cronfile.
-Percent-signs (%) in the command, unless escaped with backslash
-(\\), will be changed into newline characters, and all data
-after the first % will be sent to the command as standard
-input.
-
address@hidden day specification, vixie-style
address@hidden vixie-style day specification
-Note: The day of a command's execution can be specified by two
-fields -- day of month, and day of week. If both fields are
-restricted (ie, aren't *), the command will be run when
address@hidden
-field matches the current time. For example,
-
-``30 4 1,15 * 5''
-
-would cause a command to be run at 4:30 am on the 1st and 15th of each
-month, plus every Friday.
-
-EXAMPLE CRON FILE
-
address@hidden
-# use /bin/sh to run commands, no matter what /etc/passwd says
-SHELL=/bin/sh
-# mail any output to `paul', no matter whose crontab this is
-MAILTO=paul
-#
-# run five minutes after midnight, every day
-5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
-# run at 2:15pm on the first of every month -- output mailed to paul
-15 14 1 * * $HOME/bin/monthly
-# run at 10 pm on weekdays, annoy Joe
-0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
-23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
-5 4 * * sun echo "run at 5 after 4 every sunday"
address@hidden example
-
address@hidden Incompatibilities with old Unices, , Crontab file, Vixie Syntax
address@hidden Extensions and incompatibilities
address@hidden incompatibilities with old Unices
address@hidden extensions, vixie over old Unices
-This section lists differences between Paul Vixie's cron and the
-olde-worlde BSD and AT&T programs, for the benefit of system
-administrators and users who are upgrading all the way.
-
address@hidden @bullet
address@hidden
address@hidden day 7
-When specifying day of week, both day 0 and day 7 will be considered Sunday.
-BSD and AT&T seem to disagree about this.
-
address@hidden
-Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would
-be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY.
-
address@hidden
-Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
-
address@hidden
-Names of months or days of the week can be specified by name.
-
address@hidden
-Environment variables can be set in the crontab. In BSD or AT&T, the
-environment handed to child processes is basically the one from /etc/rc.
-
address@hidden
-Command output is mailed to the crontab owner (BSD can't do this), can be
-mailed to a person other than the crontab owner (SysV can't do this), or the
-feature can be turned off and no mail will be sent at all (SysV can't do this
-either).
-
address@hidden itemize
-
-
address@hidden Invoking, Guile modules, Syntax, Top
address@hidden Detailed invoking
address@hidden invoking
address@hidden personality
address@hidden mcron program
address@hidden cron program
address@hidden crond program
address@hidden crontab program
-The program adopts one of three different personalities depending on
-the name used to invoke it. In a standard installation, the program is
-installed in the system under the names mcron, cron and crontab
-(installed SUID).
-
-The recommended way to invoke the program is via the mcron personality
-described in the next section. The program can also be run as cron by
-root, and by the SUID program crontab by individual users to gain
-backwards compatibility with Vixie cron. However, due to the fact that
-this daemon process is shared by, and under control of, all the users
-of the system it is possible (though very unlikely) that it may become
-unusable, hence the recommendation to use the mcron personality.
-
address@hidden deprecated, vixie personality
-Furthermore, the Vixie personality is considered deprecated by this
-author (it offers not a single advantage over the mcron personality,
-and bloats the code by a factor of three). It is unlikely that this
-personality will ever actually go away, but the program may in future
-be split into two distinct parts, and new developments will only take
-place in the part which implements the mcron personality.
-
-
-
address@hidden
-* Invoking mcron::
-* Invoking cron or crond::
-* Invoking crontab::
-* Behaviour on laptops::
-* Exit codes::
address@hidden menu
-
address@hidden Invoking mcron, Invoking cron or crond, Invoking, Invoking
address@hidden Invoking mcron
address@hidden invoking mcron
address@hidden mcron options
address@hidden mcron arguments
address@hidden command line, mcron
address@hidden mcron command line
-Mcron should be run by the user who wants to schedule his jobs. It
-may be made a background job using the facilities of the shell. The
-basic command is @code{mcron [OPTION ...] [file ...]} which has the
-effect of reading all the configuration files specified (subject to
-the options) and then waiting until it is time to execute some
-command. If no files are given on the command line, then mcron will
-look in the user's cron configuration directories: these are ~/.cron
-(deprecated), the directory indicated by the @code{XDG_CONFIG_HOME}
-environment variable, or ~/.config/cron if this variable is not set.
-In any case, files which end in the extension .vixie or .vix will be
-assumed to contain Vixie-style crontabs, and files ending .guile or
-.gle will be assumed to contain scheme code and will be executed as
-such; ANY OTHER FILES WILL BE IGNORED - specify a file name of ``-''
-and then pipe the files into the standard input if you really want to
-read them, possibly using the @code{stdin} option to specify the type
-of file.
-
-The program accepts the following options.
-
address@hidden @option
address@hidden -s count
address@hidden --schedule=count
address@hidden printout of jobs schedule
address@hidden schedule of jobs, listing
address@hidden options, schedule
address@hidden options, -s
address@hidden -s option
address@hidden --schedule option
-With this option specified no commands are run. Instead, the program
-computes the times the commands would be run and prints the
-information to the screen, and then immediately exits.
-
-The count indicates the number of commands to display.
-
address@hidden daemon option
address@hidden options, daemon
address@hidden options, -d
address@hidden -d option
address@hidden --daemon option
address@hidden -d
address@hidden --daemon
-With this option the program will detach itself from the controlling
-terminal and run as a daemon process.
-
address@hidden stdin option
address@hidden options, stdin
address@hidden options, -i
address@hidden -i option
address@hidden --stdin option
address@hidden standard input, configuring from
address@hidden configuring from standard input
address@hidden -i (vixie|guile)
address@hidden --stdin=(vixie|guile)
-This option is used to indicate whether the configuration information
-being passed on the standard input is in Vixie format or Guile
-format. Guile is the default.
-
address@hidden -v option
address@hidden --version option
address@hidden options, -v
address@hidden options, version
address@hidden -v
address@hidden --version
-This option causes a message to be printed on the standard output with
-information about the version and copyright for the current program.
-
address@hidden -h option
address@hidden --help option
address@hidden options, -h
address@hidden options, --help
address@hidden -h
address@hidden --help
-This causes a short but complete usage message to be displayed on
-standard output.
-
address@hidden table
-
address@hidden Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking
address@hidden Invoking cron or crond
address@hidden cron, invokation
address@hidden invoking cron
address@hidden crond, invokation
address@hidden invoking crond
address@hidden @CONFIG_SPOOL_DIR@
address@hidden @CONFIG_SOCKET_FILE@
-NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or
address@hidden, and @code{crontab} PROGRAMS HAVE BEEN INSTALLED BY THE
-SYSTEM ADMINISTRATOR.
-
-If the program runs by the name of @code{cron} or @code{crond}, then
-it will read all the files in @address@hidden@} (which should only
-be readable by root) and the file @code{/etc/crontab}, and then
-detaches itself from the terminal to live forever as a daemon
-process. Additionally, it creates a UNIX socket at
address@hidden@address@hidden, and listens for messages sent to that socket
-consisting of a user name whose crontabs have been changed. In this
-case, the program will re-read that user's crontab. This is for
-correct functioning with the crontab program.
-
-Further, if the @code{--noetc} option was not used, a job is scheduled
-to run every minute to check if /etc/crontab has been modified
-recently. If so, this file will also be re-read.
-
-The options which may be used with this program are as follows.
-
address@hidden @option
-
address@hidden -v option
address@hidden --version option
address@hidden options, -v
address@hidden options, version
address@hidden -v
address@hidden --version
-This option causes a message to be printed on the standard output with
-information about the version and copyright for the current program.
-
address@hidden -h option
address@hidden --help option
address@hidden options, -h
address@hidden options, --help
address@hidden -h
address@hidden --help
-This causes a short but complete usage message to be displayed on
-standard output.
-
address@hidden -s [count]
address@hidden --schedule[=count]
address@hidden printout of jobs schedule
address@hidden schedule of jobs, listing
address@hidden options, schedule
address@hidden options, -s
address@hidden -s option
address@hidden --schedule option
-With this option specified no commands are run. Instead, the program
-computes the times the commands would be run and prints the
-information to the screen, and then immediately exits.
-
-The count, if supplied, indicates the number of commands to
-display. The default value is 8.
-
address@hidden -n option
address@hidden --noetc option
address@hidden options, -n
address@hidden options, --noetc
address@hidden -n
address@hidden --noetc
-This tells cron not to add a job to the system which wakes up every
-minute to check for modifications to @code{/etc/crontab}. It is
-recommended that this option be used (and further that the
address@hidden/etc/crontab} file be taken off the system altogether!)
-
address@hidden table
-
address@hidden Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking
address@hidden Invoking crontab
address@hidden crontab, invoking
address@hidden invoking crontab
-This program is run by individual users to inspect or modify their
-crontab files. If a change is made to the file, then the root daemon
-process will be given a kick, and will immediately read the new
-configuration. A warning will be issued to standard output if it
-appears that a cron daemon is not running.
-
-The command is used as
-
address@hidden [-u user] file}
-
-or
-
address@hidden [-u user] ( -l | -e | -r )}
-
-Only the root user can use the -u option, to specify the manipulation
-of another user's crontab file. In the first instance, the entire
-crontab file of the user is replaced with the contents of the
-specified file, or standard input if the file is ``-''.
-
-In the latter case, the program behaves according to which of the
-(mutually exclusive) options was given (note that the long options are
-an mcron extension).
-
address@hidden @option
-
address@hidden -l option
address@hidden list option, crontab
address@hidden options, -l
address@hidden options, --list
address@hidden viewing a crontab
address@hidden listing a crontab
address@hidden -l
address@hidden --list
-Print the user's crontab file to the standard output, and exit.
-
address@hidden -r option
address@hidden remove option
address@hidden options, -r
address@hidden options, --remove
address@hidden deleting a crontab
address@hidden removing a crontab
address@hidden -r
address@hidden --remove
-Delete the user's crontab file, and exit.
-
address@hidden -e option
address@hidden edit option
address@hidden options, -e
address@hidden options, --edit
address@hidden editing a crontab
address@hidden creating a crontab
address@hidden -e
address@hidden --edit
-Using the editor specified in the user's VISUAL or EDITOR environment
-variables, allow the user to edit his crontab. Once the user exits the
-editor, the crontab is checked for parseability, and if it is okay
-then it is installed as the user's new crontab and the daemon is
-notified that a change has taken place, so that the new file will
-become immediately effective.
-
address@hidden table
-
-
address@hidden Behaviour on laptops, Exit codes, Invoking crontab, Invoking
address@hidden Behaviour on laptops
address@hidden laptops
address@hidden power suspend
-While mcron has not been designed to work anachronistically, the behaviour of
-mcron when a laptop emerges from a suspended state is well defined, and the
-following description explains what happens in this situation.
-
-When a laptop awakes from a suspended state, all jobs which would have run while
-the laptop was suspended will run exactly once immediately (and simultaneously)
-when the laptop awakes, and then the next time that those jobs run will be
-computed based on the time the laptop was awoken. Any jobs which would not have
-run during the suspense period will be unaffected, and will still run at their
-proper times.
-
-
address@hidden Exit codes, , Behaviour on laptops, Invoking
address@hidden Exit codes
address@hidden exit codes
address@hidden error conditions
address@hidden errors
-The following are the status codes returned to the operating system
-when the program terminates.
-
address@hidden @asis
address@hidden 0
-No problems.
-
address@hidden 1
-An attempt has been made to start cron but there is already a
address@hidden@ file. If there really is no other cron daemon
-running (this does not include invokations of mcron) then you should
-remove this file before attempting to run cron.
-
address@hidden 2
-In parsing a guile configuration file, a @code{job} command has been
-seen but the second argument is neither a procedure, list or
-string. This argument is the job's action, and needs to be specified
-in one of these forms.
-
address@hidden 3
-In parsing a guile configuration file, a @code{job} command has been
-seen but the first argument is neither a procedure, list or
-string. This argument is the job's next-time specification, and needs
-to be specified in one of these forms.
-
address@hidden 4
-An attempt to run cron has been made by a user who does not have
-permission to access the crontabs in @address@hidden These files
-should be readable only by root, and the cron daemon must be run as
-root.
-
address@hidden 5
-An attempt to run mcron has been made, but there are no jobs to
-schedule!
-
address@hidden 6
-The system administrator has blocked this user from using crontab with
-the files @CONFIG_ALLOW_FILE@ and @address@hidden
-
address@hidden 7
-Crontab has been run with more than one of the arguments @code{-l},
address@hidden, @code{-e}. These are mutually exclusive options.
-
address@hidden 8
-Crontab has been run with the -u option by a user other than
-root. Only root is allowed to use this option.
-
address@hidden 9
-An invalid vixie-style time specification has been supplied.
-
address@hidden 10
-An invalid vixie-style job specification has been supplied.
-
address@hidden 11
-A bad line has been seen in /etc/crontab.
-
address@hidden 12
-The last component of the name of the program was not one of
address@hidden, @code{cron}, @code{crond} or @code{crontab}.
-
address@hidden 13
-Either none of the user's configuration directories exist, or there is a problem
-reading the files there. The configuration directories are ~/.cron
-and the directory pointed to by the @code{XDG_CONFIG_HOME} environment
-variable, or ~/.config/cron if this is not set.
-
address@hidden @item 14
address@hidden There is a problem writing to /var/cron/update. This is probably
address@hidden because the crontab program is not installed SUID root, as it should
address@hidden be.
-
address@hidden 15
-Crontab has been run without any arguments at all. There is no default
-behaviour in this case.
-
address@hidden 16
-Cron has been run by a user other than root.
-
address@hidden table
-
-
-
address@hidden Guile modules, Index, Invoking, Top
address@hidden Guile modules
-Some of the key parts of mcron are implemented as modules so they can
-be incorporated into other Guile programs, or even into C-sourced
-programs if they are linked against libguile.
-
-It may be, for example, that a program needs to perform house-keeping
-functions at certain times of the day, in which case it can spawn
-(either fork or thread) a sub-process which uses a built-in
-mcron. Another example may be a program which must sleep until some
-non-absolute time specified on the Gregorian calendar (the first day
-of next week, for example). Finally, it may be the wish of the user to
-provide a program with the functionality of mcron plus a bit extra.
-
-The core module maintains mcron's internal job lists, and provides the
-main wait-run-wait loop that is mcron's main function. It also
-introduces the facilities for accumulating a set of environment
-modifiers, which take effect when jobs run.
-
address@hidden
-* The core module:: The job list and execution loop.
-* The redirect module:: Sending output of jobs to a mail box.
-* The vixie-time module:: Parsing vixie-style time specifications.
-* The job-specifier module:: All commands for scheme configuration files.
-* The vixie-specification module:: Commands for reading vixie-style crontabs.
address@hidden menu
-
address@hidden The core module, The redirect module, Guile modules, Guile modules
address@hidden The core module
address@hidden guile module
address@hidden core module
address@hidden modules, core
-
-This module may be used by including @code{(use-modules (mcron core))}
-in a program. The main functions are @code{add-job} and
address@hidden, which allow a program to create a list of job
-specifications to run, and then to initiate the wait-run-wait loop
-firing the jobs off at the requisite times. However, before they are
-introduced two functions which manipulate the environment that takes
-effect when a job runs are defined.
-
address@hidden environment
-The environment is a set of name-value pairs which is built up
-incrementally. Each time the @code{add-job} function is called, the
-environment modifiers that have been accumulated up to that point are
-stored with the new job specification, and when the job actually runs
-these name-value pairs are used to modify the run-time environment in
-effect.
-
address@hidden procedure} append-environment-mods name value
-When a job is run make sure the environment variable @var{name} has
-the value @var{value}.
address@hidden deffn
-
address@hidden procedure} clear-environment-mods
-This procedure causes all the environment modifiers that have been
-specified so far to be forgotten.
address@hidden deffn
-
address@hidden procedure} add-job time-proc action displayable configuration-time configuration-user
-This procedure adds a job specification to the list of all jobs to
-run. @var{time-proc} should be a procedure taking exactly one argument
-which will be a UNIX time. This procedure must compute the next time
-that the job should run, and return the result. @var{action} should be
-a procedure taking no arguments, and contains the instructions that
-actually get executed whenever the job is scheduled to
-run. @var{displayable} should be a string, and is only for the use of
-humans; it can be anything which identifies or simply gives a clue as
-to the purpose or function of this job. @var{configuration-time} is
-the time from which the first invokation of this job should be
-computed. Finally, @var{configuration-user} should be the passwd entry
-for the user under whose personality the job is to run.
address@hidden deffn
-
address@hidden procedure} run-job-loop . fd-list
address@hidden file descriptors
address@hidden interrupting the mcron loop
-This procedure returns only under exceptional circumstances, but
-usually loops forever waiting for the next time to arrive when a job
-needs to run, running that job, recomputing the next run time, and
-then waiting again. However, the wait can be interrupted by data
-becoming available for reading on one of the file descriptors in the
-fd-list, if supplied. Only in this case will the procedure return to
-the calling program, which may then make modifications to the job list
-before calling the @code{run-job-loop} procedure again to resume execution of
-the mcron core.
address@hidden deffn
-
address@hidden procedure} remove-user-jobs user
-
-The argument @var{user} should be a string naming a user (his
-login name), or an integer UID, or an object representing the user's passwd
-entry. All jobs on the current job list that are scheduled to be run
-under this personality are removed from the job list.
address@hidden deffn
-
address@hidden procedure} get-schedule count
address@hidden schedule of jobs
-The argument @var{count} should be an integer value giving the number
-of time-points in the future to report that jobs will run as. Note
-that this procedure is disruptive; if @code{run-job-loop} is called
-after this procedure, the first job to run will be the one after the
-last job that was reported in the schedule report. The report itself
-is returned to the calling program as a string.
address@hidden deffn
-
address@hidden The redirect module, The vixie-time module, The core module, Guile modules
address@hidden The redirect module
address@hidden redirect module
address@hidden modules, redirect
-
-This module is introduced to a program with the command
address@hidden(use-modules (mcron redirect))}.
-
-This module provides the @code{with-mail-out} function, described
-fully in @ref{Guile Syntax}.
-
address@hidden The vixie-time module, The job-specifier module, The redirect module, Guile modules
address@hidden The vixie-time module
address@hidden vixie-time module
address@hidden modules, vixie-time
-
-This module is introduced to a program by @code{(use-modules (mcron
-vixie-time))}.
-
-This module provides a single method for converting a vixie-style time
-specification into a procedure which can be used as the
address@hidden to the core @code{add-job} procedure, or to
-the @code{job-specifier} @code{job} procedure. See @ref{Vixie Syntax}
-for full details of the allowed format for the time string.
-
address@hidden procedure} parse-vixie-time time-string
-The single argument @var{time-string} should be a string containing a
-vixie-style time specification, and the return value is the required
-procedure.
address@hidden deffn
-
-
address@hidden The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules
address@hidden The job-specifier module
address@hidden job-specifier module
address@hidden modules, job-specifier
-
-This module is introduced to a program by @code{(use-modules (mcron
-job-specifier))}.
-
-This module provides all the functions available to user's Guile
-configuration files, namely @code{range}, @code{next-year-from},
address@hidden, @code{next-month-from}, @code{next-month},
address@hidden, @code{next-day}, @code{next-hour-from},
address@hidden, @code{next-minute-from}, @code{next-minute},
address@hidden, @code{next-second},
- and last but not least, @code{job}. See @ref{Guile Syntax} for full
- details.
-
-Once this module is loaded, a scheme configuration file can be used to
-put jobs onto the job list simply by @code{load}ing the file.
-
address@hidden The vixie-specification module, , The job-specifier module, Guile modules
address@hidden The vixie-specification module
address@hidden vixie-specification module
address@hidden modules, vixie-specification
-
-To use this module, put the command @code{(use-modules (mcron
-vixie-specification))} into your program.
-
-This module exports a couple of functions for adding jobs to the
-internal job list according to a Vixie-style crontab file.
-
address@hidden procedure} read-vixie-port port . parse-line
-
-This procedure reads a crontab from the given port, and adds jobs to
-the job list accordingly, taking care of environment specifications
-and comments which may appear in such a file.
-
address@hidden should not normally be used, except that if you are
-parsing a (deprecated) @code{/etc/crontab} file with a slightly
-modified syntax, you may pass the value @var{parse-system-vixie-line}
-as the optional argument.
-
address@hidden deffn
-
address@hidden procedure} read-vixie-file name . parse-line
-
-This procedure attempts to open the named file, and if it fails will
-return silently. Otherwise, the behaviour is identical to
address@hidden above.
-
address@hidden deffn
-
-Once this module has been declared in a program, a crontab file can be
-used to augment the current job list with a call to
address@hidden
-
address@hidden Index, , Guile modules, Top
address@hidden Index
-
address@hidden cp
-
address@hidden
--
2.1.4