Merge branch 'devel'

3 files changed, 1854 insertions, 0 deletions

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 @@
+@set CONFIG_SOCKET_FILE @CONFIG_SOCKET_FILE@
+@set CONFIG_SPOOL_DIR @CONFIG_SPOOL_DIR@
+@set CONFIG_PID_FILE @CONFIG_PID_FILE@
+@set CONFIG_ALLOW_FILE @CONFIG_ALLOW_FILE@
+@set CONFIG_DENY_FILE @CONFIG_DENY_FILE@
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 0000000..9c3bbe5
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification.  Examples
+of transparent image formats include PNG, XCF and
+JPG@.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  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''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/doc/mcron.texi b/doc/mcron.texi
new file mode 100644
index 0000000..a59505d
--- /dev/null
+++ b/doc/mcron.texi
@@ -0,0 +1,1344 @@
+\input texinfo
+@c %**start of header
+@setfilename mcron.info
+@include config.texi
+@include version.texi
+@settitle mcron @value{VERSION}
+@c %**end of header
+
+@syncodeindex fn cp
+
+@copying 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
+
+@quotation
+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''.
+@end quotation
+@end copying
+
+
+@ifinfo
+
+@dircategory Individual utilities
+
+@direntry
+* mcron: (mcron).       Run jobs at scheduled times.
+@end direntry
+
+@end ifinfo
+
+
+@titlepage
+@title mcron - Mellor's cron daemon
+@author Dale Mellor
+
+@page
+@vskip 0pt plus 1fill
+@c @insertcopying
+
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top mcron
+
+This file documents the @code{mcron} command (Mellor's cron) for
+running jobs at scheduled times.
+
+@c @insertcopying
+@end ifnottex
+
+@menu
+* Introduction::                Introducing mcron.
+* Simple examples::             How to use mcron 99.9% of the time.
+* Syntax::                      All the possibilities for configuring cron jobs.
+* Invoking::                    What happens when you run the mcron command.
+* Guile modules::               Incorporating mcron into another Guile program.
+* GNU Free Documentation License::  The license of this manual.
+* Index::                       The complete index.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Simple examples
+
+* Guile Simple Examples::
+* Vixie Simple Examples::
+
+Full available syntax
+
+* Guile Syntax::
+* Extended Guile examples::
+* Vixie Syntax::
+
+Extended Guile examples
+
+* AT commands::
+* Every second Sunday::
+* Two hours every day::
+* Missing the first appointment::
+* Penultimate day of every month::
+
+Vixie
+
+* Paul Vixie's copyright::
+* Crontab file::
+* Incompatibilities with old Unices::
+
+Detailed invoking
+
+* Invoking mcron::
+* Invoking cron or crond::
+* Invoking crontab::
+* Behaviour on laptops::
+* Exit codes::
+
+Guile modules
+
+* The base module::             The job list and execution loop.
+* The redirect module::         Sending output of jobs to a mail box.
+* The vixie-time module::       Parsing vixie-style time specifications.
+* The job-specifier module::    All commands for scheme configuration files.
+* The vixie-specification module::  Commands for reading vixie-style crontabs.
+
+@end detailmenu
+@end menu
+
+@node Introduction, Simple examples, Top, Top
+@chapter Introducing mcron
+@cindex introduction
+@cindex mcron
+The mcron program represents a complete re-think of the cron concept
+originally found in the Berkeley and AT&T unices, and subsequently
+rationalized by Paul Vixie.  The original idea was to have a daemon
+that wakes up every minute, scans a set of files under a special
+directory, and determines from those files if any shell commands
+should be executed in this minute.
+
+The new idea is to read the required command instructions, work out
+which command needs to be executed next, and then sleep until the
+inferred time has arrived.  On waking the commands are run, and the
+time of the next command is computed.  Furthermore, the specifications
+are written in scheme, allowing at the same time simple command
+execution instructions and very much more flexible ones to be composed
+than the original Vixie format.  This has several useful advantages
+over the original idea.  (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).
+
+@cindex advantages of mcron
+@itemize @bullet
+@item
+Does not consume CPU resources when not needed.  Many cron daemons only
+run jobs once an hour, or even just once a day.
+@item
+Can easily allow for finer time-points to be specified,
+i.e. seconds.  In principle this could be extended to microseconds, but
+this is not implemented.
+@item
+Times can be more or less regular.  For example, a job that runs
+every 17 hours can be specified, or a job that runs on the first
+Sunday of every month.
+@item
+Times can be dynamic.  Arbitrary Guile (scheme) code can be provided to
+compute the next time that a command needs to be run.  This could, for
+example, take the system load into consideration.
+@item
+Turns out to be easy to provide complete backwards compatibility with
+Vixie cron.
+@item
+Each user looks after his own files in his own directory.  He can use
+more than one to break up complicated cron specifications.
+@item
+Each user can run his own daemon.  This removes the need for suid
+programs to manipulate the crontabs, and eliminates many security
+concerns that surround all existing cron programs.
+@item
+The user can obtain an advance schedule of all the jobs that are due
+to run.
+@item
+Vixie cron is implemented in 4500 lines of C code; mcron is 2000 lines
+of scheme, despite the fact that it offers many more features and much
+more flexibility, and complete compatibility with Vixie cron.
+@end itemize
+
+A full discussion of the design and philosophy of mcron can be found
+in the white paper at
+@url{http://www.gnu.org/software/mcron/design.html}.
+
+
+@node Simple examples, Syntax, Introduction, Top
+@chapter Simple examples
+The vast majority of uses of cron are sublimely simple: run a program
+every hour, or every day.  With this in mind the design of mcron has
+been to allow such simple specifications to be made easily.  The
+examples show how to create the command descriptions, and subsequently
+how to run mcron to make them happen.
+@menu
+* Guile Simple Examples::
+* Vixie Simple Examples::
+@end menu
+
+@node Guile Simple Examples, Vixie Simple Examples, Simple examples, Simple examples
+@section Guile
+@cindex guile examples
+@cindex examples, guile
+@cindex example, run a program every hour
+You have an executable @code{my-program} in your home directory, which
+you want to run every hour.  Create a file @code{job.guile} in
+directory @code{~/.config/cron} (this path may be altered by the
+@code{$XDG_CONFIG_HOME} environment variable) with the following
+contents
+
+@example
+(job '(next-hour) "my-program")
+@end example
+
+then run the command @code{mcron}.
+
+Want the program to run fifteen minutes past the hour, every two
+hours? Edit the file to read
+
+@example
+(job
+   '(next-minute-from
+      (next-hour (range 0 24 2))
+      15)
+   "my-program")
+@end example
+
+and run the command @code{mcron}.
+
+Or, if you are not comfortable with Scheme, you could use (and see
+also the next section)
+
+@example
+(job "15 */2 * * *" "my-program")
+@end example
+
+and run the @code{mcron} command.
+
+If you want to run other jobs, you can either add more lines to this
+file, or you can create other files in your @code{.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.
+
+
+@node Vixie Simple Examples,  , Guile Simple Examples, Simple examples
+@section Vixie
+@cindex examples
+@cindex examples, vixie
+@cindex vixie examples
+You have an executable @code{my-program} in your home directory, which
+you want to run every hour.  Create a file @code{job.vixie} in directory
+@code{~/.cron} with the following contents
+
+@example
+0 * * * * my-program
+@end example
+
+then run the command @code{mcron}.
+
+@cindex vixie compatibility
+@cindex compatibility
+Alternatively (full compatibility with Vixie cron), set your
+environment variable @code{EDITOR} to your favorite editor, run
+@code{crontab -e}, put the above line into the edit buffer, save and
+exit.  For this to work the @code{cron} daemon must be already running
+on your system, as root.
+
+@node Syntax, Invoking, Simple examples, Top
+@chapter Full available syntax
+@menu
+* Guile Syntax::
+* Extended Guile examples::
+* Vixie Syntax::
+@end menu
+@node Guile Syntax, Extended Guile examples, Syntax, Syntax
+@section Guile Syntax
+@subsection Job specification
+@cindex guile syntax
+@cindex syntax, guile
+@findex job
+In Guile-formatted configuration files each command that needs executing is
+introduced with the @code{job} function.  This function always takes two
+arguments, the first a time specification, and the second a command
+specification.  An optional third argument may contain a string to display
+when this job is listed in a schedule.  Additionally a @var{user} keyword
+argument can be supplied to use a different user than the one defined in
+@code{configuration-user} global variable.
+
+@cindex time specification, procedure
+@cindex procedure time specification
+The first argument can be a procedure, a list, or a string.  If a
+function is supplied, it must take exactly one argument, which will be
+the ``current'' time in UNIX format, and the return value of the
+function must be the time in UNIX format when this action should next
+be run.  The following functions are available to facilitate the
+computation:
+
+@findex next-second-from
+@code{(next-second-from time . args)} without arguments this
+returns the second after the current one.  With the extra arguments,
+these form a list of seconds in the minute when the action should run,
+and the function will return the time of the next allowed second
+(which may be in the next minute of the hour).  @footnote{Note that
+while commands can be scheduled to run at any second, it is unlikely
+that they will be executed then but some time shortly thereafter,
+depending on the load on the system and the number of jobs that mcron
+has to start at the same time.}
+
+@findex next-minute-from
+@findex next-hour-from
+@findex next-day-from
+@findex next-week-from
+@findex next-month-from
+@findex next-year-from
+Similarly to @code{next-second-from}, there are also
+@code{next-minute-from}, @code{next-hour-from}, @code{next-day-from},
+@code{next-week-from}, @code{next-month-from}, @code{next-year-from}.
+
+@findex range
+Furthermore, the optional argument can be fulfilled by the function
+@code{(range start end . step)}, which will provide a list of values
+from start to (but not including) end, with the step if given.  For
+example @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}.
+
+@findex next-second
+@findex next-minute
+@findex next-hour
+@findex next-day
+@findex next-week
+@findex next-month
+@findex next-year
+@cindex time specification, list
+@cindex list time specification
+If the first argument to the @code{job} function is a list, it is
+taken to be program code made up of the functions @code{(next-second
+. args)}, @code{(next-minute...)}, etc, where the optional arguments
+can be supplied with the @code{(range)} function above (these
+functions are analogous to the ones above except that they implicitly
+assume the current time; it is supplied by the mcron base when the
+list is eval'd).
+
+@cindex time specification
+@cindex time specification, string
+@cindex string time specification
+@cindex time specification, vixie-style
+@cindex vixie-style time specification
+If the first argument to the @code{job} function is a string, it is
+expected to be a Vixie cron-style time specification.  See the section
+on Vixie syntax for this.
+
+@cindex job execution
+@cindex command execution
+@cindex execution
+The second argument to the @code{(job)} function can be either a string, a
+list, or a function.  The command is executed in the home directory and with
+the UID of @var{user}.  If a string is passed, it is assumed to be shell
+script and is executed with the user's default shell.  If a list is passed it
+is assumed to be scheme code and is eval'd as such.  A supplied function
+should take exactly zero arguments, and will be called at the pertinent times.
+
+@subsection Sending output as e-mail
+@cindex email output
+@cindex email from guile script
+@cindex standard input to commands
+@findex with-mail-out
+When jobs are specified in a vixie-style configuration, the command is
+broken at a percentage sign, and the stuff that comes after this is
+sent into the command's standard input.  Furthermore, any output from
+the command is mailed to the user.  This functionality is provided for
+compatibility with Vixie cron, but it is also available to scheme
+configuration files.  The command (with-mail-out action . user) can be
+used to direct output from the action (which may be a procedure, list,
+or string) into an e-mail to the user.
+
+In the case that the action is a string, then percentage signs are
+processed as per the vixie specifications, and information is piped to
+the shell command's standard input.
+
+@subsection Setting environment variables
+@cindex environment variables in scheme
+@cindex setting environment variables
+@findex append-environment-mods
+Also for compatibility with Vixie cron, mcron has the ability to set
+environment variables in configuration files.  To access this
+functionality from a scheme configuration file, use the command
+(append-environment-mods name value), where name is the name of an
+environment variable, and value is the value put to it.  A value of #f
+will remove the variable from the environment.
+
+Note that environment modifications are accumulated as the
+configuration file is processed, so when a job actually runs, its
+environment will be modified according to the modifications specified
+before the job specification in the configuration file.
+
+
+@node Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax
+@section Extended Guile examples
+@cindex examples, extended guile
+@cindex extended guile examples
+While Guile gives you flexibility to do anything, and the power to
+represent complex requirements succinctly, things are not always as
+they seem.  The following examples illustrate some pitfalls, and
+demonstrate how to code around them.
+
+@menu
+* AT commands::
+* Every second Sunday::
+* Two hours every day::
+* Missing the first appointment::
+* Penultimate day of every month::
+@end menu
+
+@node AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples
+@subsection Synthesizing ``at'' commands
+@cindex at command
+The current implementation of mcron does not provide for an at command
+(a command-line program that allows the user to specify that a job
+runs exactly once at a certain time).  This can, however, be achieved.
+
+Suppose the program @code{my-program} needs to be run at midnight
+tonight.  A Guile script like the following would work (but a printed
+schedule, obtained with the @code{--schedule} option, will show
+superfluous entries).
+
+@example
+(job '(next-day)
+     (lambda () (system "my-program")
+                (kill (getppid) SIGINT)))
+@end example
+
+@node Every second Sunday, Two hours every day, AT commands, Extended Guile examples
+@subsection Every second Sunday
+@cindex examples, every second sunday
+To run @code{my-program} on the second Sunday of every month, a Guile
+script like the following should suffice (it is left as an exercise to
+the student to understand how this works!).
+
+@example
+(job (lambda (current-time)
+       (let* ((next-month (next-month-from current-time))
+              (first-day (tm:wday (localtime next-month)))
+              (second-sunday (if (eqv? first-day 0)
+                                 8
+                                 (- 14 first-day))))
+         (+ next-month (* 24 60 60 second-sunday))))
+     "my-program")
+@end example
+
+
+@node Two hours every day, Missing the first appointment, Every second Sunday, Extended Guile examples
+@subsection Two hours every day
+@cindex examples, two hours every day
+@cindex pitfalls, two hours every day
+Surprisingly perhaps, the following will @strong{not} have the desired
+effect.
+
+@example
+(job '(next-hour-from (next-day) '(1 2))
+     "my-program")
+@end example
+
+Rather than running the my-program program at one o'clock and two
+o'clock every day, it will only run it at one o'clock.  This is because
+each time mcron has to compute the next time to run the command, it
+first obtains the next day, and then finds the earliest hour in that
+day to run at.  Thus, after running the command at one o'clock, the
+program first skips forwards to the next midnight (missing the two
+o'clock appointment), and then finds the next one o'clock schedule.
+
+The following simple command is the correct way to specify this
+behaviour.
+
+@example
+(job '(next-hour '(1 2)) "my-program")
+@end example
+
+
+@node Missing the first appointment, Penultimate day of every month, Two hours every day, Extended Guile examples
+@subsection Missing the first appointment
+@cindex examples, missing the first appointment
+@cindex pitfalls, missing the first appointment
+The command
+
+@example
+(job '(next-hour-from (next-day) '(16))
+     "my-program")
+@end example
+
+will run @code{my-program} every day at four o'clock in the
+afternoon.  However, if mcron is started with this script at midday,
+the first time the command will run will be four o'clock tomorrow;
+today's appointment will be missed (one time only).
+
+The correct way to specify this requirement is simply
+
+@example
+(job '(next-hour '(16))
+     "my-program")
+@end example
+
+
+@node Penultimate day of every month,  , Missing the first appointment, Extended Guile examples
+@subsection Penultimate day of every month
+@cindex examples, penultimate day of every month
+The following will run the @code{my-program} program on the
+second-to-last day of every month.
+
+@example
+(job '(- (next-month-from (next-month)) (* 48 3600))
+     "my-program")
+@end example
+
+
+
+@node Vixie Syntax,  , Extended Guile examples, Syntax
+@section Vixie
+@cindex syntax, vixie
+@cindex vixie syntax
+@cindex vixie definition
+@cindex vixie compatibility
+@cindex compatibility, vixie
+@emph{NOTE} that this section is definitive.  If there is a difference in
+behaviour between the mcron program and this part of the manual, then
+there is a bug in the program.  This section is also copied verbatim
+from Paul Vixie's documentation for his cron program, and his
+copyright notice is duly reproduced below.
+
+There are three problems with this specification.
+
+@cindex zero'th day of month
+@cindex 0'th day of month
+1.  It is allowed to specify days of the month in the range 0-31.  What
+does it mean to specify day 0? Looking at the Vixie source code, it
+seems that if this date appears as part of a list, it has no
+effect.  However, if it appears on its own, the effect is to say
+``don't run on any particular day of the month, only take the week-day
+specification into account.'' Mcron has been coded to mimic this
+behaviour as a special case (unmodified mcron logic implies that this
+date specification would cause jobs to run on the last day of the
+previous month).
+
+@cindex thirteenth month of year
+@cindex 13th month of year
+2.  Similarly to the above (but different), months of the year can be
+specified in the range 0-12.  In the case of mcron (don't know what
+Vixie cron did) month 12 will cause the program to wait until January
+of the following year (but don't rely on this).
+
+@cindex shell
+@cindex environment variables, shell
+@cindex /etc/passwd
+3.  Somewhere it says that cron sets the SHELL environment variable to
+/bin/sh, and elsewhere it implies that the default behaviour is for
+the user's default shell to be used to execute commands.  Mcron sets
+the variable and runs the command in the user's default shell, as
+advertised by the /etc/passwd file.
+
+@menu
+* Paul Vixie's copyright::
+* Crontab file::
+* Incompatibilities with old Unices::
+@end menu
+
+
+@node Paul Vixie's copyright, Crontab file, Vixie Syntax, Vixie Syntax
+@subsection Paul Vixie's copyright
+@cindex copyright, Paul Vixie's
+@cindex Paul Vixie's copyright
+@quotation
+Copyright 1988,1990,1993,1994 by Paul Vixie
+All rights reserved
+
+Distribute freely, except: don't remove my name from the source or
+documentation (don't take credit for my work), mark your changes (don't
+get me blamed for your possible bugs), don't alter or remove this
+notice.  May be sold if buildable source is provided to buyer.  No
+warrantee of any kind, express or implied, is included with this
+software; use at your own risk, responsibility for damages (if any) to
+anyone resulting from the use of this software rests entirely with the
+user.
+@end quotation
+
+
+
+
+@node  Crontab file, Incompatibilities with old Unices, Paul Vixie's copyright, Vixie Syntax
+@subsection Crontab files
+@cindex crontab file
+@cindex vixie crontab file
+A @code{crontab} file contains instructions to the @code{cron} daemon
+of the general form: ``run this command at this time on this date''.
+Each user has their own crontab, and commands in any given crontab
+will be executed as the user who owns the crontab.  Uucp and News will
+usually have their own crontabs, eliminating the need for explicitly
+running @code{su} as part of a cron command.
+
+@cindex comments, vixie-style
+Blank lines and leading spaces and tabs are ignored.  Lines whose first
+non-space character is a pound-sign (#) are comments, and are ignored.
+Note that comments are not allowed on the same line as cron commands, since
+they will be taken to be part of the command.  Similarly, comments are not
+allowed on the same line as environment variable settings.
+
+An active line in a crontab will be either an environment setting or a cron
+command.  An environment setting is of the form,
+
+@cindex environment setting, vixie-style
+@example
+name = value
+@end example
+
+where the spaces around the equal-sign (=) are optional, and any
+subsequent non-leading spaces in @code{value} will be part of the
+value assigned to @code{name}.  The @code{value} string may be placed
+in quotes (single or double, but matching) to preserve leading or
+trailing blanks.
+
+@cindex environment variables, SHELL
+@cindex environment variables, LOGNAME
+@cindex environment variables, HOME
+@cindex SHELL environment variable
+@cindex LOGNAME environment variable
+@cindex HOME environment variable
+@cindex /etc/passwd
+Several environment variables are set up automatically by the
+@code{cron} daemon.  SHELL is set to /bin/sh, and LOGNAME and HOME are
+set from the /etc/passwd line of the crontab's owner.  HOME and SHELL
+may be overridden by settings in the crontab; LOGNAME may not.
+
+@cindex environment variables, USER
+@cindex USER environment variable
+@cindex BSD
+(Another note: the LOGNAME variable is sometimes called USER on BSD systems...
+on these systems, USER will be set also.) @footnote{mcron has not been
+ported to BSD, so these notes are not relevant.}
+
+@cindex environment variables, MAILTO
+@cindex MAILTO environment variable
+In addition to LOGNAME, HOME, and SHELL, @code{cron} will look at
+MAILTO if it has any reason to send mail as a result of running
+commands in ``this'' crontab.  If MAILTO is defined (and non-empty),
+mail is sent to the user so named.  If MAILTO is defined but empty
+(MAILTO=""), no mail will be sent.  Otherwise mail is sent to the
+owner of the crontab.  This option is useful if you decide on
+/bin/mail instead of /usr/lib/sendmail as your mailer when you install
+cron -- /bin/mail doesn't do aliasing, and UUCP usually doesn't read
+its mail.
+
+The format of a cron command is very much the V7 standard, with a number of
+upward-compatible extensions.  Each line has five time and date fields,
+followed by a user name if this is the system crontab file,
+followed by a command.  Commands are executed by @code{cron}
+when the minute, hour, and month of year fields match the current
+time, @strong{and} when at least one of the two day fields (day of month, or day of week)
+match the current time (see ``Note'' below).  @code{cron} examines cron entries once every minute.
+The time and date fields are:
+
+@cindex vixie time specification fields
+@cindex fields, vixie time specification
+@multitable @columnfractions .2 .5
+@item Field @tab Allowed values
+@item ----- @tab --------------
+@item minute @tab 0-59
+@item hour @tab 0-23
+@item day of month @tab 0-31
+@item month @tab 0-12 (or names, see below)
+@item day of week @tab 0-7 (0 or 7 is Sun, or use names)
+@end multitable
+
+A field may be an asterisk (*), which always stands for ``first-last''.
+
+@cindex ranges in vixie time specifications
+Ranges of numbers are allowed.  Ranges are two numbers separated
+with a hyphen.  The specified range is inclusive.  For example,
+8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
+and 11.
+
+@cindex lists in vixie time specifications
+Lists are allowed.  A list is a set of numbers (or ranges)
+separated by commas.  Examples: ``1,2,5,9'', ``0-4,8-12''.
+
+@cindex steps in vixie time specifications
+Step values can be used in conjunction with ranges.  Following
+a range with ``/<number>'' specifies skips of the number's value
+through the range.  For example, ``0-23/2'' can be used in the hours
+field to specify command execution every other hour (the alternative
+in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22'').  Steps are
+also permitted after an asterisk, so if you want to say ``every two
+hours'', just use ``*/2''.
+
+@cindex names in vixie-style time specifications
+Names can also be used for the ``month'' and ``day of week''
+fields.  Use the first three letters of the particular
+day or month (case doesn't matter).  Ranges or
+lists of names are not allowed.  @footnote{Mcron allows any alphabetic
+characters after a name, so full names of days or months are also valid.}
+
+@cindex % character on vixie-style commands
+@cindex standard input, vixie-style
+The ``sixth'' field (the rest of the line) specifies the command to be
+run.
+The entire command portion of the line, up to a newline or %
+character, will be executed by /bin/sh or by the shell
+specified in the SHELL variable of the cronfile.
+Percent-signs (%) in the command, unless escaped with backslash
+(\\), will be changed into newline characters, and all data
+after the first % will be sent to the command as standard
+input.
+
+@cindex day specification, vixie-style
+@cindex vixie-style day specification
+Note: The day of a command's execution can be specified by two
+fields -- day of month, and day of week.  If both fields are
+restricted (ie, aren't *), the command will be run when
+@emph{either}
+field matches the current time.  For example,
+
+``30 4 1,15 * 5''
+
+would cause a command to be run at 4:30 am on the 1st and 15th of each
+month, plus every Friday.
+
+EXAMPLE CRON FILE
+
+@example
+# use /bin/sh to run commands, no matter what /etc/passwd says
+SHELL=/bin/sh
+# mail any output to `paul', no matter whose crontab this is
+MAILTO=paul
+#
+# run five minutes after midnight, every day
+5 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
+# run at 2:15pm on the first of every month -- output mailed to paul
+15 14 1 * *     $HOME/bin/monthly
+# run at 10 pm on weekdays, annoy Joe
+0 22 * * 1-5	mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
+23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
+5 4 * * sun     echo "run at 5 after 4 every sunday"
+@end example
+
+@node  Incompatibilities with old Unices,  , Crontab file, Vixie Syntax
+@subsection Extensions and incompatibilities
+@cindex incompatibilities with old Unices
+@cindex extensions, vixie over old Unices
+This section lists differences between Paul Vixie's cron and the
+olde-worlde BSD and AT&T programs, for the benefit of system
+administrators and users who are upgrading all the way.
+
+@itemize @bullet
+@item
+@cindex day 7
+When specifying day of week, both day 0 and day 7 will be considered Sunday.
+BSD and AT&T seem to disagree about this.
+
+@item
+Lists and ranges are allowed to co-exist in the same field.  "1-3,7-9" would
+be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY.
+
+@item
+Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
+
+@item
+Names of months or days of the week can be specified by name.
+
+@item
+Environment variables can be set in the crontab.  In BSD or AT&T, the
+environment handed to child processes is basically the one from /etc/rc.
+
+@item
+Command output is mailed to the crontab owner (BSD can't do this), can be
+mailed to a person other than the crontab owner (SysV can't do this), or the
+feature can be turned off and no mail will be sent at all (SysV can't do this
+either).
+
+@end itemize
+
+
+@node Invoking, Guile modules, Syntax, Top
+@chapter Detailed invoking
+@cindex invoking
+@cindex personality
+@cindex mcron program
+@cindex cron program
+@cindex crond program
+@cindex crontab program
+The program adopts one of three different personalities depending on
+the name used to invoke it.  In a standard installation, the program is
+installed in the system under the names mcron, cron and crontab
+(installed SUID).
+
+The recommended way to invoke the program is via the mcron personality
+described in the next section.  The program can also be run as cron by
+root, and by the SUID program crontab by individual users to gain
+backwards compatibility with Vixie cron.  However, due to the fact that
+this daemon process is shared by, and under control of, all the users
+of the system it is possible (though very unlikely) that it may become
+unusable, hence the recommendation to use the mcron personality.
+
+@cindex deprecated, vixie personality
+Furthermore, the Vixie personality is considered deprecated by this
+author (it offers not a single advantage over the mcron personality,
+and bloats the code by a factor of three).  It is unlikely that this
+personality will ever actually go away, but the program may in future
+be split into two distinct parts, and new developments will only take
+place in the part which implements the mcron personality.
+
+
+
+@menu
+* Invoking mcron::
+* Invoking cron or crond::
+* Invoking crontab::
+* Behaviour on laptops::
+* Exit codes::
+@end menu
+
+@node Invoking mcron, Invoking cron or crond, Invoking, Invoking
+@section Invoking mcron
+@cindex invoking mcron
+@cindex mcron options
+@cindex mcron arguments
+@cindex command line, mcron
+@cindex mcron command line
+Mcron should be run by the user who wants to schedule his jobs.  It
+may be made a background job using the facilities of the shell.  The
+basic command is @code{mcron [OPTION ...] [file ...]}  which has the
+effect of reading all the configuration files specified (subject to
+the options) and then waiting until it is time to execute some
+command.  If no files are given on the command line, then mcron will
+look in the user's cron 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.
+
+@table @option
+@item -s count
+@itemx --schedule=count
+@cindex printout of jobs schedule
+@cindex schedule of jobs, listing
+@cindex options, schedule
+@cindex options, -s
+@cindex -s option
+@cindex --schedule option
+With this option specified no commands are run.  Instead, the program
+computes the times the commands would be run and prints the
+information to the screen, and then immediately exits.
+
+The count indicates the number of commands to display.
+
+@cindex daemon option
+@cindex options, daemon
+@cindex options, -d
+@cindex -d option
+@cindex --daemon option
+@item -d
+@itemx --daemon
+With this option the program will detach itself from the controlling
+terminal and run as a daemon process.
+
+@cindex stdin option
+@cindex options, stdin
+@cindex options, -i
+@cindex -i option
+@cindex --stdin option
+@cindex standard input, configuring from
+@cindex configuring from standard input
+@item -i (vixie|guile)
+@itemx --stdin=(vixie|guile)
+This option is used to indicate whether the configuration information
+being passed on the standard input is in Vixie format or Guile
+format.  Guile is the default.
+
+@cindex -v option
+@cindex --version option
+@cindex options, -v
+@cindex options, version
+@item -v
+@itemx --version
+This option causes a message to be printed on the standard output with
+information about the version and copyright for the current program.
+
+@cindex -h option
+@cindex --help option
+@cindex options, -h
+@cindex options, --help
+@item -h
+@itemx --help
+This causes a short but complete usage message to be displayed on
+standard output.
+
+@end table
+
+@node Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking
+@section Invoking cron or crond
+@cindex cron, invokation
+@cindex invoking cron
+@cindex crond, invokation
+@cindex invoking crond
+@cindex @value{CONFIG_SPOOL_DIR}
+@cindex @value{CONFIG_SOCKET_FILE}
+NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or
+@code{crond}, 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 @code{@value{CONFIG_SPOOL_DIR}} (which
+should only be readable by root) and the file @code{/etc/crontab}, and
+then detaches itself from the terminal to live forever as a daemon
+process.  Additionally, it creates a UNIX socket at
+@code{@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.
+
+@table @option
+
+@cindex -v option
+@cindex --version option
+@cindex options, -v
+@cindex options, version
+@item -v
+@itemx --version
+This option causes a message to be printed on the standard output with
+information about the version and copyright for the current program.
+
+@cindex -h option
+@cindex --help option
+@cindex options, -h
+@cindex options, --help
+@item -h
+@itemx --help
+This causes a short but complete usage message to be displayed on
+standard output.
+
+@item -s [count]
+@itemx --schedule[=count]
+@cindex printout of jobs schedule
+@cindex schedule of jobs, listing
+@cindex options, schedule
+@cindex options, -s
+@cindex -s option
+@cindex --schedule option
+With this option specified no commands are run.  Instead, the program
+computes the times the commands would be run and prints the
+information to the screen, and then immediately exits.
+
+The count, if supplied, indicates the number of commands to
+display.  The default value is 8.
+
+@cindex -n option
+@cindex --noetc option
+@cindex options, -n
+@cindex options, --noetc
+@item -n
+@itemx --noetc
+This tells cron not to add a job to the system which wakes up every
+minute to check for modifications to @code{/etc/crontab}.  It is
+recommended that this option be used (and further that the
+@code{/etc/crontab} file be taken off the system altogether!)
+
+@end table
+
+@node Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking
+@section Invoking crontab
+@cindex crontab, invoking
+@cindex 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
+
+@code{crontab [-u user] file}
+
+or
+
+@code{crontab [-u user] ( -l | -e | -r )}
+
+Only the root user can use the -u option, to specify the manipulation
+of another user's crontab file.  In the first instance, the entire
+crontab file of the user is replaced with the contents of the
+specified file, or standard input if the file is ``-''.
+
+In the latter case, the program behaves according to which of the
+(mutually exclusive) options was given (note that the long options are
+an mcron extension).
+
+@table @option
+
+@cindex -l option
+@cindex list option, crontab
+@cindex options, -l
+@cindex options, --list
+@cindex viewing a crontab
+@cindex listing a crontab
+@item -l
+@itemx --list
+Print the user's crontab file to the standard output, and exit.
+
+@cindex -r option
+@cindex remove option
+@cindex options, -r
+@cindex options, --remove
+@cindex deleting a crontab
+@cindex removing a crontab
+@item -r
+@item --remove
+Delete the user's crontab file, and exit.
+
+@cindex -e option
+@cindex edit option
+@cindex options, -e
+@cindex options, --edit
+@cindex editing a crontab
+@cindex creating a crontab
+@item -e
+@item --edit
+Using the editor specified in the user's VISUAL or EDITOR environment
+variables, allow the user to edit his crontab.  Once the user exits the
+editor, the crontab is checked for parseability, and if it is okay
+then it is installed as the user's new crontab and the daemon is
+notified that a change has taken place, so that the new file will
+become immediately effective.
+
+@end table
+
+
+@node Behaviour on laptops, Exit codes, Invoking crontab, Invoking
+@section Behaviour on laptops
+@cindex laptops
+@cindex 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.
+
+
+@node Exit codes,  , Behaviour on laptops, Invoking
+@section Exit codes
+@cindex exit codes
+@cindex error conditions
+@cindex errors
+The following are the status codes returned to the operating system
+when the program terminates.
+
+@table @asis
+@item 0
+No problems.
+
+@item 1
+An attempt has been made to start cron but there is already a
+@value{CONFIG_PID_FILE} file.  If there really is no other cron daemon
+running (this does not include invokations of mcron) then you should
+remove this file before attempting to run cron.
+
+@item 2
+In parsing a guile configuration file, a @code{job} command has been
+seen but the second argument is neither a procedure, list or
+string.  This argument is the job's action, and needs to be specified
+in one of these forms.
+
+@item 3
+In parsing a guile configuration file, a @code{job} command has been
+seen but the first argument is neither a procedure, list or
+string.  This argument is the job's next-time specification, and needs
+to be specified in one of these forms.
+
+@item 4
+An attempt to run cron has been made by a user who does not have
+permission to access the crontabs in @value{CONFIG_SPOOL_DIR}.  These
+files should be readable only by root, and the cron daemon must be run
+as root.
+
+@item 5
+An attempt to run mcron has been made, but there are no jobs to
+schedule!
+
+@item 6
+The system administrator has blocked this user from using crontab with
+the files @value{CONFIG_ALLOW_FILE} and @value{CONFIG_DENY_FILE}.
+
+@item 7
+Crontab has been run with more than one of the arguments @code{-l},
+@code{-r}, @code{-e}.  These are mutually exclusive options.
+
+@item 8
+Crontab has been run with the -u option by a user other than
+root.  Only root is allowed to use this option.
+
+@item 9
+An invalid vixie-style time specification has been supplied.
+
+@item 10
+An invalid vixie-style job specification has been supplied.
+
+@item 11
+A bad line has been seen in /etc/crontab.
+
+@item 12
+The last component of the name of the program was not one of
+@code{mcron}, @code{cron}, @code{crond} or @code{crontab}.
+
+@item 13
+Either 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.
+
+@c @item 14
+@c There is a problem writing to /var/cron/update.  This is probably
+@c because the crontab program is not installed SUID root, as it should
+@c be.
+
+@item 15
+Crontab has been run without any arguments at all.  There is no default
+behaviour in this case.
+
+@item 16
+Cron has been run by a user other than root.
+
+@end table
+
+
+
+@node Guile modules, Index, Invoking, Top
+@chapter Guile modules
+Some of the key parts of mcron are implemented as modules so they can
+be incorporated into other Guile programs, or even into C-sourced
+programs if they are linked against libguile.
+
+It may be, for example, that a program needs to perform house-keeping
+functions at certain times of the day, in which case it can spawn
+(either fork or thread) a sub-process which uses a built-in
+mcron.  Another example may be a program which must sleep until some
+non-absolute time specified on the Gregorian calendar (the first day
+of next week, for example).  Finally, it may be the wish of the user to
+provide a program with the functionality of mcron plus a bit extra.
+
+The base module maintains mcron's internal job lists, and provides the
+main wait-run-wait loop that is mcron's main function.  It also
+introduces the facilities for accumulating a set of environment
+modifiers, which take effect when jobs run.
+
+@menu
+* The base module::             The job list and execution loop.
+* The redirect module::         Sending output of jobs to a mail box.
+* The vixie-time module::       Parsing vixie-style time specifications.
+* The job-specifier module::    All commands for scheme configuration files.
+* The vixie-specification module::  Commands for reading vixie-style crontabs.
+@end menu
+
+@node The base module, The redirect module, Guile modules, Guile modules
+@section The base module
+@cindex guile module
+@cindex base module
+@cindex modules, base
+
+This module may be used by including @code{(use-modules (mcron base))}
+in a program.  The main functions are @code{add-job} and
+@code{run-job-loop}, which allow a program to create a list of job
+specifications to run, and then to initiate the wait-run-wait loop
+firing the jobs off at the requisite times.  However, before they are
+introduced two functions which manipulate the environment that takes
+effect when a job runs are defined.
+
+@cindex environment
+The environment is a set of name-value pairs which is built up
+incrementally.  Each time the @code{add-job} function is called, the
+environment modifiers that have been accumulated up to that point are
+stored with the new job specification, and when the job actually runs
+these name-value pairs are used to modify the run-time environment in
+effect.
+
+@deffn{Scheme procedure} append-environment-mods name value
+When a job is run make sure the environment variable @var{name} has
+the value @var{value}.
+@end deffn
+
+@deffn{Scheme procedure} clear-environment-mods
+This procedure causes all the environment modifiers that have been
+specified so far to be forgotten.
+@end deffn
+
+@deffn{Scheme procedure} add-job time-proc action displayable configuration-time configuration-user
+This procedure adds a job specification to the list of all jobs to
+run.  @var{time-proc} should be a procedure taking exactly one argument
+which will be a UNIX time.  This procedure must compute the next time
+that the job should run, and return the result.  @var{action} should be
+a procedure taking no arguments, and contains the instructions that
+actually get executed whenever the job is scheduled to
+run.  @var{displayable} should be a string, and is only for the use of
+humans; it can be anything which identifies or simply gives a clue as
+to the purpose or function of this job.  @var{configuration-time} is
+the time from which the first invokation of this job should be
+computed.  Finally, @var{configuration-user} should be the passwd entry
+for the user under whose personality the job is to run.
+@end deffn
+
+@deffn{Scheme procedure} run-job-loop . fd-list
+@cindex file descriptors
+@cindex interrupting the mcron loop
+This procedure returns only under exceptional circumstances, but
+usually loops forever waiting for the next time to arrive when a job
+needs to run, running that job, recomputing the next run time, and
+then waiting again.  However, the wait can be interrupted by data
+becoming available for reading on one of the file descriptors in the
+fd-list, if supplied.  Only in this case will the procedure return to
+the calling program, which may then make modifications to the job list
+before calling the @code{run-job-loop} procedure again to resume execution of
+the mcron base.
+@end deffn
+
+@deffn{Scheme procedure} remove-user-jobs user
+
+The argument @var{user} should be a string naming a user (his
+login name), or an integer UID, or an object representing the user's passwd
+entry.  All jobs on the current job list that are scheduled to be run
+under this personality are removed from the job list.
+@end deffn
+
+@deffn{Scheme procedure} get-schedule count
+@cindex schedule of jobs
+The argument @var{count} should be an integer value giving the number
+of time-points in the future to report that jobs will run as.  Note
+that this procedure is disruptive; if @code{run-job-loop} is called
+after this procedure, the first job to run will be the one after the
+last job that was reported in the schedule report.  The report itself
+is returned to the calling program as a string.
+@end deffn
+
+@node The redirect module, The vixie-time module, The base module, Guile modules
+@section The redirect module
+@cindex redirect module
+@cindex modules, redirect
+
+This module is introduced to a program with the command
+@code{(use-modules (mcron redirect))}.
+
+This module provides the @code{with-mail-out} function, described
+fully in @ref{Guile Syntax}.
+
+@node The vixie-time module, The job-specifier module, The redirect module, Guile modules
+@section The vixie-time module
+@cindex vixie-time module
+@cindex modules, vixie-time
+
+This module is introduced to a program by @code{(use-modules (mcron
+vixie-time))}.
+
+This module provides a single method for converting a vixie-style time
+specification into a procedure which can be used as the
+@code{next-time-function} to the base @code{add-job} procedure, or to
+the @code{job-specifier} @code{job} procedure.  See @ref{Vixie Syntax}
+for full details of the allowed format for the time string.
+
+@deffn{Scheme procedure} parse-vixie-time time-string
+The single argument @var{time-string} should be a string containing a
+vixie-style time specification, and the return value is the required
+procedure.
+@end deffn
+
+
+@node The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules
+@section The job-specifier module
+@cindex job-specifier module
+@cindex modules, job-specifier
+
+This module is introduced to a program by @code{(use-modules (mcron
+job-specifier))}.
+
+This module provides all the functions available to user's Guile
+configuration files, namely @code{range}, @code{next-year-from},
+@code{next-year}, @code{next-month-from}, @code{next-month},
+@code{next-day-from}, @code{next-day}, @code{next-hour-from},
+@code{next-hour}, @code{next-minute-from}, @code{next-minute},
+@code{next-second-from}, @code{next-second},
+ and last but not least, @code{job}.  See @ref{Guile Syntax} for full
+ details.
+
+Once this module is loaded, a scheme configuration file can be used to
+put jobs onto the job list simply by @code{load}ing the file.
+
+@node The vixie-specification module,  , The job-specifier module, Guile modules
+@section The vixie-specification module
+@cindex vixie-specification module
+@cindex modules, vixie-specification
+
+To use this module, put the command @code{(use-modules (mcron
+vixie-specification))} into your program.
+
+This module exports a couple of functions for adding jobs to the
+internal job list according to a Vixie-style crontab file.
+
+@deffn{Scheme procedure} read-vixie-port port . parse-line
+
+This procedure reads a crontab from the given port, and adds jobs to
+the job list accordingly, taking care of environment specifications
+and comments which may appear in such a file.
+
+@var{parse-line} should not normally be used, except that if you are
+parsing a (deprecated) @code{/etc/crontab} file with a slightly
+modified syntax, you may pass the value @var{parse-system-vixie-line}
+as the optional argument.
+
+@end deffn
+
+@deffn{Scheme procedure} read-vixie-file name . parse-line
+
+This procedure attempts to open the named file, and if it fails will
+return silently.  Otherwise, the behaviour is identical to
+@code{read-vixie-port} above.
+
+@end deffn
+
+Once this module has been declared in a program, a crontab file can be
+used to augment the current job list with a call to
+@code{read-vixie-file}.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@node Index,  , Guile modules, Top
+@unnumbered Index
+
+@printindex cp
+
+@bye