fix verbose output when no command is passed

[user/henk/code/snooze.git] / README.md

diff --git a/README.md b/README.md
index 5831e81f4a6e569cc4951f589b7b84453faca3b6..600bd08c16767eba16d7adee291875accfbce44e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 ## snooze: run a command at a particular time
 
 ## 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
 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)
   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)
 
 Over runwhen:
 - less confusing usage (I hope)


@@ -31,6 +32,18 @@ Over runwhen:
 
 Over uschedule:
 - due to supervision, no centralized daemon required
 
 Over uschedule:
 - due to supervision, no centralized daemon required

+- filtering by ISO week and day of year
+
+Over systemd timers:
+- mnemonic syntax
+- less complexity for jobs, no need for a `<job>.timer` file distinct
+  from the `<job>.service` file,
+- can use a file timestamp to ensure minimum waiting time between two
+  runs, even across reboots
+- very robust with respect to external time changes
+- randomized delays
+- variable slack
+- ad-hoc usage possible, just run the program from command line

 
 ## Rosetta stone
 
 
 ## Rosetta stone
 


@@ -39,12 +52,12 @@ Over uschedule:
   snooze: `-M5`
 * run at 2:15pm on the first of every month:
   cron: `15 14 1 * *`
   snooze: `-M5`
 * run at 2:15pm on the first of every month:
   cron: `15 14 1 * *`

-  snooze: `-d1 -H2 -M15`
+  snooze: `-d1 -H14 -M15`

 * run at 10 pm on weekdays:
   cron: `0 22 * * 1-5`
   snooze: `-w1-5 -H22`
 * 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`
   snooze: `-H/2 -M23`
 * run every second week:
   snooze: `-W/2`


@@ -58,9 +71,13 @@ Over uschedule:
 * `-n`: dry-run, print the next 5 times the command would run.
 * `-v`: verbose, print scheduled (and rescheduled) times.
 * `-t`, `-T`: see below timefiles
 * `-n`: dry-run, print the next 5 times the command would run.
 * `-v`: verbose, print scheduled (and rescheduled) times.
 * `-t`, `-T`: see below timefiles

-* `-R`: add between 0 and RANDDELAY seconds to the scheduled time.
+* `-R`: add between 0 and RANDDELAY seconds to the start of the scheduled time.
+* `-J`: add between 0 and JITTER seconds to scheduled execution time.

 * `-s`: commands are executed even if they are SLACK (default: 60) seconds late.
 
 * `-s`: commands are executed even if they are SLACK (default: 60) seconds late.
 

+The durations RANDDELAY and JITTER 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
 The remaining arguments are patterns for the time fields:
 
 * `-d`: day of month


@@ -99,14 +116,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.
 
 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.
 
 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
 Only mtime is looked at, so touch(1) is good.
 
 ## Exact behavior


@@ -122,9 +139,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
   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
 * 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...
 
 * If no command was given, just return with status 0
 * and so on...
 


@@ -136,15 +154,15 @@ Run a job like cron, every day at 7am and 7pm:
 
 Run a job daily, never twice a day:
 
 
 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
                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
 
        mirrorallthethings
        touch timefile
 


@@ -152,9 +170,19 @@ Use snooze inline, cron-style mail:
 
        set -e
        snooze ...
 
        set -e
        snooze ...

-        actualjob >output 2>&1 ||
+       actualjob >output 2>&1 ||

                mail -s "$(hostname): snooze job failed with status $?" root <output
 
                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`
 ## Installation
 
 Use `make all` to build, `make install` to install relative to `PREFIX`


@@ -165,9 +193,7 @@ You can also just copy the binary into your `PATH`.
 
 snooze is in the public domain.
 
 
 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/
 
 http://creativecommons.org/publicdomain/zero/1.0/