Annotation of src/external/bsd/cron/dist/crontab.5, Revision 1.7
1.7 ! wiz 1: .\" $NetBSD: crontab.5,v 1.6 2018/06/14 22:02:57 christos Exp $
1.2 christos 2: .\"
1.1 christos 3: .\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
4: .\" * All rights reserved
5: .\" */
6: .\"
1.6 christos 7: .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
8: .\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc.
1.1 christos 9: .\"
1.6 christos 10: .\" Permission to use, copy, modify, and distribute this software for any
11: .\" purpose with or without fee is hereby granted, provided that the above
12: .\" copyright notice and this permission notice appear in all copies.
13: .\"
14: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
15: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
17: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
20: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21: .\"
22: .\" $OpenBSD: crontab.5,v 1.36 2018/06/13 13:27:37 jmc Exp $
23: .\"
1.7 ! wiz 24: .Dd June 14, 2018
1.2 christos 25: .Dt CRONTAB 5
26: .Os
27: .Sh NAME
28: .Nm crontab
29: .Nd tables for driving cron
30: .Sh DESCRIPTION
1.1 christos 31: A
1.2 christos 32: .Nm
1.1 christos 33: file contains instructions to the
1.2 christos 34: .Xr cron 8
35: daemon of the general form:
1.6 christos 36: .Dq at these times on these dates run this command .
37: There may be a system
38: .Nm
39: and each user may have their own
40: .Nm .
41: Commands in any given
42: .Nm
43: will be
44: executed either as the user who owns the
45: .Nm
46: or, in the case of the system
47: .Nm crontab ,
48: as the user specified on the command line.
49: .Pp
50: While a
51: .Nm
52: is a text file, it is not intended to be directly edited.
53: Creation, modification, and removal of a
54: .Nm
55: should be done using
56: .Xr crontab 1 .
57: .Pp
58: Blank lines, leading spaces, and tabs are ignored.
59: Lines whose first non-space character is a pound sign
60: .Pq Ql #
1.2 christos 61: are comments, and are ignored.
1.6 christos 62: Note that comments are not allowed on the same line as
63: .Xr cron 8
64: commands, since
1.2 christos 65: they will be taken to be part of the command.
66: Similarly, comments are not
1.1 christos 67: allowed on the same line as environment variable settings.
1.2 christos 68: .Pp
1.6 christos 69: An active line in a
70: .Nm
71: is either an environment variable setting or a
72: .Xr cron 8
73: command.
74: .Pp
75: Environment variable settings create the environment
76: any command in the
77: .Nm
78: is run in.
79: An environment variable setting is of the form:
80: .Pp
81: .Dl name = value
82: .Pp
83: The spaces around the equal sign
84: .Pq Ql =
1.2 christos 85: are optional, and any subsequent non-leading spaces in
86: .Ar value
1.1 christos 87: will be part of the value assigned to
1.2 christos 88: .Ar name .
89: The
90: .Ar value
1.6 christos 91: string may be placed in quotes
92: .Pq single or double , but matching
93: to preserve leading or trailing blanks.
1.2 christos 94: .Pp
1.6 christos 95: Lines in the system
96: .Nm
97: have six fixed fields plus a command, in the form:
98: .Bd -ragged -offset indent
99: .Ar minute
100: .Ar hour
101: .Ar day-of-month
102: .Ar month
103: .Ar day-of-week
104: .Ar user
105: .Ar command
106: .Ed
1.2 christos 107: .Pp
1.6 christos 108: While lines in a user
109: .Nm
110: have five fixed fields plus a command, in the form:
111: .Bd -ragged -offset indent
112: .Ar minute
113: .Ar hour
114: .Ar day-of-month
115: .Ar month
116: .Ar day-of-week
117: .Ar command
118: .Ed
1.2 christos 119: .Pp
1.6 christos 120: Fields are separated by blanks or tabs.
121: The command may be one or more fields long.
122: The allowed values for the fields are:
123: .Bl -column "day-of-month" "allowed values" -offset indent
124: .It Sy field Ta Sy allowed values
125: .It Ar minute Ta * or 0\(en59
126: .It Ar hour Ta * or 0\(en23
127: .It Ar day-of-month Ta * or 1\(en31
128: .It Ar month Ta * or 1\(en12 or a name (see below)
129: .It Ar day-of-week Ta * or 0\(en7 or a name (0 or 7 is Sunday)
130: .It Ar user Ta a valid username
131: .It Ar command Ta text
1.2 christos 132: .El
133: .Pp
1.6 christos 134: Lists are allowed.
135: A list is a set of numbers (or ranges) separated by commas.
136: For example,
137: .Dq 1,2,5,9
138: or
139: .Dq 0\(en4,8\(en12 .
1.2 christos 140: .Pp
141: Ranges of numbers are allowed.
142: Ranges are two numbers separated with a hyphen.
143: The specified range is inclusive.
144: For example,
1.6 christos 145: 8\(en11 for an
146: .Ar hour
147: entry specifies execution at hours 8, 9, 10 and 11.
1.2 christos 148: .Pp
149: Step values can be used in conjunction with ranges.
150: Following a range with
1.6 christos 151: .No / Ns Ar number
152: specifies skips of
153: .Ar number
154: through the range.
1.2 christos 155: For example,
1.6 christos 156: .Dq 0\(en23/2
157: can be used in the
158: .Ar hour
159: field to specify command execution every other hour.
160: Steps are also permitted after an asterisk, so to say
1.2 christos 161: .Dq every two hours ,
162: just use
163: .Dq */2 .
164: .Pp
1.6 christos 165: An asterisk
166: .Pq Ql *
167: is short form for a range of all allowed values.
168: .Pp
169: Names can be used in the
170: .Ar month
1.2 christos 171: and
1.6 christos 172: .Ar day-of-week
1.2 christos 173: fields.
1.6 christos 174: Use the first three letters of the particular
175: day or month (case doesn't matter).
1.2 christos 176: Ranges or lists of names are not allowed.
177: .Pp
178: The
1.6 christos 179: .Ar command
180: field (the rest of the line) is the command to be
181: run.
182: The entire command portion of the line, up to a newline or %
183: character, will be executed by
184: .Pa /bin/sh
185: or by the shell
186: specified in the
1.2 christos 187: .Ev SHELL
1.6 christos 188: variable of the
189: .Nm crontab .
1.2 christos 190: Percent signs
1.6 christos 191: .Pq Ql %
192: in the command, unless escaped with a backslash
193: .Pq Ql \e ,
194: will be changed into newline characters, and all data
195: after the first
196: .Ql %
197: will be sent to the command as standard input.
198: .Pp
199: Commands may be modified as follows:
200: .Bl -tag -width Ds
201: .It Fl n Ar command
202: No mail is sent after a successful run.
203: The execution output will only be mailed if the command exits with a non-zero
204: exit code.
205: The
206: .Fl n
207: option is an attempt to cure potentially copious volumes of mail coming from
208: .Xr cron 8 .
209: .It Fl q Ar command
210: Execution will not be logged.
211: .El
212: .Pp
213: Commands are executed by
214: .Xr cron 8
215: when the
216: .Ar minute ,
217: .Ar hour ,
218: and
219: .Ar month
220: fields match the current time,
221: .Em and
222: when at least one of the two day fields
223: .Po Ar day-of-month
224: or
225: .Ar day-of-week Pc ,
226: match the current time.
227: .Pp
228: Note: The day of a command's execution can be specified by two
229: fields \(em
230: .Ar day-of-month
231: and
232: .Ar day-of-week .
233: If both fields are restricted (i.e. aren't *),
234: the command will be run when
1.2 christos 235: .Em either
236: field matches the current time.
237: For example,
1.6 christos 238: .Pp
239: .Dl 30 4 1,15 * 5
240: .Pp
241: would cause a command to be run at 4:30 am on the 1st and 15th of each
242: month, plus every Friday.
1.2 christos 243: .Pp
244: Instead of the first five fields, one of eight special strings may appear:
1.6 christos 245: .Bl -column "@midnight" "meaning" -offset indent
1.2 christos 246: .It Sy string Ta Sy meaning
247: .It @reboot Ta Run once, at startup.
1.6 christos 248: .It @yearly Ta Run every January 1 (0 0 1 1 *).
249: .It @annually Ta The same as @yearly.
250: .It @monthly Ta Run the first day of every month (0 0 1 * *).
251: .It @weekly Ta Run every Sunday (0 0 * * 0).
252: .It @daily Ta Run every midnight (0 0 * * *).
253: .It @midnight Ta The same as @daily.
254: .It @hourly Ta Run every hour, on the hour (0 * * * *).
1.2 christos 255: .El
1.6 christos 256: .Sh ENVIRONMENT
257: .Bl -tag -width "CRON_WITHIN"
258: .It Ev CRON_TZ
259: The
260: .Ev CRON_TZ
261: variable can be set to an alternate time zone in order to affect when the job
262: is run.
263: Note that this only affects the scheduling of the job, not the time zone
1.7 ! wiz 264: that the job perceives when it is run.
1.6 christos 265: If
266: .Ev CRON_TZ
267: is defined but empty
268: .Pq Ev CRON_TZ Ns = Ns \&"" ,
269: jobs are scheduled with respect to the local time zone.
270: .It Ev CRON_WITHIN
271: The
272: .Ev CRON_WITHIN
273: variable should indicate the number of seconds within a job's
274: scheduled time that it should still be run.
275: On a heavily loaded system, or on a system that has just been
276: .Dq woken up ,
277: jobs will sometimes start later than originally intended, and by
278: skipping non-critical jobs because of delays, system load can be
279: lightened.
1.7 ! wiz 280: If
1.6 christos 281: .Ev CRON_WITHIN
282: is defined but empty
283: .Pq Ev CRON_WITHIN Ns = Ns \&"" ,
284: or set to some non-positive value (0, a negative number, or a
285: non-numeric string), it is treated as if it was unset.
286: .It Ev HOME
287: Set from the user's
288: .Pa /etc/passwd
289: entry.
290: May be overridden by settings in the
291: .Nm .
292: .It Ev LOGNAME
293: Set from the user's
294: .Pa /etc/passwd
295: entry.
296: May not be overridden by settings in the
297: .Nm .
298: .It Ev MAILTO
299: If
300: .Ev MAILTO
301: is defined and non-empty,
302: mail is sent to the user so named.
303: If
304: .Ev MAILTO
305: is defined but empty
306: .Pq Ev MAILTO = Qq ,
307: no mail will be sent.
308: Otherwise mail is sent to the owner of the
309: .Nm .
310: This is useful for pseudo-users that lack an alias
311: that would otherwise redirect the mail to a real person.
312: .It Ev SHELL
313: Set to
314: .Pa /bin/sh .
315: May be overridden by settings in the
316: .Nm .
317: .It Ev USER
318: Set from the user's
319: .Pa /etc/passwd
320: entry.
321: May not be overridden by settings in the
322: .Nm .
323: .El
324: .Sh FILES
325: .Bl -tag -width "/var/cron/tabs/<user>XXX" -compact
326: .It Pa /etc/crontab
327: System crontab.
328: .It Pa /var/cron/tabs/ Ns Aq Ar user
329: User crontab.
330: .El
331: .Sh EXAMPLES
1.2 christos 332: .Bd -literal
1.1 christos 333: # use /bin/sh to run commands, no matter what /etc/passwd says
334: SHELL=/bin/sh
335: # mail any output to `paul', no matter whose crontab this is
336: MAILTO=paul
337: #
338: # run five minutes after midnight, every day
1.6 christos 339: 5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
1.1 christos 340: # run at 2:15pm on the first of every month -- output mailed to paul
341: 15 14 1 * * $HOME/bin/monthly
342: # run at 10 pm on weekdays, annoy Joe
1.6 christos 343: 0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
1.1 christos 344: 23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
345: 5 4 * * sun echo "run at 5 after 4 every sunday"
1.2 christos 346: .Ed
347: .Sh SEE ALSO
348: .Xr crontab 1 ,
349: .Xr cron 8
350: .Sh STANDARDS
1.6 christos 351: The
352: .Nm
353: file format is compliant with the
354: .St -p1003.1-2008
355: specification.
356: The behaviours described below are all extensions to that standard:
357: .Bl -dash
358: .It
359: The
360: .Ar day-of-week
361: field may use 7 to represent Sunday.
362: .It
363: Ranges may include
364: .Dq steps .
365: .It
366: Months or days of the week can be specified by name.
367: .It
368: Mailing after a successful run can be suppressed with
369: .Fl n .
370: .It
371: Logging can be suppressed with
372: .Fl q .
373: .It
374: Environment variables can be set in a crontab.
375: .It
376: Command output can be mailed to a person other than the crontab
377: owner, or the feature can be turned off and no mail will be sent
378: at all.
379: .It
1.2 christos 380: All of the
1.6 christos 381: .Ql @
382: commands that can appear in place of the first five fields.
383: .El
1.2 christos 384: .Sh AUTHORS
1.6 christos 385: .Nm
386: was written by
387: .An Paul Vixie Aq Mt vixie@isc.org .
CVSweb <webmaster@jp.NetBSD.org>