From 8f430594f4452c378de08177be187d1cb5de1cd0 Mon Sep 17 00:00:00 2001 From: Mathieu Lirzin Date: Fri, 26 Jun 2015 23:17:01 +0200 Subject: build: Fix build of the manual. * mcron.texinfo.in: Rename to ... * doc/mcron.texi: ... this. * doc/config.texi.in: New file. * configure.ac: Adapt to it. * makefile.am: Likewise. * .gitignore: Likewise. * README--git: Likewise. --- doc/config.texi.in | 5 + doc/mcron.texi | 1337 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1342 insertions(+) create mode 100644 doc/config.texi.in create mode 100644 doc/mcron.texi (limited to 'doc') 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/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 +@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. +* 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 core module:: The job list and execution loop. +* The redirect module:: Sending output of jobs to a mail box. +* The vixie-time module:: Parsing vixie-style time specifications. +* The job-specifier module:: All commands for scheme configuration files. +* The vixie-specification module:: Commands for reading vixie-style crontabs. + +@end detailmenu +@end menu + +@node Introduction, Simple examples, Top, Top +@chapter Introducing mcron +@cindex introduction +@cindex mcron +The mcron program represents a complete re-think of the cron concept +originally found in the Berkeley and AT&T unices, and subsequently +rationalized by Paul Vixie. The original idea was to have a daemon +that wakes up every minute, scans a set of files under a special +directory, and determines from those files if any shell commands +should be executed in this minute. + +The new idea is to read the required command instructions, work out +which command needs to be executed next, and then sleep until the +inferred time has arrived. On waking the commands are run, and the +time of the next command is computed. Furthermore, the specifications +are written in scheme, allowing at the same time simple command +execution instructions and very much more flexible ones to be composed +than the original Vixie format. This has several useful advantages +over the original idea. (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. + +@cindex time specification, procedure +@cindex procedure time specification +The first argument can be a procedure, a list, or a string. If a +function is supplied, it must take exactly one argument, which will be +the ``current'' time in UNIX format, and the return value of the +function must be the time in UNIX format when this action should next +be run. The following functions are available to facilitate the +computation: + +@findex next-second-from +@code{(next-second-from time . args)} without arguments this +returns the second after the current one. With the extra arguments, +these form a list of seconds in the minute when the action should run, +and the function will return the time of the next allowed second +(which may be in the next minute of the hour). @footnote{Note that +while commands can be scheduled to run at any second, it is unlikely +that they will be executed then but some time shortly thereafter, +depending on the load on the system and the number of jobs that mcron +has to start at the same time.} + +@findex next-minute-from +@findex next-hour-from +@findex next-day-from +@findex next-week-from +@findex next-month-from +@findex next-year-from +Similarly to @code{next-second-from}, there are also +@code{next-minute-from}, @code{next-hour-from}, @code{next-day-from}, +@code{next-week-from}, @code{next-month-from}, @code{next-year-from}. + +@findex range +Furthermore, the optional argument can be fulfilled by the function +@code{(range start end . step)}, which will provide a list of values +from start to (but not including) end, with the step if given. For +example @code{(range 0 10 2)} will yield the list @code{'(0 2 4 6 8)}. + +@findex next-second +@findex next-minute +@findex next-hour +@findex next-day +@findex next-week +@findex next-month +@findex next-year +@cindex time specification, list +@cindex list time specification +If the first argument to the @code{job} function is a list, it is +taken to be program code made up of the functions @code{(next-second +. args)}, @code{(next-minute...)}, etc, where the optional arguments +can be supplied with the @code{(range)} function above (these +functions are analogous to the ones above except that they implicitly +assume the current time; it is supplied by the mcron core when the +list is eval'd). + +@cindex time specification +@cindex time specification, string +@cindex string time specification +@cindex time specification, vixie-style +@cindex vixie-style time specification +If the first argument to the @code{job} function is a string, it is +expected to be a Vixie cron-style time specification. See the section +on Vixie syntax for this. + +@cindex job execution +@cindex command execution +@cindex execution +The second argument to the @code{(job)} function can be either a +string, a list, or a function. In all cases the command is executed in +the user's home directory, under the user's own UID. If a string is +passed, it is assumed to be shell script and is executed with the +user's default shell. If a list is passed it is assumed to be scheme +code and is eval'd as such. A supplied function should take exactly +zero arguments, and will be called at the pertinent times. + +@subsection Sending output as e-mail +@cindex email output +@cindex email from guile script +@cindex standard input to commands +@findex with-mail-out +When jobs are specified in a vixie-style configuration, the command is +broken at a percentage sign, and the stuff that comes after this is +sent into the command's standard input. Furthermore, any output from +the command is mailed to the user. This functionality is provided for +compatibility with Vixie cron, but it is also available to scheme +configuration files. The command (with-mail-out action . user) can be +used to direct output from the action (which may be a procedure, list, +or string) into an e-mail to the user. + +In the case that the action is a string, then percentage signs are +processed as per the vixie specifications, and information is piped to +the shell command's standard input. + +@subsection Setting environment variables +@cindex environment variables in scheme +@cindex setting environment variables +@findex append-environment-mods +Also for compatibility with Vixie cron, mcron has the ability to set +environment variables in configuration files. To access this +functionality from a scheme configuration file, use the command +(append-environment-mods name value), where name is the name of an +environment variable, and value is the value put to it. A value of #f +will remove the variable from the environment. + +Note that environment modifications are accumulated as the +configuration file is processed, so when a job actually runs, its +environment will be modified according to the modifications specified +before the job specification in the configuration file. + + +@node Extended Guile examples, Vixie Syntax, Guile Syntax, Syntax +@section Extended Guile examples +@cindex examples, extended guile +@cindex extended guile examples +While Guile gives you flexibility to do anything, and the power to +represent complex requirements succinctly, things are not always as +they seem. The following examples illustrate some pitfalls, and +demonstrate how to code around them. + +@menu +* AT commands:: +* Every second Sunday:: +* Two hours every day:: +* Missing the first appointment:: +* Penultimate day of every month:: +@end menu + +@node AT commands, Every second Sunday, Extended Guile examples, Extended Guile examples +@subsection Synthesizing ``at'' commands +@cindex at command +The current implementation of mcron does not provide for an at command +(a command-line program that allows the user to specify that a job +runs exactly once at a certain time). This can, however, be achieved. + +Suppose the program @code{my-program} needs to be run at midnight +tonight. A Guile script like the following 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 ``/'' 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 core module maintains mcron's internal job lists, and provides the +main wait-run-wait loop that is mcron's main function. It also +introduces the facilities for accumulating a set of environment +modifiers, which take effect when jobs run. + +@menu +* The core module:: The job list and execution loop. +* The redirect module:: Sending output of jobs to a mail box. +* The vixie-time module:: Parsing vixie-style time specifications. +* The job-specifier module:: All commands for scheme configuration files. +* The vixie-specification module:: Commands for reading vixie-style crontabs. +@end menu + +@node The core module, The redirect module, Guile modules, Guile modules +@section The core module +@cindex guile module +@cindex core module +@cindex modules, core + +This module may be used by including @code{(use-modules (mcron core))} +in a program. The main functions are @code{add-job} and +@code{run-job-loop}, which allow a program to create a list of job +specifications to run, and then to initiate the wait-run-wait loop +firing the jobs off at the requisite times. However, before they are +introduced two functions which manipulate the environment that takes +effect when a job runs are defined. + +@cindex environment +The environment is a set of name-value pairs which is built up +incrementally. Each time the @code{add-job} function is called, the +environment modifiers that have been accumulated up to that point are +stored with the new job specification, and when the job actually runs +these name-value pairs are used to modify the run-time environment in +effect. + +@deffn{Scheme procedure} append-environment-mods name value +When a job is run make sure the environment variable @var{name} has +the value @var{value}. +@end deffn + +@deffn{Scheme procedure} clear-environment-mods +This procedure causes all the environment modifiers that have been +specified so far to be forgotten. +@end deffn + +@deffn{Scheme procedure} add-job time-proc action displayable configuration-time configuration-user +This procedure adds a job specification to the list of all jobs to +run. @var{time-proc} should be a procedure taking exactly one argument +which will be a UNIX time. This procedure must compute the next time +that the job should run, and return the result. @var{action} should be +a procedure taking no arguments, and contains the instructions that +actually get executed whenever the job is scheduled to +run. @var{displayable} should be a string, and is only for the use of +humans; it can be anything which identifies or simply gives a clue as +to the purpose or function of this job. @var{configuration-time} is +the time from which the first invokation of this job should be +computed. Finally, @var{configuration-user} should be the passwd entry +for the user under whose personality the job is to run. +@end deffn + +@deffn{Scheme procedure} run-job-loop . fd-list +@cindex file descriptors +@cindex interrupting the mcron loop +This procedure returns only under exceptional circumstances, but +usually loops forever waiting for the next time to arrive when a job +needs to run, running that job, recomputing the next run time, and +then waiting again. However, the wait can be interrupted by data +becoming available for reading on one of the file descriptors in the +fd-list, if supplied. Only in this case will the procedure return to +the calling program, which may then make modifications to the job list +before calling the @code{run-job-loop} procedure again to resume execution of +the mcron core. +@end deffn + +@deffn{Scheme procedure} remove-user-jobs user + +The argument @var{user} should be a string naming a user (his +login name), or an integer UID, or an object representing the user's passwd +entry. All jobs on the current job list that are scheduled to be run +under this personality are removed from the job list. +@end deffn + +@deffn{Scheme procedure} get-schedule count +@cindex schedule of jobs +The argument @var{count} should be an integer value giving the number +of time-points in the future to report that jobs will run as. Note +that this procedure is disruptive; if @code{run-job-loop} is called +after this procedure, the first job to run will be the one after the +last job that was reported in the schedule report. The report itself +is returned to the calling program as a string. +@end deffn + +@node The redirect module, The vixie-time module, The core module, Guile modules +@section The redirect module +@cindex redirect module +@cindex modules, redirect + +This module is introduced to a program with the command +@code{(use-modules (mcron redirect))}. + +This module provides the @code{with-mail-out} function, described +fully in @ref{Guile Syntax}. + +@node The vixie-time module, The job-specifier module, The redirect module, Guile modules +@section The vixie-time module +@cindex vixie-time module +@cindex modules, vixie-time + +This module is introduced to a program by @code{(use-modules (mcron +vixie-time))}. + +This module provides a single method for converting a vixie-style time +specification into a procedure which can be used as the +@code{next-time-function} to the core @code{add-job} procedure, or to +the @code{job-specifier} @code{job} procedure. See @ref{Vixie Syntax} +for full details of the allowed format for the time string. + +@deffn{Scheme procedure} parse-vixie-time time-string +The single argument @var{time-string} should be a string containing a +vixie-style time specification, and the return value is the required +procedure. +@end deffn + + +@node The job-specifier module, The vixie-specification module, The vixie-time module, Guile modules +@section The job-specifier module +@cindex job-specifier module +@cindex modules, job-specifier + +This module is introduced to a program by @code{(use-modules (mcron +job-specifier))}. + +This module provides all the functions available to user's Guile +configuration files, namely @code{range}, @code{next-year-from}, +@code{next-year}, @code{next-month-from}, @code{next-month}, +@code{next-day-from}, @code{next-day}, @code{next-hour-from}, +@code{next-hour}, @code{next-minute-from}, @code{next-minute}, +@code{next-second-from}, @code{next-second}, + and last but not least, @code{job}. See @ref{Guile Syntax} for full + details. + +Once this module is loaded, a scheme configuration file can be used to +put jobs onto the job list simply by @code{load}ing the file. + +@node The vixie-specification module, , The job-specifier module, Guile modules +@section The vixie-specification module +@cindex vixie-specification module +@cindex modules, vixie-specification + +To use this module, put the command @code{(use-modules (mcron +vixie-specification))} into your program. + +This module exports a couple of functions for adding jobs to the +internal job list according to a Vixie-style crontab file. + +@deffn{Scheme procedure} read-vixie-port port . parse-line + +This procedure reads a crontab from the given port, and adds jobs to +the job list accordingly, taking care of environment specifications +and comments which may appear in such a file. + +@var{parse-line} should not normally be used, except that if you are +parsing a (deprecated) @code{/etc/crontab} file with a slightly +modified syntax, you may pass the value @var{parse-system-vixie-line} +as the optional argument. + +@end deffn + +@deffn{Scheme procedure} read-vixie-file name . parse-line + +This procedure attempts to open the named file, and if it fails will +return silently. Otherwise, the behaviour is identical to +@code{read-vixie-port} above. + +@end deffn + +Once this module has been declared in a program, a crontab file can be +used to augment the current job list with a call to +@code{read-vixie-file}. + +@node Index, , Guile modules, Top +@unnumbered Index + +@printindex cp + +@bye -- cgit v1.2.3 From 940146bc909d5ee2dd491dbc76d07f2b6f740152 Mon Sep 17 00:00:00 2001 From: Mathieu Lirzin Date: Tue, 7 Jul 2015 11:56:52 +0200 Subject: doc: Include a copy of the GNU FDL. * doc/fdl.texi: New file. * doc/mcron.texi: Include it. * makefile.am (doc_mcron_TEXINFOS): New variable. --- doc/fdl.texi | 505 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/mcron.texi | 6 + makefile.am | 2 +- 3 files changed, 512 insertions(+), 1 deletion(-) create mode 100644 doc/fdl.texi (limited to 'doc') 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 index cb97a06..27cd1b7 100644 --- a/doc/mcron.texi +++ b/doc/mcron.texi @@ -63,6 +63,7 @@ running jobs at scheduled times. * 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 @@ -1329,6 +1330,11 @@ 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 diff --git a/makefile.am b/makefile.am index 189ce02..431190c 100644 --- a/makefile.am +++ b/makefile.am @@ -33,7 +33,7 @@ CLEANFILES = mcron.c EXTRA_DIST = makefile.ed mcron.c.template BUGS info_TEXINFOS = doc/mcron.texi - +doc_mcron_TEXINFOS = doc/fdl.texi dist_man_MANS = doc/mcron.1 bin_PROGRAMS = mcron -- cgit v1.2.3 From 418b81e1af8d18c86693cb43ffe89354af28e3a8 Mon Sep 17 00:00:00 2001 From: Mathieu Lirzin Date: Sat, 7 May 2016 13:08:06 +0200 Subject: base: Rename (mcron core) module to (mcron base). The 'configure' script deletes the 'core.*' files. Having a file named 'base.scm' instead of 'core.scm' simplifies the build process without changing the semantics. * src/mcron/mcron-core.scm: Rename to ... * src/mcron/base.scm: ... this. All module users changed. * Makefile.am (MODULES): Add 'src/mcron/base.scm'. (CP): Remove variable. (src/mcron/core.scm): Remove target. (GEN_MODULES): Remove 'src/mcron/core.scm'. (dist_mcronmodule_DATA): Remove 'src/mcron/mcron-core.scm' * doc/mcron.texi: Adapt to name change. * .gitignore: Update. --- .gitignore | 1 - Makefile.am | 12 +- doc/mcron.texi | 24 ++-- src/mcron/base.scm | 270 ++++++++++++++++++++++++++++++++++++++ src/mcron/job-specifier.scm | 7 +- src/mcron/main.scm | 4 +- src/mcron/mcron-core.scm | 270 -------------------------------------- src/mcron/vixie-specification.scm | 2 +- 8 files changed, 292 insertions(+), 298 deletions(-) create mode 100644 src/mcron/base.scm delete mode 100644 src/mcron/mcron-core.scm (limited to 'doc') diff --git a/.gitignore b/.gitignore index 8bffc85..c064be1 100644 --- a/.gitignore +++ b/.gitignore @@ -31,7 +31,6 @@ config.log config.scm config.status configure -core.scm depcomp install-sh missing diff --git a/Makefile.am b/Makefile.am index 1b5317c..f02b84e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -23,6 +23,7 @@ mcron_DEPENDENCIES = $(GOBJECTS) # Build Guile modules before linking. mcron_LDADD = @GUILE_LIBS@ MODULES = \ + src/mcron/base.scm \ src/mcron/environment.scm \ src/mcron/job-specifier.scm \ src/mcron/main.scm \ @@ -31,13 +32,7 @@ MODULES = \ src/mcron/vixie-time.scm GEN_MODULES = \ - src/mcron/config.scm \ - src/mcron/core.scm - -CP = @CP@ -# XXX: Prevent the 'configure' script to delete the 'core.*' files. -src/mcron/core.scm: src/mcron/mcron-core.scm - $(CP) $< $@ + src/mcron/config.scm GOBJECTS = \ $(GEN_MODULES:%.scm=%.go) \ @@ -49,8 +44,7 @@ mcronmodule_DATA = \ dist_mcronmodule_DATA = \ $(MODULES) \ - src/mcron/crontab.scm \ - src/mcron/mcron-core.scm + src/mcron/crontab.scm # Unset 'GUILE_LOAD_COMPILED_PATH' altogether while compiling. Otherwise, if # $GUILE_LOAD_COMPILED_PATH contains $(mcronmoduledir), we may find .go files diff --git a/doc/mcron.texi b/doc/mcron.texi index 27cd1b7..340faca 100644 --- a/doc/mcron.texi +++ b/doc/mcron.texi @@ -104,7 +104,7 @@ Detailed invoking Guile modules -* The core module:: The job list and execution loop. +* 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. @@ -327,7 +327,7 @@ 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 +assume the current time; it is supplied by the mcron base when the list is eval'd). @cindex time specification @@ -1150,26 +1150,26 @@ 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 +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 core module:: The job list and execution loop. +* 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 core module, The redirect module, Guile modules, Guile modules -@section The core module +@node The base module, The redirect module, Guile modules, Guile modules +@section The base module @cindex guile module -@cindex core module -@cindex modules, core +@cindex base module +@cindex modules, base -This module may be used by including @code{(use-modules (mcron core))} +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 @@ -1221,7 +1221,7 @@ 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. +the mcron base. @end deffn @deffn{Scheme procedure} remove-user-jobs user @@ -1242,7 +1242,7 @@ last job that was reported in the schedule report. The report itself is returned to the calling program as a string. @end deffn -@node The redirect module, The vixie-time module, The core module, Guile modules +@node The redirect module, The vixie-time module, The base module, Guile modules @section The redirect module @cindex redirect module @cindex modules, redirect @@ -1263,7 +1263,7 @@ vixie-time))}. This module provides a single method for converting a vixie-style time specification into a procedure which can be used as the -@code{next-time-function} to the core @code{add-job} procedure, or to +@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. diff --git a/src/mcron/base.scm b/src/mcron/base.scm new file mode 100644 index 0000000..7094dbc --- /dev/null +++ b/src/mcron/base.scm @@ -0,0 +1,270 @@ +;; Copyright (C) 2015, 2016 Mathieu Lirzin +;; Copyright (C) 2003 Dale Mellor +;; +;; This file is part of GNU mcron. +;; +;; GNU mcron is free software: you can redistribute it and/or modify it under +;; the terms of the GNU General Public License as published by the Free +;; Software Foundation, either version 3 of the License, or (at your option) +;; any later version. +;; +;; GNU mcron is distributed in the hope that it will be useful, but WITHOUT +;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +;; more details. +;; +;; You should have received a copy of the GNU General Public License along +;; with GNU mcron. If not, see . + + + +(define-module (mcron base) + #:use-module (mcron environment) + #:use-module (srfi srfi-9) + #:export (add-job + remove-user-jobs + get-schedule + run-job-loop + ;; These three are deprecated and not documented. + use-system-job-list + use-user-job-list + clear-system-jobs) + #:re-export (clear-environment-mods + append-environment-mods)) + + +(use-modules (srfi srfi-1) ;; For remove. + (srfi srfi-2)) ;; For and-let*. + + + +;; The list of all jobs known to the system. Each element of the list is +;; +;; (make-job user next-time-function action environment displayable next-time) +;; +;; where action must be a procedure, and the environment is an alist of +;; modifications that need making to the UNIX environment before the action is +;; run. The next-time element is the only one that is modified during the +;; running of a cron process (i.e. all the others are set once and for all at +;; configuration time). +;; +;; The reason we maintain two lists is that jobs in /etc/crontab may be placed +;; in one, and all other jobs go in the other. This makes it possible to remove +;; all the jobs in the first list in one go, and separately we can remove all +;; jobs from the second list which belong to a particular user. This behaviour +;; is required for full vixie compatibility. + +(define system-job-list '()) +(define user-job-list '()) + +(define configuration-source 'user) + +(define (use-system-job-list) (set! configuration-source 'system)) +(define (use-user-job-list) (set! configuration-source 'user)) + +;; A cron job. +(define-record-type + (make-job user time-proc action environment displayable next-time) + job? + (user job:user) ;object : passwd entry + (time-proc job:next-time-function) ;proc : with one 'time' parameter + (action job:action) ;thunk : user's code + (environment job:environment) ;alist : environment variables + (displayable job:displayable) ;string : visible in schedule + (next-time job:next-time ;number : time in UNIX format + job:next-time-set!)) + +;; Remove jobs from the user-job-list belonging to this user. + +(define (remove-user-jobs user) + (if (or (string? user) + (integer? user)) + (set! user (getpw user))) + (set! user-job-list + (remove (lambda (job) (eqv? (passwd:uid user) + (passwd:uid (job:user job)))) + user-job-list))) + + + +;; Remove all the jobs on the system job list. + +(define (clear-system-jobs) (set! system-job-list '())) + + + +;; Add a new job with the given specifications to the head of the appropriate +;; jobs list. + +(define (add-job time-proc action displayable configuration-time + configuration-user) + (let ((entry (make-job configuration-user + time-proc + action + (get-current-environment-mods-copy) + displayable + (time-proc configuration-time)))) + (if (eq? configuration-source 'user) + (set! user-job-list (cons entry user-job-list)) + (set! system-job-list (cons entry system-job-list))))) + + + +;; Procedure to locate the jobs in the global job-list with the lowest +;; (soonest) next-times. These are the jobs for which we must schedule the mcron +;; program (under any personality) to next wake up. The return value is a cons +;; cell consisting of the next time (maintained in the next-time variable) and a +;; list of the job entries that are to run at this time (maintained in the +;; next-jobs-list variable). +;; +;; The procedure works by first obtaining the time of the first job on the list, +;; and setting this job in the next-jobs-list. Then for each other entry on the +;; job-list, either the job runs earlier than any other that have been scanned, +;; in which case the next-time and next-jobs-list are re-initialized to +;; accomodate, or the job runs at the same time as the next job, in which case +;; the next-jobs-list is simply augmented with the new job, or else the job runs +;; later than others noted in which case we ignore it for now and continue to +;; recurse the list. + +(define (find-next-jobs) + (let ((job-list (append system-job-list user-job-list))) + + (if (null? job-list) + + '(#f . '()) + + (let ((next-time 2000000000) + (next-jobs-list '())) + + (for-each + (lambda (job) + (let ((this-time (job:next-time job))) + (cond ((< this-time next-time) + (set! next-time this-time) + (set! next-jobs-list (list job))) + ((eqv? this-time next-time) + (set! next-jobs-list (cons job next-jobs-list)))))) + job-list) + + (cons next-time next-jobs-list))))) + + + +;; Create a string containing a textual list of the next count jobs to run. +;; +;; Enter a loop of displaying the next set of jobs to run, artificially +;; forwarding the time to the next time point (instead of waiting for it to +;; occur as we would do in a normal run of mcron), and recurse around the loop +;; count times. +;; +;; Note that this has the effect of mutating the job timings. Thus the program +;; must exit after calling this function; the internal data state will be left +;; unusable. + +(define (get-schedule count) + (with-output-to-string + (lambda () + (do ((count count (- count 1))) + ((eqv? count 0)) + (and-let* + ((next-jobs (find-next-jobs)) + (time (car next-jobs)) + (date-string (strftime "%c %z\n" (localtime time)))) + (for-each (lambda (job) + (display date-string) + (display (job:displayable job)) + (newline)(newline) + (job:next-time-set! job ((job:next-time-function job) + (job:next-time job)))) + (cdr next-jobs))))))) + + + +;; For proper housekeeping, it is necessary to keep a record of the number of +;; child processes we fork off to run the jobs. + +(define number-children 0) + + + +;; For every job on the list, fork a process to run it (noting the fact by +;; increasing the number-children counter), and in the new process set up the +;; run-time environment exactly as it should be before running the job proper. +;; +;; In the parent, update the job entry by computing the next time the job needs +;; to run. + +(define (run-jobs jobs-list) + (for-each + (lambda (job) + (if (eqv? (primitive-fork) 0) + (begin + (setgid (passwd:gid (job:user job))) + (setuid (passwd:uid (job:user job))) + (chdir (passwd:dir (job:user job))) + (modify-environment (job:environment job) (job:user job)) + ((job:action job)) + (primitive-exit 0)) + (begin + (set! number-children (+ number-children 1)) + (job:next-time-set! job ((job:next-time-function job) + (current-time)))))) + jobs-list)) + + + +;; Give any zombie children a chance to die, and decrease the number known to +;; exist. + +(define (child-cleanup) + (do () ((or (<= number-children 0) + (eqv? (car (waitpid WAIT_ANY WNOHANG)) 0))) + (set! number-children (- number-children 1)))) + + + +;; Now the main loop. Loop over all job specifications, get a list of the next +;; ones to run (may be more than one). Set an alarm and go to sleep. When we +;; wake, run the jobs and reap any children (old jobs) that have +;; completed. Repeat ad infinitum. +;; +;; Note that, if we wake ahead of time, it can only mean that a signal has been +;; sent by a crontab job to tell us to re-read a crontab file. In this case we +;; break out of the loop here, and let the main procedure deal with the +;; situation (it will eventually re-call this function, thus maintaining the +;; loop). + +(define (run-job-loop . fd-list) + + (call-with-current-continuation + (lambda (break) + + (let ((fd-list (if (null? fd-list) '() (car fd-list)))) + + (let loop () + + (let* ((next-jobs (find-next-jobs)) + (next-time (car next-jobs)) + (next-jobs-list (cdr next-jobs)) + (sleep-time (if next-time (- next-time (current-time)) + 2000000000))) + + (and (> sleep-time 0) + (if (not (null? + (catch 'system-error + (lambda () + (car (select fd-list '() '() sleep-time))) + (lambda (key . args) ;; Exception add by Sergey + ;; Poznyakoff. + (if (member (car (last args)) + (list EINTR EAGAIN)) + (begin + (child-cleanup) '()) + (apply throw key args)))))) + (break))) + + (run-jobs next-jobs-list) + + (child-cleanup) + + (loop))))))) diff --git a/src/mcron/job-specifier.scm b/src/mcron/job-specifier.scm index 1c2f9d9..9e13551 100644 --- a/src/mcron/job-specifier.scm +++ b/src/mcron/job-specifier.scm @@ -20,12 +20,13 @@ ;; This module defines all the functions that can be used by scheme mcron ;; configuration files, namely the procedures for working out next times, the -;; job procedure for registering new jobs (actually a wrapper around the core -;; add-job function), and the procedure for declaring environment modifications. +;; job procedure for registering new jobs (actually a wrapper around the +;; base add-job function), and the procedure for declaring environment +;; modifications. (define-module (mcron job-specifier) #:use-module (ice-9 match) - #:use-module (mcron core) + #:use-module (mcron base) #:use-module (mcron environment) #:use-module (mcron vixie-time) #:use-module (srfi srfi-1) diff --git a/src/mcron/main.scm b/src/mcron/main.scm index 1f2b068..db7dfd6 100644 --- a/src/mcron/main.scm +++ b/src/mcron/main.scm @@ -25,7 +25,7 @@ #:use-module (ice-9 rdelim) #:use-module (ice-9 regex) #:use-module (mcron config) - #:use-module (mcron core) + #:use-module (mcron base) #:use-module (mcron job-specifier) #:use-module (mcron vixie-specification) #:use-module (srfi srfi-2) @@ -389,7 +389,7 @@ option.\n") (lambda () (display (getpid)) (newline))))) ;; Now the main loop. Forever execute the run-job-loop procedure in the - ;; mcron core, and when it drops out (can only be because a message has come + ;; mcron base, and when it drops out (can only be because a message has come ;; in on the socket) we process the socket request before restarting the ;; loop again. Sergey Poznyakoff: we can also drop out of run-job-loop ;; because of a SIGCHLD, so must test FDES-LIST. diff --git a/src/mcron/mcron-core.scm b/src/mcron/mcron-core.scm deleted file mode 100644 index 13781c9..0000000 --- a/src/mcron/mcron-core.scm +++ /dev/null @@ -1,270 +0,0 @@ -;; Copyright (C) 2015, 2016 Mathieu Lirzin -;; Copyright (C) 2003 Dale Mellor -;; -;; This file is part of GNU mcron. -;; -;; GNU mcron is free software: you can redistribute it and/or modify it under -;; the terms of the GNU General Public License as published by the Free -;; Software Foundation, either version 3 of the License, or (at your option) -;; any later version. -;; -;; GNU mcron is distributed in the hope that it will be useful, but WITHOUT -;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -;; more details. -;; -;; You should have received a copy of the GNU General Public License along -;; with GNU mcron. If not, see . - - - -(define-module (mcron core) - #:use-module (mcron environment) - #:use-module (srfi srfi-9) - #:export (add-job - remove-user-jobs - get-schedule - run-job-loop - ;; These three are deprecated and not documented. - use-system-job-list - use-user-job-list - clear-system-jobs) - #:re-export (clear-environment-mods - append-environment-mods)) - - -(use-modules (srfi srfi-1) ;; For remove. - (srfi srfi-2)) ;; For and-let*. - - - -;; The list of all jobs known to the system. Each element of the list is -;; -;; (make-job user next-time-function action environment displayable next-time) -;; -;; where action must be a procedure, and the environment is an alist of -;; modifications that need making to the UNIX environment before the action is -;; run. The next-time element is the only one that is modified during the -;; running of a cron process (i.e. all the others are set once and for all at -;; configuration time). -;; -;; The reason we maintain two lists is that jobs in /etc/crontab may be placed -;; in one, and all other jobs go in the other. This makes it possible to remove -;; all the jobs in the first list in one go, and separately we can remove all -;; jobs from the second list which belong to a particular user. This behaviour -;; is required for full vixie compatibility. - -(define system-job-list '()) -(define user-job-list '()) - -(define configuration-source 'user) - -(define (use-system-job-list) (set! configuration-source 'system)) -(define (use-user-job-list) (set! configuration-source 'user)) - -;; A cron job. -(define-record-type - (make-job user time-proc action environment displayable next-time) - job? - (user job:user) ;object : passwd entry - (time-proc job:next-time-function) ;proc : with one 'time' parameter - (action job:action) ;thunk : user's code - (environment job:environment) ;alist : environment variables - (displayable job:displayable) ;string : visible in schedule - (next-time job:next-time ;number : time in UNIX format - job:next-time-set!)) - -;; Remove jobs from the user-job-list belonging to this user. - -(define (remove-user-jobs user) - (if (or (string? user) - (integer? user)) - (set! user (getpw user))) - (set! user-job-list - (remove (lambda (job) (eqv? (passwd:uid user) - (passwd:uid (job:user job)))) - user-job-list))) - - - -;; Remove all the jobs on the system job list. - -(define (clear-system-jobs) (set! system-job-list '())) - - - -;; Add a new job with the given specifications to the head of the appropriate -;; jobs list. - -(define (add-job time-proc action displayable configuration-time - configuration-user) - (let ((entry (make-job configuration-user - time-proc - action - (get-current-environment-mods-copy) - displayable - (time-proc configuration-time)))) - (if (eq? configuration-source 'user) - (set! user-job-list (cons entry user-job-list)) - (set! system-job-list (cons entry system-job-list))))) - - - -;; Procedure to locate the jobs in the global job-list with the lowest -;; (soonest) next-times. These are the jobs for which we must schedule the mcron -;; program (under any personality) to next wake up. The return value is a cons -;; cell consisting of the next time (maintained in the next-time variable) and a -;; list of the job entries that are to run at this time (maintained in the -;; next-jobs-list variable). -;; -;; The procedure works by first obtaining the time of the first job on the list, -;; and setting this job in the next-jobs-list. Then for each other entry on the -;; job-list, either the job runs earlier than any other that have been scanned, -;; in which case the next-time and next-jobs-list are re-initialized to -;; accomodate, or the job runs at the same time as the next job, in which case -;; the next-jobs-list is simply augmented with the new job, or else the job runs -;; later than others noted in which case we ignore it for now and continue to -;; recurse the list. - -(define (find-next-jobs) - (let ((job-list (append system-job-list user-job-list))) - - (if (null? job-list) - - '(#f . '()) - - (let ((next-time 2000000000) - (next-jobs-list '())) - - (for-each - (lambda (job) - (let ((this-time (job:next-time job))) - (cond ((< this-time next-time) - (set! next-time this-time) - (set! next-jobs-list (list job))) - ((eqv? this-time next-time) - (set! next-jobs-list (cons job next-jobs-list)))))) - job-list) - - (cons next-time next-jobs-list))))) - - - -;; Create a string containing a textual list of the next count jobs to run. -;; -;; Enter a loop of displaying the next set of jobs to run, artificially -;; forwarding the time to the next time point (instead of waiting for it to -;; occur as we would do in a normal run of mcron), and recurse around the loop -;; count times. -;; -;; Note that this has the effect of mutating the job timings. Thus the program -;; must exit after calling this function; the internal data state will be left -;; unusable. - -(define (get-schedule count) - (with-output-to-string - (lambda () - (do ((count count (- count 1))) - ((eqv? count 0)) - (and-let* - ((next-jobs (find-next-jobs)) - (time (car next-jobs)) - (date-string (strftime "%c %z\n" (localtime time)))) - (for-each (lambda (job) - (display date-string) - (display (job:displayable job)) - (newline)(newline) - (job:next-time-set! job ((job:next-time-function job) - (job:next-time job)))) - (cdr next-jobs))))))) - - - -;; For proper housekeeping, it is necessary to keep a record of the number of -;; child processes we fork off to run the jobs. - -(define number-children 0) - - - -;; For every job on the list, fork a process to run it (noting the fact by -;; increasing the number-children counter), and in the new process set up the -;; run-time environment exactly as it should be before running the job proper. -;; -;; In the parent, update the job entry by computing the next time the job needs -;; to run. - -(define (run-jobs jobs-list) - (for-each - (lambda (job) - (if (eqv? (primitive-fork) 0) - (begin - (setgid (passwd:gid (job:user job))) - (setuid (passwd:uid (job:user job))) - (chdir (passwd:dir (job:user job))) - (modify-environment (job:environment job) (job:user job)) - ((job:action job)) - (primitive-exit 0)) - (begin - (set! number-children (+ number-children 1)) - (job:next-time-set! job ((job:next-time-function job) - (current-time)))))) - jobs-list)) - - - -;; Give any zombie children a chance to die, and decrease the number known to -;; exist. - -(define (child-cleanup) - (do () ((or (<= number-children 0) - (eqv? (car (waitpid WAIT_ANY WNOHANG)) 0))) - (set! number-children (- number-children 1)))) - - - -;; Now the main loop. Loop over all job specifications, get a list of the next -;; ones to run (may be more than one). Set an alarm and go to sleep. When we -;; wake, run the jobs and reap any children (old jobs) that have -;; completed. Repeat ad infinitum. -;; -;; Note that, if we wake ahead of time, it can only mean that a signal has been -;; sent by a crontab job to tell us to re-read a crontab file. In this case we -;; break out of the loop here, and let the main procedure deal with the -;; situation (it will eventually re-call this function, thus maintaining the -;; loop). - -(define (run-job-loop . fd-list) - - (call-with-current-continuation - (lambda (break) - - (let ((fd-list (if (null? fd-list) '() (car fd-list)))) - - (let loop () - - (let* ((next-jobs (find-next-jobs)) - (next-time (car next-jobs)) - (next-jobs-list (cdr next-jobs)) - (sleep-time (if next-time (- next-time (current-time)) - 2000000000))) - - (and (> sleep-time 0) - (if (not (null? - (catch 'system-error - (lambda () - (car (select fd-list '() '() sleep-time))) - (lambda (key . args) ;; Exception add by Sergey - ;; Poznyakoff. - (if (member (car (last args)) - (list EINTR EAGAIN)) - (begin - (child-cleanup) '()) - (apply throw key args)))))) - (break))) - - (run-jobs next-jobs-list) - - (child-cleanup) - - (loop))))))) diff --git a/src/mcron/vixie-specification.scm b/src/mcron/vixie-specification.scm index 5cd1528..f055383 100644 --- a/src/mcron/vixie-specification.scm +++ b/src/mcron/vixie-specification.scm @@ -30,7 +30,7 @@ read-vixie-file check-system-crontab) #:use-module ((mcron config) :select (config-socket-file)) - #:use-module (mcron core) + #:use-module (mcron base) #:use-module (mcron job-specifier) #:use-module (mcron redirect) #:use-module (mcron vixie-time)) -- cgit v1.2.3 From 31baff1a5187d8ddc89324cbe42dbeffc309c962 Mon Sep 17 00:00:00 2001 From: Mathieu Lirzin Date: Sat, 7 May 2016 18:51:49 +0200 Subject: job-specifier: job: Add #:user keyword argument. * src/mcron/job-specifier.scm (job): Add #:user keyword argument. * doc/mcron.texi (Job specification): Document it. --- doc/mcron.texi | 25 +++++++++++++------------ src/mcron/job-specifier.scm | 12 ++++++++---- 2 files changed, 21 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/mcron.texi b/doc/mcron.texi index 340faca..a59505d 100644 --- a/doc/mcron.texi +++ b/doc/mcron.texi @@ -271,11 +271,13 @@ on your system, as root. @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. +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 @@ -342,13 +344,12 @@ on Vixie syntax for this. @cindex job execution @cindex command execution @cindex execution -The second argument to the @code{(job)} function can be either a -string, a list, or a function. In all cases the command is executed in -the user's home directory, under the user's own UID. If a string is -passed, it is assumed to be shell script and is executed with the -user's default shell. If a list is passed it is assumed to be scheme -code and is eval'd as such. A supplied function should take exactly -zero arguments, and will be called at the pertinent times. +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 diff --git a/src/mcron/job-specifier.scm b/src/mcron/job-specifier.scm index 9e13551..6dacece 100644 --- a/src/mcron/job-specifier.scm +++ b/src/mcron/job-specifier.scm @@ -212,7 +212,8 @@ go into the list. For example, (range 1 6 2) returns '(1 3 5)." ;; finding the next legitimate time from the current configuration time (set ;; right at the top of this program). -(define (job time-proc action . displayable) +(define* (job time-proc action #:optional displayable + #:key (user configuration-user)) (let ((action (cond ((procedure? action) action) ((list? action) (lambda () (primitive-eval action))) ((string? action) (lambda () (system action))) @@ -231,11 +232,14 @@ go into the list. For example, (range 1 6 2) returns '(1 3 5)." "job: invalid first argument (next-time-function; " "should be function, string or list)")))) (displayable - (cond ((not (null? displayable)) (car displayable)) + (cond (displayable displayable) ((procedure? action) "Lambda function") ((string? action) action) ((list? action) (with-output-to-string - (lambda () (display action))))))) + (lambda () (display action)))))) + (user* (if (or (string? user) (integer? user)) + (getpw user) + user))) (add-job (lambda (current-time) (set! current-action-time current-time) ;; ?? !!!! Code @@ -251,4 +255,4 @@ go into the list. For example, (range 1 6 2) returns '(1 3 5)." action displayable configuration-time - configuration-user))) + user*))) -- cgit v1.2.3