snooze.1

   1 .Dd January 4, 2016
   2 .Dt SNOOZE 1
   3 .Os
   4 .Sh NAME
   5 .Nm snooze
   6 .Nd run a command at a particular time
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Fl nv
  10 .Op Fl t Ar timefile
  11 .Op Fl T Ar timewait
  12 .Op Fl R Ar randdelay
  13 .Op Fl s Ar slack
  14 .Op Fl d Ar day
  15 .Op Fl m Ar mon
  16 .Op Fl w Ar wday
  17 .Op Fl D Ar yday
  18 .Op Fl W Ar yweek
  19 .Op Fl H Ar hour
  20 .Op Fl M Ar min
  21 .Op Fl S Ar sec
  22 .Ar command\ ...
  23 .Sh DESCRIPTION
  24 .Nm
  25 waits until a particular time and then runs a command.
  26 Together with a service supervision system such as
  27 .Xr runsv 8 ,
  28 this can be used to replace
  29 .Xr cron 8 .
  30 .Pp
  31 The options are as follows:
  32 .Bl -tag -width Ds
  33 .It Fl n
  34 Dry run: print the next 5 times the command would run and exit.
  35 .It Fl v
  36 Verbose: print scheduled (and rescheduled) times.
  37 .It Fl t , Fl T
  38 See below,
  39 .Sx TIMEFILES .
  40 .It Fl R
  41 Wait randomly up to
  42 .Ar randdelay
  43 seconds later than the scheduled time.
  44 .It Fl s
  45 Commands are executed even if they are
  46 .Ar slack
  47 (default: 60) seconds late.
  48 .El
  49 .Pp
  50 The durations
  51 .Ar randdelay
  52 and
  53 .Ar slack
  54 and
  55 .Ar timewait
  56 are parsed as seconds,
  57 unless a postfix of
  58 .Cm m
  59 for minutes,
  60 .Cm h
  61 for hours, or
  62 .Cm d
  63 for days is used.
  64 .Pp
  65 The remaining arguments are patterns for the time fields:
  66 .Pp
  67 .Bl -tag -compact -width xxxxxxxxxx
  68 .It Fl d
  69 day of month
  70 .It Fl n
  71 month
  72 .It Fl w
  73 weekday (0-7, sunday is 0 and 7)
  74 .It Fl D
  75 day of year
  76 .It Fl W
  77 ISO week of year (0..53)
  78 .It Fl H
  79 hour
  80 .It Fl M
  81 minute
  82 .It Fl S
  83 second
  84 .El
  85 .Pp
  86 The following syntax is used for these options:
  87 .Bl -tag -width xxxxxxxxxx
  88 .It Cm -d 3
  89 exact match: run on the 3rd
  90 .It Cm -d 3,10,27
  91 alternation: run on 3rd, 10th, 27th
  92 .It Cm -d 1-5
  93 range: run on 1st, 2nd, 3rd, 4th, 5th
  94 .It Cm -d *
  95 star: run every day
  96 .It Cm -d /5
  97 repetition: run on 5th, 10th, 15th, 20th, 25th, 30th day
  98 .It Cm -d 2/5
  99 shifted repetition: run on 7th, 12th, 17th, 22nd, 27th day
 100 .El
 101 .Pp
 102 and combinations of those, e.g.\&
 103 .Cm -d 1-10,15/5,28 .
 104 .Pp
 105 The defaults are
 106 .Cm -d* -m* -w* -D* -W* -H0 -M0 -S0 ,
 107 that is, every midnight.
 108 .Pp
 109 Note that
 110 .Em all
 111 patterns need to match
 112 (contrary to
 113 .Xr cron 8
 114 where either day of month
 115 .Em or
 116 day of week matches), so
 117 .Cm -w5 -d13
 118 only runs on Friday the 13th.
 119 .Sh TIMEFILES
 120 Optionally, you can keep track of runs in time files, using
 121 .Fl t
 122 and optionally
 123 .Fl T :
 124 .Pp
 125 When
 126 .Fl T
 127 is passed, execution will not start earlier than the mtime
 128 of
 129 .Ar timefile
 130 plus
 131 .Ar timewait
 132 seconds.
 133 .Pp
 134 When
 135 .Fl T
 136 is
 137 .Em not
 138 passed,
 139 .Nm
 140 will start finding the first matching time
 141 starting from the mtime of
 142 .Ar timefile ,
 143 and taking
 144 .Ar slack
 145 into account.
 146 (E.g.\&
 147 .Cm -H0 -s 1d -t timefile
 148 will start an instant
 149 execution when timefile has not been touched today, whereas without
 150 .Fl t
 151 this would always wait until next midnight.)
 152 .Pp
 153 If
 154 .Ar timefile
 155 does not exist, it will be assumed outdated enough to
 156 ensure earliest execution.
 157 .Pp
 158 .Nm
 159 does not update the timefiles, your job needs to do that!
 160 Only mtime is looked at, so
 161 .Xr touch 1
 162 is good.
 163 .Sh EXIT STATUS
 164 .Ex -std
 165 .Pp
 166 The
 167 .Ar command
 168 is run using exec, so its exit status gets propagated to the parent.
 169 .Pp
 170 If no command was given,
 171 .Nm
 172 just returns with status 0.
 173 .Sh SEE ALSO
 174 .Xr sleep 1 ,
 175 .Xr cron 8 ,
 176 runwhen,
 177 uschedule
 178 .Sh AUTHORS
 179 .An Christian Neukirchen Aq Mt chneukirchen@gmail.com
 180 .Sh LICENSE
 181 .Nm
 182 is in the public domain.
 183 .Pp
 184 To the extent possible under law,
 185 the creator of this work
 186 has waived all copyright and related or
 187 neighboring rights to this work.
 188 .Pp
 189 .Lk http://creativecommons.org/publicdomain/zero/1.0/