[BACK]Return to crontab.5 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / external / bsd / cron / dist

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>