doc/cronexpr.texi

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