From 88ada6d2b7b715b281f02220de803e9483469307 Mon Sep 17 00:00:00 2001 From: wiz Date: Sat, 4 Apr 2009 17:29:59 +0000 Subject: [PATCH] Convert to mdoc. Bump date for previous. --- usr.sbin/cron/crontab.5 | 488 ++++++++++++++++++++++++---------------- 1 file changed, 289 insertions(+), 199 deletions(-) diff --git a/usr.sbin/cron/crontab.5 b/usr.sbin/cron/crontab.5 index 1a5a4bdb1cd6..4f7b66c7cef3 100644 --- a/usr.sbin/cron/crontab.5 +++ b/usr.sbin/cron/crontab.5 @@ -1,4 +1,4 @@ -.\" $NetBSD: crontab.5,v 1.12 2009/04/04 16:05:10 perry Exp $ +.\" $NetBSD: crontab.5,v 1.13 2009/04/04 17:29:59 wiz Exp $ .\" .\"/* Copyright 1988,1990,1993,1994 by Paul Vixie .\" * All rights reserved @@ -19,199 +19,275 @@ .\" .\" Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp .\" -.TH CRONTAB 5 "24 January 1994" -.UC 4 -.SH NAME -crontab \- tables for driving cron -.SH DESCRIPTION +.Dd April 4, 2009 +.Dt CRONTAB 5 +.Os +.Sh NAME +.Nm crontab +.Nd tables for driving cron +.Sh DESCRIPTION A -.I crontab +.Nm file contains instructions to the -.IR cron (8) -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 -.IR su (1) +.Xr cron 8 +daemon of the general form: +.Dq 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 +.Xr su 1 as part of a cron command. -.PP -Blank lines and leading spaces and tabs are ignored. Lines whose first -non-space character is a pound-sign (#) are comments, and are ignored. +.Pp +Blank lines and leading spaces and tabs are ignored. +Lines whose first non-space character is a pound-sign +.Pq Sq # +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 +they will be taken to be part of the command. +Similarly, comments are not allowed on the same line as environment variable settings. -.PP -An active line in a crontab will be either an environment setting or a cron -command. An environment setting is of the form, -.PP +.Pp +An active line in a crontab will be either an environment setting +or a cron command. +An environment setting is of the form, +.Bd -literal name = value -.PP -where the spaces around the equal-sign (=) are optional, and any subsequent -non-leading spaces in -.I value +.Ed +where the spaces around the equal-sign +.Pq Sq = +are optional, and any subsequent non-leading spaces in +.Ar value will be part of the value assigned to -.IR name . +.Ar name . The -.I value -string may be placed in quotes (single or double, but matching) to preserve -leading or trailing blanks. The -.I name -string may also be placed in quotes (single or double, but matching) to preserve -leading, trailing or inner blanks. -.PP -Several environment variables are set up -automatically by the -.IR cron (8) +.Ar value +string may be placed in quotes (single or double, but matching) to +preserve leading or trailing blanks. +The +.Ar name +string may also be placed in quotes (single or double, but matching) +to preserve leading, trailing or inner blanks. +.Pp +Several environment variables are set up automatically by the +.Xr cron 8 daemon. -SHELL is set to /bin/sh, and LOGNAME and HOME are set from the /etc/passwd +.Ev SHELL +is set to +.Pa /bin/sh , +and +.Ev LOGNAME +and +.Ev HOME +are set from the +.Pa /etc/passwd line of the crontab's owner. -HOME and SHELL may be overridden by settings in the crontab; LOGNAME may not. -.PP -(Another note: the LOGNAME variable is sometimes called USER on BSD systems... -on these systems, USER will be set also.) -.PP -In addition to LOGNAME, HOME, and SHELL, -.IR cron (8) -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. -.PP +.Ev HOME +and +.Ev SHELL +may be overridden by settings in the crontab; +.Ev LOGNAME +may not. +.Pp +(Another note: the +.Ev LOGNAME +variable is sometimes called +.Ev USER +on BSD systems... on these systems, +.Ev USER +will be set also.) +.Pp +In addition to +.Ev LOGNAME , +.Ev HOME , +and +.Ev SHELL , +.Xr cron 8 +will look at +.Ev MAILTO +if it has any reason to send mail as a result of running commands in +.Dq this +crontab. +If +.Ev MAILTO +is defined (and non-empty), mail is sent to the user so named. +If +.Ev MAILTO +is defined but empty +.Pq Ev MAILTO Ns = Ns \&"" , +no mail will be sent. +Otherwise mail is sent to the owner of the crontab. +This option is useful if you decide on +.Xr mail 1 +instead of +.Xr sendmail 1 +as your mailer when you install cron -- +.Xr mail 1 +doesn't do aliasing, and UUCP usually doesn't read its mail. +.Pp In order to provide finer control over when jobs execute, users -can also set the environment variables CRON_TZ and CRON_WITHIN. -The CRON_TZ variable can be set to an alternate time zone in order -to affect when the job is run. Note that this only affects the -scheduling of the job, not the time zone that the job perceives -when it is run. If CRON_TZ is defined but empty (CRON_TZ=""), jobs -are scheduled with respect to the local time zone. -.PP -The CRON_WITHIN variable should indicate the number of seconds -within a job's scheduled time that it should still be run. On a -heavily loaded system, or on a system that has just been "woken -up", jobs will sometimes start later than originally intended, and -by skipping non-critical jobs because of delays, system load can -be lightened. If CRON_WITHIN is defined but empty (CRON_WITHIN="") or -set to some non-positive value (0, a negative number, or a non-numeric -string), it is treated as if it was unset. -.PP -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 -.IR cron (8) -when the minute, hour, and month of year fields match the current time, -.I and +can also set the environment variables +.Ev CRON_TZ +and +.Ev CRON_WITHIN . +The +.Ev CRON_TZ +variable can be set to an alternate time zone in order to affect +when the job is run. +Note that this only affects the scheduling of the job, not the time +zone that the job perceives when it is run. +If +.Ev CRON_TZ +is defined but empty +.Pq Ev CRON_TZ Ns = Ns \&"" , +jobs are scheduled with respect to the local time zone. +.Pp +The +.Ev CRON_WITHIN +variable should indicate the number of seconds within a job's +scheduled time that it should still be run. +On a heavily loaded system, or on a system that has just been +.Dq woken up , +jobs will sometimes start later than originally intended, and by +skipping non-critical jobs because of delays, system load can be +lightened. +If +.Ev CRON_WITHIN +is defined but empty +.Pa Ev CRON_WITHIN Ns = Ns \&"" +or set to some non-positive value (0, a negative number, or a +non-numeric string), it is treated as if it was unset. +.Pp +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 +.Xr cron 8 +when the minute, hour, and month of year fields match the current +time, +.Em and when at least one of the two day fields (day of month, or day of week) -match the current time (see ``Note'' below). -.IR cron (8) +match the current time (see +.Dq Note +below). +.Xr cron 8 examines cron entries once every minute. The time and date fields are: -.IP -.ta 1.5i -field allowed values -.br ------ -------------- -.br -minute 0-59 -.br -hour 0-23 -.br -.\" changed from 0-31 to 1-31: mouse, 1997-07-13 -day of month 1-31 -.br -.\" changed from 0-12 to 1-12: mouse, 1997-07-13 -month 1-12 (or names, see below) -.br -day of week 0-7 (0 or 7 is Sun, or use names) -.br -.PP -A field may be an asterisk (*), which always stands for ``first\-last''. -.PP -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. -.PP -A field may begin with a question mark (?), which indicates a -single value randomly selected when the crontab file is read. +.Bl -column -offset indent "day of month" "0-7 (0 or 7 is Sun, or use names)" +.It Em field Ta Em allowed values +.It minute Ta 0-59 +.It hour Ta 0-23 +.It day of month Ta 1-31 +.It month Ta 1-12 (or names, see below) +.It day of week Ta 0-7 (0 or 7 is Sun, or use names) +.El +.Pp +A field may be an asterisk +.Pq Sq * , +which always stands for +.Dq first\-last . +.Pp +Ranges of numbers are allowed. +Ranges are two numbers separated with a hyphen. +The specified range is inclusive. +For example, +.Dq 8-11 +for an +.Dq hours +entry specifies execution at hours 8, 9, 10, and 11. +.Pp +A field may begin with a question mark +.Pq Sq ? , +which indicates a single value randomly selected when the crontab +file is read. If the field contains only a question mark, the value is randomly selected from the range of all possible values for the field. If the question mark precedes a range, the value is randomly selected from the range. -For example, ``? ?2-5 * * *'' specifies that a task will be performed -daily between 2:00am and and 5:59am at a time randomly selected when -the crontab file is first read. +For example, +.Dq ? ?2-5 * * * +specifies that a task will be performed daily between 2:00am and +and 5:59am at a time randomly selected when the crontab file is +first read. As just one example, this feature can be used to prevent a large number of hosts from contacting a server simultaneously and -overloading it by staggering the time at which a download script is -executed. -.PP -Lists are allowed. A list is a set of numbers (or ranges) -separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''. -.PP -Step values can be used in conjunction with ranges. Following -a range with ``/\*[Lt]number\*[Gt]'' 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''. -.PP -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. -.PP -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. -.PP -Note: The day of a command's execution can be specified by two -fields \(em day of month, and day of week. If both fields are -restricted (ie, aren't *), the command will be run when -.I either -field matches the current time. For example, -.br -``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. -.\" Everything from here to .SH EXAMPLE CRON FILE added: mouse, 1997-07-13 -.PP +overloading it by staggering the time at which a download script +is executed. +.Pp +Lists are allowed. +A list is a set of numbers (or ranges) separated by commas. +Examples: +.Dq 1,2,5,9 , +.Dq 0-4,8-12 . +.Pp +Step values can be used in conjunction with ranges. +Following a range with +.Dq / Ns Aq number +specifies skips of the number's value through the range. +For example, +.Dq 0-23/2 +can be used in the hours field to specify command execution every +other hour (the alternative in the V7 standard is +.Dq 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 +.Dq every two hours , +just use +.Dq */2 . +.Pp +Names can also be used for the +.Dq month +and +.Dq 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. +.Pp +The +.Dq 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 percent +signs +.Pq Sq % , +will be executed by +.Xr sh 1 +or by the shell specified in the +.Ev SHELL +variable of the cronfile. +Percent signs +.Pq Sq % +in the command, unless escaped with backslash +.Pq Sq \e , +will be changed into newline characters, and all data after the +first % will be sent to the command as standard input. +.Pp +.Em Note : +The day of a command's execution can be specified by two fields +\(em day of month, and day of week. +If both fields are restricted (i.e., aren't *), the command will +be run when +.Em either +field matches the current time. +For example, +.Dq 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. +.Pp Instead of the first five fields, one of eight special strings may appear: -.IP -.ta 1.5i -string meaning -.br ------- ------- -.br -@reboot Run once, at startup. -.br -@yearly Run once a year, "0 0 1 1 *". -.br -@annually (same as @yearly) -.br -@monthly Run once a month, "0 0 1 * *". -.br -@weekly Run once a week, "0 0 * * 0". -.br -@daily Run once a day, "0 0 * * *". -.br -@midnight (same as @daily) -.br -@hourly Run once an hour, "0 * * * *". -.br -.SH EXAMPLE CRON FILE -.nf - +.Bl -column -offset indent "@annually" "Run once a month, 0 0 1 * *." +.It Sy string Ta Sy meaning +.It @reboot Ta Run once, at startup. +.It @yearly Ta Run once a year, Dq 0 0 1 1 * . +.It @annually Ta (same as @yearly) +.It @monthly Ta Run once a month, Dq 0 0 1 * * . +.It @weekly Ta Run once a week, Dq 0 0 * * 0 . +.It @daily Ta Run once a day, Dq 0 0 * * * . +.It @midnight Ta (same as @daily) +.It @hourly Ta Run once an hour, Dq 0 * * * * . +.El +.Ss EXAMPLE CRON FILE +.Bd -literal # 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 @@ -226,31 +302,45 @@ MAILTO=paul 23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 5 4 * * sun echo "run at 5 after 4 every sunday" ? ?2-4 1,15 * * echo "random between 2am-4:59am on the 1st and 15th" -.fi -.SH SEE ALSO -cron(8), crontab(1) -.SH EXTENSIONS -When specifying day of week, both day 0 and day 7 will be considered Sunday. +.Ed +.Sh SEE ALSO +.Xr crontab 1 , +.Xr cron 8 +.Sh STANDARDS +When specifying day of week, both day 0 and day 7 will be considered +Sunday. BSD and ATT seem to disagree about this. -.PP -Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would -be rejected by ATT or BSD cron -- they want to see "1-3" or "7,8,9" ONLY. -.PP -Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". -.PP +.Pp +Lists and ranges are allowed to co-exist in the same field. +.Dq 1-3,7-9 +would be rejected by ATT or BSD cron -- they want to see +.Dq 1-3 +or +.Dq 7,8,9 +ONLY. +.Pp +Ranges can include +.Dq steps , +so +.Dq 1-9/2 +is the same as +.Dq 1,3,5,7,9 . +.Pp Names of months or days of the week can be specified by name. -.PP -Environment variables can be set in the crontab. In BSD or ATT, the -environment handed to child processes is basically the one from /etc/rc. -.PP -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). -.\" This next paragraph added: mouse, 1997-07-13 -.PP -All of the `@' commands that can appear in place of the first five fields -are extensions. -.SH AUTHOR -.nf -Paul Vixie \*[Lt]paul@vix.com\*[Gt] +.Pp +Environment variables can be set in the crontab. +In BSD or ATT, the environment handed to child processes is basically +the one from +.Pa /etc/rc . +.Pp +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). +.Pp +All of the +.Sq @ +commands that can appear in place of the first five fields are +extensions. +.Sh AUTHORS +.An Paul Vixie Aq paul@vix.com