doc/cronexpr.texi

   1 @anchor{CronExpr}
   2 This is copy-pasted documentation from
   3 @code{github.com/gorhill/cronexpr} library used there.
   4
   5 @multitable @columnfractions .2 .1 .2 .5
   6 @headitem Field name @tab Mandatory? @tab Allowed values @tab Allowed special characters
   7
   8 @item Seconds @tab No @tab 0-59 @tab @verb{|* / , -|}
   9 @item Minutes @tab Yes @tab 0-59 @tab @verb{|* / , -|}
  10 @item Hours @tab Yes @tab 0-23 @tab @verb{|* / , -|}
  11 @item Day of month @tab Yes @tab 1-31 @tab @verb{|* / , - L W|}
  12 @item Month @tab Yes @tab 1-12 or JAN-DEC @tab @verb{|* / , -|}
  13 @item Day of week @tab Yes @tab 0-6 or SUN-SAT @tab @verb{|* / , - L #|}
  14 @item Year @tab No @tab 1970–2099 @tab @verb{|* / , -|}
  15
  16 @end multitable
  17
  18 @table @asis
  19
  20 @item Asterisk (@verb{|*|})
  21
  22 The asterisk indicates that the cron expression matches for all values
  23 of the field. E.g., using an asterisk in the 4th field (month) indicates
  24 every month.
  25
  26 @item Slash (@verb{|/|})
  27
  28 Slashes describe increments of ranges. For example @verb{|3-59/15|} in
  29 the minute field indicate the third minute of the hour and every 15
  30 minutes thereafter. The form @verb{|*/...|} is equivalent to the form
  31 "first-last/@dots{}", that is, an increment over the largest possible range
  32 of the field.
  33
  34 @item Comma (@verb{|,|})
  35
  36 Commas are used to separate items of a list. For example, using
  37 @verb{|MON,WED,FRI|} in the 5th field (day of week) means Mondays,
  38 Wednesdays and Fridays.
  39
  40 @item Hyphen (@verb{|-|})
  41
  42 Hyphens define ranges. For example, 2000-2010 indicates every year
  43 between 2000 and 2010 AD, inclusive.
  44
  45 @item L
  46
  47 @verb{|L|} stands for "last". When used in the day-of-week field, it
  48 allows you to specify constructs such as "the last Friday" (@verb{|5L|})
  49 of a given month. In the day-of-month field, it specifies the last day
  50 of the month.
  51
  52 @item W
  53
  54 The @verb{|W|} character is allowed for the day-of-month field. This
  55 character is used to specify the business day (Monday-Friday) nearest
  56 the given day. As an example, if you were to specify @verb{|15W|} as the
  57 value for the day-of-month field, the meaning is: "the nearest business
  58 day to the 15th of the month."
  59
  60 So, if the 15th is a Saturday, the trigger fires on Friday the 14th. If
  61 the 15th is a Sunday, the trigger fires on Monday the 16th. If the 15th
  62 is a Tuesday, then it fires on Tuesday the 15th. However if you specify
  63 @verb{|1W|} as the value for day-of-month, and the 1st is a Saturday,
  64 the trigger fires on Monday the 3rd, as it does not 'jump' over the
  65 boundary of a month's days.
  66
  67 The @verb{|W|} character can be specified only when the day-of-month is
  68 a single day, not a range or list of days.
  69
  70 The @verb{|W|} character can also be combined with @verb{|L|}, i.e.
  71 @verb{|LW|} to mean "the last business day of the month."
  72
  73 @item Hash (@verb{|#|})
  74
  75 @verb{|#|} is allowed for the day-of-week field, and must be followed by
  76 a number between one and five. It allows you to specify constructs such
  77 as "the second Friday" of a given month.
  78
  79 @end table
  80
  81 Predefined cron expressions:
  82
  83 @multitable @columnfractions .1 .75 .15
  84 @headitem Entry @tab Description @tab Equivalent to
  85 @item @verb{|@annually|} @tab
  86     Run once a year at midnight in the morning of January 1 @tab
  87     @verb{|0 0 0 1 1 * *|}
  88 @item @verb{|@yearly|} @tab
  89     Run once a year at midnight in the morning of January 1 @tab
  90     @verb{|0 0 0 1 1 * *|}
  91 @item @verb{|@monthly|} @tab
  92     Run once a month at midnight in the morning of the first of the month @tab
  93     @verb{|0 0 0 1 * * *|}
  94 @item @verb{|@weekly|} @tab
  95     Run once a week at midnight in the morning of Sunday @tab
  96     @verb{|0 0 0 * * 0 *|}
  97 @item @verb{|@daily|} @tab
  98     Run once a day at midnight @tab
  99     @verb{|0 0 0 * * * *|}
 100 @item @verb{|@hourly|} @tab
 101     Run once an hour at the beginning of the hour @tab
 102     @verb{|0 0 * * * * *|}
 103 @end multitable
 104
 105 @itemize
 106 @item
 107 If only six fields are present, a @verb{|0|} second field is prepended,
 108 that is, @verb{|* * * * * 2013|} internally become
 109 @verb{|0 * * * * * 2013|}.
 110 @item
 111 If only five fields are present, a @verb{|0|} second field is prepended
 112 and a wildcard year field is appended, that is, @verb{|* * * * Mon|}
 113 internally become @verb{|0 * * * * Mon *|}.
 114 @item
 115 Domain for day-of-week field is [0-7] instead of [0-6], 7 being Sunday
 116 (like 0). This to comply with @url{https://linux.die.net/man/5/crontab}.
 117 @end itemize