apg/when

WHEN(1)

NAME
       when - repeatedly runs a command, then another when the first succeeds

SYNOPSIS
       when [-n <seconds>] [-t|-z] [-h] [-v] <conditional> <command>

DESCRIPTION
       when  runs conditional every N seconds awaiting for "success." Success
       is defined in one of two ways. In timebomb mode, -t, success is
       defined by whether or not the conditional is still running after N
       seconds (as specified by the -n flag). In zero mode, -z, success is
       achieved when conditional exits with a return value of 0.

       The -n flag allows the interval to be set (in seconds) between
       successive attempts at running the conditional

       when will run until interrupted, or command completes.


OPTIONS
       -h     Prints the help message and exits successfully.

       -n seconds
              Sets the interval for running the conditional to seconds
              In timebomb mode, the specified time in seconds will need to pass 
              before the conditional succeeds.

       -t     Sets the success mode to timebomb which succeeds after
              conditional has been running for at least seconds

       -v     Prints the version and exits successfully.

       -V     Turns on verbose output. Mostly useful for debugging purposes.

       -z     Sets the success mode to zero which succeeds after conditional
              returns 0 the first time. The conditional is guaranteed to be run
              at most 1 time every seconds

NOTE
       Note that both conditional and command are given to "sh -c" which
       means that you may need to use extra quoting to get the desired effect.

       Note that POSIX option processing is used (i.e., option processing
       stops at the first non-option argument).  This means that flags
       after conditional don't get interpreted by when itself.

EXIT STATUS
       when makes an effort to exit with the exit status returned by the
       conditional in timebomb mode. In zero mode the exit status should be,
       well, 0.

EXAMPLES
       TODO more examples needed

       Suppose you have a failing build, xmessage will alert you when
       it succeeds.

              when "make" "xmessage 'hurrah, build passed'"

       Or you want to say hello to john when he logs on

              when "w | grep john" "echo 'hello, john' | write john"

       Or maybe you have a daemon failing in a tight loop due to
       misconfiguration or lack of resources. One can run it with when and
       be alerted to when it becomes happy

              when -n 10 -t "<failing daemon>" "xmessage 'daemon running'"

SEE ALSO
       watch(1)

COPYRIGHT
       Copyright (C) 2013 Andrew Gwozdziewycz

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published
       by the Free Software Foundation, either version 3 of the License,
       or (at  your option) any later version.

       This  program  is  distributed  in  the  hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>

AUTHOR
       when was written by Andrew Gwozdziewycz <[email protected]> in 2013



                                                                                                         2013
                                                                                                         Dec
                                                                                                         10
                                                                                                         WHEN(1)