diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/config.texi.in | 5 | ||||
| -rw-r--r-- | doc/mcron.texi | 1337 |
2 files changed, 0 insertions, 1342 deletions
diff --git a/doc/config.texi.in b/doc/config.texi.in deleted file mode 100644 index 50d9a18..0000000 --- a/doc/config.texi.in +++ /dev/null @@ -1,5 +0,0 @@ -@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 deleted file mode 100644 index cb97a06..0000000 --- a/doc/mcron.texi +++ /dev/null @@ -1,1337 +0,0 @@ -\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 ``/<number>'' specifies skips of the number's value -through the range. For example, ``0-23/2'' can be used in the hours -field to specify command execution every other hour (the alternative -in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are -also permitted after an asterisk, so if you want to say ``every two -hours'', just use ``*/2''. - -@cindex names in vixie-style time specifications -Names can also be used for the ``month'' and ``day of week'' -fields. Use the first three letters of the particular -day or month (case doesn't matter). Ranges or -lists of names are not allowed. @footnote{Mcron allows any alphabetic -characters after a name, so full names of days or months are also valid.} - -@cindex % character on vixie-style commands -@cindex standard input, vixie-style -The ``sixth'' field (the rest of the line) specifies the command to be -run. -The entire command portion of the line, up to a newline or % -character, will be executed by /bin/sh or by the shell -specified in the SHELL variable of the cronfile. -Percent-signs (%) in the command, unless escaped with backslash -(\\), will be changed into newline characters, and all data -after the first % will be sent to the command as standard -input. - -@cindex day specification, vixie-style -@cindex vixie-style day specification -Note: The day of a command's execution can be specified by two -fields -- day of month, and day of week. If both fields are -restricted (ie, aren't *), the command will be run when -@emph{either} -field matches the current time. For example, - -``30 4 1,15 * 5'' - -would cause a command to be run at 4:30 am on the 1st and 15th of each -month, plus every Friday. - -EXAMPLE CRON FILE - -@example -# use /bin/sh to run commands, no matter what /etc/passwd says -SHELL=/bin/sh -# mail any output to `paul', no matter whose crontab this is -MAILTO=paul -# -# run five minutes after midnight, every day -5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 -# run at 2:15pm on the first of every month -- output mailed to paul -15 14 1 * * $HOME/bin/monthly -# run at 10 pm on weekdays, annoy Joe -0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% -23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" -5 4 * * sun echo "run at 5 after 4 every sunday" -@end example - -@node Incompatibilities with old Unices, , Crontab file, Vixie Syntax -@subsection Extensions and incompatibilities -@cindex incompatibilities with old Unices -@cindex extensions, vixie over old Unices -This section lists differences between Paul Vixie's cron and the -olde-worlde BSD and AT&T programs, for the benefit of system -administrators and users who are upgrading all the way. - -@itemize @bullet -@item -@cindex day 7 -When specifying day of week, both day 0 and day 7 will be considered Sunday. -BSD and AT&T seem to disagree about this. - -@item -Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would -be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY. - -@item -Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". - -@item -Names of months or days of the week can be specified by name. - -@item -Environment variables can be set in the crontab. In BSD or AT&T, the -environment handed to child processes is basically the one from /etc/rc. - -@item -Command output is mailed to the crontab owner (BSD can't do this), can be -mailed to a person other than the crontab owner (SysV can't do this), or the -feature can be turned off and no mail will be sent at all (SysV can't do this -either). - -@end itemize - - -@node Invoking, Guile modules, Syntax, Top -@chapter Detailed invoking -@cindex invoking -@cindex personality -@cindex mcron program -@cindex cron program -@cindex crond program -@cindex crontab program -The program adopts one of three different personalities depending on -the name used to invoke it. In a standard installation, the program is -installed in the system under the names mcron, cron and crontab -(installed SUID). - -The recommended way to invoke the program is via the mcron personality -described in the next section. The program can also be run as cron by -root, and by the SUID program crontab by individual users to gain -backwards compatibility with Vixie cron. However, due to the fact that -this daemon process is shared by, and under control of, all the users -of the system it is possible (though very unlikely) that it may become -unusable, hence the recommendation to use the mcron personality. - -@cindex deprecated, vixie personality -Furthermore, the Vixie personality is considered deprecated by this -author (it offers not a single advantage over the mcron personality, -and bloats the code by a factor of three). It is unlikely that this -personality will ever actually go away, but the program may in future -be split into two distinct parts, and new developments will only take -place in the part which implements the mcron personality. - - - -@menu -* Invoking mcron:: -* Invoking cron or crond:: -* Invoking crontab:: -* Behaviour on laptops:: -* Exit codes:: -@end menu - -@node Invoking mcron, Invoking cron or crond, Invoking, Invoking -@section Invoking mcron -@cindex invoking mcron -@cindex mcron options -@cindex mcron arguments -@cindex command line, mcron -@cindex mcron command line -Mcron should be run by the user who wants to schedule his jobs. It -may be made a background job using the facilities of the shell. The -basic command is @code{mcron [OPTION ...] [file ...]} which has the -effect of reading all the configuration files specified (subject to -the options) and then waiting until it is time to execute some -command. If no files are given on the command line, then mcron will -look in the user's cron configuration directories: these are ~/.cron -(deprecated), the directory indicated by the @code{XDG_CONFIG_HOME} -environment variable, or ~/.config/cron if this variable is not set. -In any case, files which end in the extension .vixie or .vix will be -assumed to contain Vixie-style crontabs, and files ending .guile or -.gle will be assumed to contain scheme code and will be executed as -such; ANY OTHER FILES WILL BE IGNORED - specify a file name of ``-'' -and then pipe the files into the standard input if you really want to -read them, possibly using the @code{stdin} option to specify the type -of file. - -The program accepts the following options. - -@table @option -@item -s count -@itemx --schedule=count -@cindex printout of jobs schedule -@cindex schedule of jobs, listing -@cindex options, schedule -@cindex options, -s -@cindex -s option -@cindex --schedule option -With this option specified no commands are run. Instead, the program -computes the times the commands would be run and prints the -information to the screen, and then immediately exits. - -The count indicates the number of commands to display. - -@cindex daemon option -@cindex options, daemon -@cindex options, -d -@cindex -d option -@cindex --daemon option -@item -d -@itemx --daemon -With this option the program will detach itself from the controlling -terminal and run as a daemon process. - -@cindex stdin option -@cindex options, stdin -@cindex options, -i -@cindex -i option -@cindex --stdin option -@cindex standard input, configuring from -@cindex configuring from standard input -@item -i (vixie|guile) -@itemx --stdin=(vixie|guile) -This option is used to indicate whether the configuration information -being passed on the standard input is in Vixie format or Guile -format. Guile is the default. - -@cindex -v option -@cindex --version option -@cindex options, -v -@cindex options, version -@item -v -@itemx --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - -@cindex -h option -@cindex --help option -@cindex options, -h -@cindex options, --help -@item -h -@itemx --help -This causes a short but complete usage message to be displayed on -standard output. - -@end table - -@node Invoking cron or crond, Invoking crontab, Invoking mcron, Invoking -@section Invoking cron or crond -@cindex cron, invokation -@cindex invoking cron -@cindex crond, invokation -@cindex invoking crond -@cindex @value{CONFIG_SPOOL_DIR} -@cindex @value{CONFIG_SOCKET_FILE} -NOTE THAT THIS SECTION ONLY APPLIES IF THE @code{cron} or -@code{crond}, and @code{crontab} PROGRAMS HAVE BEEN INSTALLED BY THE -SYSTEM ADMINISTRATOR. - -If the program runs by the name of @code{cron} or @code{crond}, then -it will read all the files in @code{@value{CONFIG_SPOOL_DIR}} (which -should only be readable by root) and the file @code{/etc/crontab}, and -then detaches itself from the terminal to live forever as a daemon -process. Additionally, it creates a UNIX socket at -@code{@value{CONFIG_SOCKET_FILE}}, and listens for messages sent to -that socket consisting of a user name whose crontabs have been -changed. In this case, the program will re-read that user's crontab. -This is for correct functioning with the crontab program. - -Further, if the @code{--noetc} option was not used, a job is scheduled -to run every minute to check if /etc/crontab has been modified -recently. If so, this file will also be re-read. - -The options which may be used with this program are as follows. - -@table @option - -@cindex -v option -@cindex --version option -@cindex options, -v -@cindex options, version -@item -v -@itemx --version -This option causes a message to be printed on the standard output with -information about the version and copyright for the current program. - -@cindex -h option -@cindex --help option -@cindex options, -h -@cindex options, --help -@item -h -@itemx --help -This causes a short but complete usage message to be displayed on -standard output. - -@item -s [count] -@itemx --schedule[=count] -@cindex printout of jobs schedule -@cindex schedule of jobs, listing -@cindex options, schedule -@cindex options, -s -@cindex -s option -@cindex --schedule option -With this option specified no commands are run. Instead, the program -computes the times the commands would be run and prints the -information to the screen, and then immediately exits. - -The count, if supplied, indicates the number of commands to -display. The default value is 8. - -@cindex -n option -@cindex --noetc option -@cindex options, -n -@cindex options, --noetc -@item -n -@itemx --noetc -This tells cron not to add a job to the system which wakes up every -minute to check for modifications to @code{/etc/crontab}. It is -recommended that this option be used (and further that the -@code{/etc/crontab} file be taken off the system altogether!) - -@end table - -@node Invoking crontab, Behaviour on laptops, Invoking cron or crond, Invoking -@section Invoking crontab -@cindex crontab, invoking -@cindex invoking crontab -This program is run by individual users to inspect or modify their -crontab files. If a change is made to the file, then the root daemon -process will be given a kick, and will immediately read the new -configuration. A warning will be issued to standard output if it -appears that a cron daemon is not running. - -The command is used as - -@code{crontab [-u user] file} - -or - -@code{crontab [-u user] ( -l | -e | -r )} - -Only the root user can use the -u option, to specify the manipulation -of another user's crontab file. In the first instance, the entire -crontab file of the user is replaced with the contents of the -specified file, or standard input if the file is ``-''. - -In the latter case, the program behaves according to which of the -(mutually exclusive) options was given (note that the long options are -an mcron extension). - -@table @option - -@cindex -l option -@cindex list option, crontab -@cindex options, -l -@cindex options, --list -@cindex viewing a crontab -@cindex listing a crontab -@item -l -@itemx --list -Print the user's crontab file to the standard output, and exit. - -@cindex -r option -@cindex remove option -@cindex options, -r -@cindex options, --remove -@cindex deleting a crontab -@cindex removing a crontab -@item -r -@item --remove -Delete the user's crontab file, and exit. - -@cindex -e option -@cindex edit option -@cindex options, -e -@cindex options, --edit -@cindex editing a crontab -@cindex creating a crontab -@item -e -@item --edit -Using the editor specified in the user's VISUAL or EDITOR environment -variables, allow the user to edit his crontab. Once the user exits the -editor, the crontab is checked for parseability, and if it is okay -then it is installed as the user's new crontab and the daemon is -notified that a change has taken place, so that the new file will -become immediately effective. - -@end table - - -@node Behaviour on laptops, Exit codes, Invoking crontab, Invoking -@section Behaviour on laptops -@cindex laptops -@cindex power suspend -While mcron has not been designed to work anachronistically, the behaviour of -mcron when a laptop emerges from a suspended state is well defined, and the -following description explains what happens in this situation. - -When a laptop awakes from a suspended state, all jobs which would have run while -the laptop was suspended will run exactly once immediately (and simultaneously) -when the laptop awakes, and then the next time that those jobs run will be -computed based on the time the laptop was awoken. Any jobs which would not have -run during the suspense period will be unaffected, and will still run at their -proper times. - - -@node Exit codes, , Behaviour on laptops, Invoking -@section Exit codes -@cindex exit codes -@cindex error conditions -@cindex errors -The following are the status codes returned to the operating system -when the program terminates. - -@table @asis -@item 0 -No problems. - -@item 1 -An attempt has been made to start cron but there is already a -@value{CONFIG_PID_FILE} file. If there really is no other cron daemon -running (this does not include invokations of mcron) then you should -remove this file before attempting to run cron. - -@item 2 -In parsing a guile configuration file, a @code{job} command has been -seen but the second argument is neither a procedure, list or -string. This argument is the job's action, and needs to be specified -in one of these forms. - -@item 3 -In parsing a guile configuration file, a @code{job} command has been -seen but the first argument is neither a procedure, list or -string. This argument is the job's next-time specification, and needs -to be specified in one of these forms. - -@item 4 -An attempt to run cron has been made by a user who does not have -permission to access the crontabs in @value{CONFIG_SPOOL_DIR}. These -files should be readable only by root, and the cron daemon must be run -as root. - -@item 5 -An attempt to run mcron has been made, but there are no jobs to -schedule! - -@item 6 -The system administrator has blocked this user from using crontab with -the files @value{CONFIG_ALLOW_FILE} and @value{CONFIG_DENY_FILE}. - -@item 7 -Crontab has been run with more than one of the arguments @code{-l}, -@code{-r}, @code{-e}. These are mutually exclusive options. - -@item 8 -Crontab has been run with the -u option by a user other than -root. Only root is allowed to use this option. - -@item 9 -An invalid vixie-style time specification has been supplied. - -@item 10 -An invalid vixie-style job specification has been supplied. - -@item 11 -A bad line has been seen in /etc/crontab. - -@item 12 -The last component of the name of the program was not one of -@code{mcron}, @code{cron}, @code{crond} or @code{crontab}. - -@item 13 -Either none of the user's configuration directories exist, or there is a problem -reading the files there. The configuration directories are ~/.cron -and the directory pointed to by the @code{XDG_CONFIG_HOME} environment -variable, or ~/.config/cron if this is not set. - -@c @item 14 -@c There is a problem writing to /var/cron/update. This is probably -@c because the crontab program is not installed SUID root, as it should -@c be. - -@item 15 -Crontab has been run without any arguments at all. There is no default -behaviour in this case. - -@item 16 -Cron has been run by a user other than root. - -@end table - - - -@node Guile modules, Index, Invoking, Top -@chapter Guile modules -Some of the key parts of mcron are implemented as modules so they can -be incorporated into other Guile programs, or even into C-sourced -programs if they are linked against libguile. - -It may be, for example, that a program needs to perform house-keeping -functions at certain times of the day, in which case it can spawn -(either fork or thread) a sub-process which uses a built-in -mcron. Another example may be a program which must sleep until some -non-absolute time specified on the Gregorian calendar (the first day -of next week, for example). Finally, it may be the wish of the user to -provide a program with the functionality of mcron plus a bit extra. - -The 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 |