Implement "system" crontabs, with documentation changes

Makefile

@@ -66,6 +66,7 @@ install:
 	$(INSTALL_PROGRAM) -m0700 -g root crond $(DESTDIR)$(SBINDIR)/crond
 	$(INSTALL_PROGRAM) -m4750 -g $(CRONTAB_GROUP) crontab $(DESTDIR)$(BINDIR)/crontab
 	$(INSTALL_DATA) crontab.1 $(DESTDIR)$(MANDIR)/man1/crontab.1
+	$(INSTALL_DATA) crontab.5 $(DESTDIR)$(MANDIR)/man5/crontab.5
 	$(INSTALL_DATA) crond.8 $(DESTDIR)$(MANDIR)/man8/crond.8
 	$(INSTALL_DIR) $(DESTDIR)$(SCRONTABS)
 	$(INSTALL_DIR) $(DESTDIR)$(CRONTABS)
@@ -78,8 +79,9 @@ clean: force
 force: ;
 
 man: force
-	-pandoc -t man -f markdown -s crontab.markdown -o crontab.1
-	-pandoc -t man -f markdown -s crond.markdown -o crond.8
+	-pandoc -t man -f markdown -s crontab.1.markdown -o crontab.1
+	-pandoc -t man -f markdown -s crontab.5.markdown -o crontab.5
+	-pandoc -t man -f markdown -s crond.8.markdown -o crond.8
 
 # for maintainer's use only
 TARNAME = /home/abs/_dcron/dcron-$(VERSION).tar.gz

crond.8

@@ -1,193 +1,191 @@
-.TH CROND 8 "1 May 2011"
+.\" Automatically generated by Pandoc 2.3.1
+.\"
+.TH "CROND" "8" "20 Nov 2019" "" ""
+.hy
 .SH NAME
 .PP
-crond - dillon's lightweight cron daemon
+crond \- dillon's lightweight cron daemon
 .SH SYNOPSIS
 .PP
-\f[B]crond [-s dir] [-c dir] [-t dir] [-m user\@host] [-M mailhandler] [-S|-L file] [-l loglevel] [-b|-f|-d]\f[]
+\f[B]crond [\-s dir] [\-c dir] [\-t dir] [\-m user\@host] [\-M
+mailhandler] [\-S|\-L file] [\-l loglevel] [\-b|\-f|\-d]\f[]
 .SH OPTIONS
 .PP
-\f[B]crond\f[] is a background daemon that parses individual
-crontab files and executes commands on behalf of the users in
-question.
+\f[B]crond\f[] is a background daemon that parses individual crontab
+files and executes commands on behalf of the users in question.
 .TP
-.B -s dir
+.B \-s dir
 directory of system crontabs (defaults to /etc/cron.d)
 .RS
 .RE
 .TP
-.B -c dir
-directory of per-user crontabs (defaults to
-/var/spool/cron/crontabs)
+.B \-c dir
+directory of per\-user crontabs (defaults to /var/spool/cron/crontabs)
 .RS
 .RE
 .TP
-.B -t dir
+.B \-t dir
 directory of timestamps for \@freq and FREQ=\&... jobs (defaults to
 /var/spool/cron/cronstamps)
 .RS
 .RE
 .TP
-.B -m user\@host
-where should the output of cronjobs be directed? (defaults to local
-user) Some mail handlers (like msmtp) can't route mail to local
-users.
-If that's what you're using, then you should supply a remote
-address using this switch.
+.B \-m user\@host
+where should the output of cronjobs be directed?
+(defaults to local user) Some mail handlers (like msmtp) can't route
+mail to local users.
+If that's what you're using, then you should supply a remote address
+using this switch.
 Cron output for all users will be directed to that address.
-Alternatively, you could supply a different mail handler using the
--M switch, to log or otherwise process the messages instead of
-mailing them.
-Alternatively, you could just direct the stdout and stderr of your
-cron jobs to /dev/null.
+Alternatively, you could supply a different mail handler using the \-M
+switch, to log or otherwise process the messages instead of mailing
+them.
+Alternatively, you could just direct the stdout and stderr of your cron
+jobs to /dev/null.
 .RS
 .RE
 .TP
-.B -M mailhandler
-Any output that cronjobs print to stdout or stderr gets formatted
-as an email and piped to \f[C]/usr/sbin/sendmail\ -t\ -oem\ -i\f[].
+.B \-M mailhandler
+Any output that cronjobs print to stdout or stderr gets formatted as an
+email and piped to \f[C]/usr/sbin/sendmail\ \-t\ \-oem\ \-i\f[].
 Attempts to mail this are also logged.
-This switch permits the user to substitute a different mailhandler,
-or a script, for sendmail.
-That custom mailhandler is called with no arguments, and with the
-mail headers and cronjob output supplied to stdin.
-When a custom mailhandler is used, mailing is no longer logged
-(have your mailhandler do that if you want it).
-When cron jobs generate no stdout or stderr, nothing is sent to
-either sendmail or a custom mailhandler.
+This switch permits the user to substitute a different mailhandler, or a
+script, for sendmail.
+That custom mailhandler is called with no arguments, and with the mail
+headers and cronjob output supplied to stdin.
+When a custom mailhandler is used, mailing is no longer logged (have
+your mailhandler do that if you want it).
+When cron jobs generate no stdout or stderr, nothing is sent to either
+sendmail or a custom mailhandler.
 .RS
 .RE
 .TP
-.B -S
+.B \-S
 log events to syslog, using syslog facility LOG_CRON and identity
 `crond' (this is the default behavior).
 .RS
 .RE
 .TP
-.B -L file
+.B \-L file
 log to specified file instead of syslog.
 .RS
 .RE
 .TP
-.B -l loglevel
+.B \-l loglevel
 log events at the specified, or more important, loglevels.
 The default is `notice'.
-Valid level names are as described in logger(1) and syslog(3):
-alert, crit, debug, emerg, err, error (deprecated synonym for err),
-info, notice, panic (deprecated synonym for emerg), warning, warn
-(deprecated synonym for warning).
+Valid level names are as described in logger(1) and syslog(3): alert,
+crit, debug, emerg, err, error (deprecated synonym for err), info,
+notice, panic (deprecated synonym for emerg), warning, warn (deprecated
+synonym for warning).
 .RS
 .RE
 .TP
-.B -b
-run \f[B]crond\f[] in the background (default unless -d or -f is
+.B \-b
+run \f[B]crond\f[] in the background (default unless \-d or \-f is
 specified)
 .RS
 .RE
 .TP
-.B -f
+.B \-f
 run \f[B]crond\f[] in the foreground.
-All log messages are sent to stderr instead of syslog or a -L file.
+All log messages are sent to stderr instead of syslog or a \-L file.
 .RS
 .RE
 .TP
-.B -d
+.B \-d
 turn on debugging.
-This option sets the logging level to `debug' and causes
-\f[B]crond\f[] to run in the foreground.
+This option sets the logging level to `debug' and causes \f[B]crond\f[]
+to run in the foreground.
 .RS
 .RE
 .SH DESCRIPTION
 .PP
-\f[B]crond\f[] is responsible for scanning the crontab files and
-running their commands at the appropriate time.
-It always synchronizes to the top of the minute, matching the
-current time against its internal list of parsed crontabs.
+\f[B]crond\f[] is responsible for scanning the crontab files and running
+their commands at the appropriate time.
+It always synchronizes to the top of the minute, matching the current
+time against its internal list of parsed crontabs.
 That list is stored so that it can be scanned very quickly, and
 \f[B]crond\f[] can deal with several hundred crontabs with several
 thousand entries without using noticeable CPU.
 .PP
-Cron jobs are not re-executed if a previous instance of them is
-still running.
-For example, if you have a crontab command \f[C]sleep\ 70\f[], that
-you request to be run every minute, \f[B]crond\f[] will skip this
-job when it sees it is still running.
-So the job won't be run more frequently than once every two
-minutes.
+Cron jobs are not re\-executed if a previous instance of them is still
+running.
+For example, if you have a crontab command \f[C]sleep\ 70\f[], that you
+request to be run every minute, \f[B]crond\f[] will skip this job when
+it sees it is still running.
+So the job won't be run more frequently than once every two minutes.
 If you do not like this feature, you can run your commands in the
 background with an \f[C]&\f[].
 .PP
-\f[B]crond\f[] automatically detects when the clock has been
-changed, during its per-minute scans.
-Backwards time-changes of an hour or less won't re-run cron jobs
-from the intervening period.
-\f[B]crond\f[] will effectively sleep until it catches back up to
-the original time.
-Forwards time-changes of an hour or less (or if the computer is
-suspended and resumed again within an hour) will run any missed
-jobs exactly once.
-Changes greater than an hour in either direction cause
-\f[B]crond\f[] to re-calculate when jobs should be run, and not
-attempt to execute any missed commands.
-This is effectively the same as if \f[B]crond\f[] had been stopped
-and re-started.
-.PP
-For example, suppose it's 10 am, and a job is scheduled to run
-every day at 10:30 am.
-If you set the system's clock forward to 11 am, crond will
-immediately run the 10:30 job.
-If on the other hand you set the system's clock forward to noon,
-the 10:30 am job will be skipped until the next day.
+\f[B]crond\f[] automatically detects when the clock has been changed,
+during its per\-minute scans.
+Backwards time\-changes of an hour or less won't re\-run cron jobs from
+the intervening period.
+\f[B]crond\f[] will effectively sleep until it catches back up to the
+original time.
+Forwards time\-changes of an hour or less (or if the computer is
+suspended and resumed again within an hour) will run any missed jobs
+exactly once.
+Changes greater than an hour in either direction cause \f[B]crond\f[] to
+re\-calculate when jobs should be run, and not attempt to execute any
+missed commands.
+This is effectively the same as if \f[B]crond\f[] had been stopped and
+re\-started.
+.PP
+For example, suppose it's 10 am, and a job is scheduled to run every day
+at 10:30 am.
+If you set the system's clock forward to 11 am, crond will immediately
+run the 10:30 job.
+If on the other hand you set the system's clock forward to noon, the
+10:30 am job will be skipped until the next day.
 Jobs scheduled using \@daily and the like work differently; see
 crontab(1) for details.
 .PP
-\f[B]crond\f[] has a number of built in limitations to reduce the
-chance of it being ill-used.
-Potentially infinite loops during parsing are dealt with via a
-failsafe counter, and non-root crontabs are limited to 256 crontab
-entries.
+\f[B]crond\f[] has a number of built in limitations to reduce the chance
+of it being ill\-used.
+Potentially infinite loops during parsing are dealt with via a failsafe
+counter, and non\-root crontabs are limited to 256 crontab entries.
 Crontab lines may not be longer than 1024 characters, including the
 newline.
 .PP
-Whenever \f[B]crond\f[] must run a job, it first creates a
-daemon-owned temporary file O_EXCL and O_APPEND to store any
-output, then fork()s and changes its user and group permissions to
-match that of the user the job is being run for, then
-\f[B]exec\f[]s \f[B]/bin/sh -c \f[] to run the job.
-The temporary file remains under the ownership of the daemon to
-prevent the user from tampering with it.
-Upon job completion, \f[B]crond\f[] verifies the secureness of the
-mail file and, if it has been appended to, mails the file to the
-specified address.
-The \f[B]sendmail\f[] program (or custom mail handler, if supplied)
-is run under the user's uid to prevent mail related security holes.
+Whenever \f[B]crond\f[] must run a job, it first creates a daemon\-owned
+temporary file O_EXCL and O_APPEND to store any output, then fork()s and
+changes its user and group permissions to match that of the user the job
+is being run for, then \f[B]exec\f[]s \f[B]/bin/sh \-c \f[] to run the
+job.
+The temporary file remains under the ownership of the daemon to prevent
+the user from tampering with it.
+Upon job completion, \f[B]crond\f[] verifies the secureness of the mail
+file and, if it has been appended to, mails the file to the specified
+address.
+The \f[B]sendmail\f[] program (or custom mail handler, if supplied) is
+run under the user's uid to prevent mail related security holes.
 .PP
 When a user edits their crontab, \f[B]crontab\f[] first copies the
-crontab to a user owned file before running the user's preferred
-editor.
-The suid \f[B]crontab\f[] keeps an open descriptor to the file
-which it later uses to copy the file back, thereby ensuring the
-user has not tampered with the file type.
-.PP
-\f[B]crontab\f[] notifies \f[B]crond\f[] that a user's crontab file
-has been modified (or created or deleted) through the
-\[lq]cron.update\[rq] file, which resides in the per-user crontabs
-directory (usually /var/spool/cron/crontabs).
-\f[B]crontab\f[] appends the filename of the modified crontab file
-to \[lq]cron.update\[rq]; and \f[B]crond\f[] inspects this file to
+crontab to a user owned file before running the user's preferred editor.
+The suid \f[B]crontab\f[] keeps an open descriptor to the file which it
+later uses to copy the file back, thereby ensuring the user has not
+tampered with the file type.
+.PP
+\f[B]crontab\f[] notifies \f[B]crond\f[] that a user's crontab file has
+been modified (or created or deleted) through the \[lq]cron.update\[rq]
+file, which resides in the per\-user crontabs directory (usually
+/var/spool/cron/crontabs).
+\f[B]crontab\f[] appends the filename of the modified crontab file to
+\[lq]cron.update\[rq]; and \f[B]crond\f[] inspects this file to
 determine when to reparse or otherwise update its internal list of
 parsed crontabs.
 .PP
 Whenever a \[lq]cron.update\[rq] file is seen, \f[B]crond\f[] also
-re-reads timestamp files from its timestamp directory (usually
+re\-reads timestamp files from its timestamp directory (usually
 /var/spool/cron/cronstamps).
 Normally these will just mirror \f[B]crond\f[]'s own internal
-representations, but this mechanism could be used to manually
-notify \f[B]crond\f[] that you've externally updated the
-timestamps.
+representations, but this mechanism could be used to manually notify
+\f[B]crond\f[] that you've externally updated the timestamps.
 .PP
-The \[lq]cron.update\[rq] file can also be used to ask
-\f[B]crond\f[] to schedule a \[lq]named\[rq] cron job.
+The \[lq]cron.update\[rq] file can also be used to ask \f[B]crond\f[] to
+schedule a \[lq]named\[rq] cron job.
 To do this, append a line of the form:
 .IP
 .nf
@@ -197,40 +195,36 @@ clio\ job1\ !job2
 .fi
 .PP
 to \[lq]cron.update\[rq].
-This request that user clio's job1 should be scheduled (waiting
-first for the successful completion of any jobs named in job1's
-AFTER= tag), and job2 should also be scheduled (without waiting for
-other jobs).
+This request that user clio's job1 should be scheduled (waiting first
+for the successful completion of any jobs named in job1's AFTER= tag),
+and job2 should also be scheduled (without waiting for other jobs).
 See crontab(1) for more about tags and named jobs.
 .PP
-The directory of per-user crontabs is re-parsed once every hour in
-any case.
-Any crontabs in the system directory (usually /etc/cron.d) are
-parsed at the same time.
+The directory of per\-user crontabs is re\-parsed once every hour in any
+case.
+Any crontabs in the system directory (usually /etc/cron.d) are parsed at
+the same time.
 This directory can be used by packaging systems.
-When you install a package foo, it might write its own foo-specific
+When you install a package foo, it might write its own foo\-specific
 crontab to /etc/cron.d/foo.
 .PP
-The superuser has a per-user crontab along with other users.
+The superuser has a per\-user crontab along with other users.
 It usually resides at /var/spool/cron/crontabs/root.
 .PP
 Users can only have a crontab if they have an entry in /etc/passwd;
 however they do not need to have login shell privileges.
-Cron jobs are always run under /bin/sh; see crontab(1) for more
-details.
+Cron jobs are always run under /bin/sh; see crontab(1) for more details.
 .PP
-Unlike \f[B]crontab\f[], the \f[B]crond\f[] program does not keep
-open descriptors to crontab files while running their jobs, as this
-could cause \f[B]crond\f[] to run out of descriptors.
+Unlike \f[B]crontab\f[], the \f[B]crond\f[] program does not keep open
+descriptors to crontab files while running their jobs, as this could
+cause \f[B]crond\f[] to run out of descriptors.
 .SH SEE ALSO
 .PP
-\f[B]crontab\f[](1)
+\f[B]crontab\f[](1) \f[B]crontab\f[](5)
 .SH AUTHORS
 .PP
-Matthew Dillon (dillon\@apollo.backplane.com): original
-developer
+Matthew Dillon (dillon\@apollo.backplane.com): original developer
 .PD 0
 .P
 .PD
-Jim Pryor (profjim\@jimpryor.net): current
-developer
+James Pryor (dubiousjim\@gmail.com): current developer

crond.markdown → crond.8.markdown

@@ -178,6 +178,7 @@ out of descriptors.
 SEE ALSO
 ========
 **crontab**(1)
+**crontab**(5)
 
 AUTHORS
 =======