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 (1..366)
  76 .It Fl W
  77 ISO week of year (1..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 .Pp
 120 If
 121 .Nm
 122 receives a
 123 .Dv SIGALRM
 124 signal, the command is immediately executed.
 125 .Sh TIMEFILES
 126 Optionally, you can keep track of runs in time files, using
 127 .Fl t :
 128 .Pp
 129 When
 130 .Fl T
 131 is passed, execution will not start earlier than the mtime
 132 of
 133 .Ar timefile
 134 plus
 135 .Ar timewait
 136 seconds.
 137 .Pp
 138 When
 139 .Fl T
 140 is
 141 .Em not
 142 passed,
 143 .Nm
 144 will start finding the first matching time
 145 starting from the mtime of
 146 .Ar timefile ,
 147 and taking
 148 .Ar slack
 149 into account.
 150 (E.g.\&
 151 .Cm -H0 -s 1d -t timefile
 152 will start an instant
 153 execution when timefile has not been touched today, whereas without
 154 .Fl t
 155 this would always wait until next midnight.)
 156 .Pp
 157 If
 158 .Ar timefile
 159 does not exist, it will be assumed outdated enough to
 160 ensure earliest execution.
 161 .Pp
 162 .Nm
 163 does not update the timefiles, your job needs to do that!
 164 Only mtime is looked at, so
 165 .Xr touch 1
 166 is good.
 167 .Sh EXIT STATUS
 168 .Ex -std
 169 .Pp
 170 The
 171 .Ar command
 172 is run using exec, so its exit status gets propagated to the parent.
 173 .Pp
 174 If no command was given,
 175 .Nm
 176 just returns with status 0.
 177 .Sh SEE ALSO
 178 .Xr runwhen 1 ,
 179 .Xr sleep 1 ,
 180 .Xr uschedule 1 ,
 181 .Xr cron 8
 182 .Sh AUTHORS
 183 .An Leah Neukirchen Aq Mt leah@vuxu.org
 184 .Sh LICENSE
 185 .Nm
 186 is in the public domain.
 187 .Pp
 188 To the extent possible under law,
 189 the creator of this work
 190 has waived all copyright and related or
 191 neighboring rights to this work.
 192 .Pp
 193 .Lk http://creativecommons.org/publicdomain/zero/1.0/