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