X-Git-Url: https://git.netwichtig.de/gitweb/?a=blobdiff_plain;f=README.md;h=be882f1cefea6bf994960a85af3cf9d2275dce4f;hb=3027c580b50c028d5b3c3617704bf987a7897a83;hp=5831e81f4a6e569cc4951f589b7b84453faca3b6;hpb=a4aabb05a1673be34780f340428d6b11405cce08;p=user%2Fhenk%2Fcode%2Fsnooze.git

diff --git a/README.md b/README.md
index 5831e81..be882f1 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 ## snooze: run a command at a particular time
 
-`snooze` is a new tool for to wait until a particular time and then
-run a command.  Together with a service supervision system such as runit,
-this can be used to replace cron(8).
+`snooze` is a new tool for waiting until a particular time and then
+running a command.  Together with a service supervision system such as
+runit, this can be used to replace cron(8).
 
-`lr` has been tested on Linux 4.2.
+`snooze` has been tested on Linux 4.2.
 It will likely work on other Unix-like systems with C99.
 
 ## Benefits
@@ -23,6 +23,7 @@ Over cron:
   runs, even across reboots
 - randomized delays (some cron have that)
 - variable slack (no need for anacron)
+- ad-hoc usage possible, just run the program from command line
 
 Over runwhen:
 - less confusing usage (I hope)
@@ -31,6 +32,7 @@ Over runwhen:
 
 Over uschedule:
 - due to supervision, no centralized daemon required
+- filtering by ISO week and day of year
 
 ## Rosetta stone
 
@@ -43,8 +45,8 @@ Over uschedule:
 * run at 10 pm on weekdays:
   cron: `0 22 * * 1-5`
   snooze: `-w1-5 -H22`
-* run 23 minutes after midn, 2am, 4am ..., everyday:
-  cron: 23 0-23/2 * * *
+* run 23 minutes after midnight, 2am, 4am ..., everyday:
+  cron: `23 0-23/2 * * *`
   snooze: `-H/2 -M23`
 * run every second week:
   snooze: `-W/2`
@@ -61,6 +63,9 @@ Over uschedule:
 * `-R`: add between 0 and RANDDELAY seconds to the scheduled time.
 * `-s`: commands are executed even if they are SLACK (default: 60) seconds late.
 
+The durations RANDDELAY and SLACK and TIMEWAIT are parsed as seconds,
+unless a postfix of `m` for minutes, `h` for hours, or `d` for days is used.
+
 The remaining arguments are patterns for the time fields:
 
 * `-d`: day of month
@@ -99,14 +104,14 @@ of TIMEFILE plus TIMEWAIT seconds.
 
 When `-T` is *not* passed, snooze will start finding the first matching time
 starting from the mtime of TIMEFILE, and taking SLACK into account.
-(E.g. `-H0 -s$((24*60*60)) -t timefile` will start an instant
+(E.g. `-H0 -s 1d -t timefile` will start an instant
 execution when timefile has not been touched today, whereas without `-t`
 this would always wait until next midnight.)
 
 If TIMEFILE does not exist, it will be assumed outdated enough to
 ensure earliest execution.
 
-snooze does not update the timefiles, you need to do that!
+snooze does not update the timefiles, your job needs to do that!
 Only mtime is looked at, so touch(1) is good.
 
 ## Exact behavior
@@ -122,9 +127,10 @@ Only mtime is looked at, so touch(1) is good.
   execs the command.  You need to ensure (by setting up supervision)
   snooze runs again after that!
 * if we woke due to a SIGALRM, the command is executed immediately as well
+* if we notice time moved backwards, recompute the time until the event
 * if the event is in the future, recompute the time it takes, possibly
   considering shifting of the system time or timezone changes
-  (possibly only works on glibc)
+  (timezone reload only tested on glibc)
 * If no command was given, just return with status 0
 * and so on...
 
@@ -136,15 +142,15 @@ Run a job like cron, every day at 7am and 7pm:
 
 Run a job daily, never twice a day:
 
-	exec snooze -H0 -S $((24*60*60)) -t timefile \
+	exec snooze -H0 -s 1d -t timefile \
 		sh -c 'run-parts /etc/cron.daily; touch timefile'
 
 Use snooze inline, run a mirror script every hour at 30 minutes past,
 but ensure there are at least 20 minutes in between.
 
 	set -e
-	snooze -H'*' -M30 -t timefile -T $((20*60))
-	touch timefile  # remove this if instantly retrying on failure is ok
+	snooze -H'*' -M30 -t timefile -T 20m
+	touch timefile  # remove this if instantly retrying on failure were ok
 	mirrorallthethings
 	touch timefile
 
@@ -152,9 +158,19 @@ Use snooze inline, cron-style mail:
 
 	set -e
 	snooze ...
-        actualjob >output 2>&1 ||
+	actualjob >output 2>&1 ||
 		mail -s "$(hostname): snooze job failed with status $?" root <output
 
+Snooze for rate-limiting a general purpose runit service: don't
+restart faster than every two minutes. (Note that after a crash with a
+daemon runtime of more than two minutes, it will be restarted
+immediately):
+
+	set -e
+	snooze -H'*' -M'*' -S'*' -t timefile -T 2m
+	touch timefile
+	exec mydaemond
+
 ## Installation
 
 Use `make all` to build, `make install` to install relative to `PREFIX`
@@ -165,9 +181,7 @@ You can also just copy the binary into your `PATH`.
 
 snooze is in the public domain.
 
-To the extent possible under law,
-Christian Neukirchen <chneukirchen@gmail.com>
-has waived all copyright and related or
-neighboring rights to this work.
+To the extent possible under law, Leah Neukirchen <leah@vuxu.org>
+has waived all copyright and related or neighboring rights to this work.
 
 http://creativecommons.org/publicdomain/zero/1.0/