README.md

   1 # `fag` (Fork After Grep)
   2
   3 ```
   4 fag(1)                           User Commands                          fag(1)
   5
   6 NAME
   7        fag  - daemonize program after a regular expression pattern was matched
   8        (ForkAfterGrep)
   9
  10 SYNOPSIS
  11        fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]
  12
  13 DESCRIPTION
  14        fag uses  grep  to  search  the  output  of  PROGRAM  for  the  regular
  15        expression  PATTERN and daemonizes it when a match is found. The PID is
  16        then returned on stdout.
  17
  18 OPTIONS
  19    Behaviour Changing Options
  20        -t SECONDS
  21               Set a timeout of SECONDS seconds.
  22
  23        -k [SIGNAL]
  24               If given, send a signal to PROGRAM.  SIGNAL defaults to  SIGTERM
  25               (15).  Right now, only decimal notation is implemented.
  26
  27        -e     Search PATTERN on stderr instead of stdout.
  28
  29        -V     Be  verbose;  print program's stdout (or stderr if -e is set) to
  30               stderr.
  31
  32    Generic Program Information
  33        -h     Output a short usage message and exit.
  34
  35        -v     Display version and copyright information and exit.
  36
  37 EXIT STATUS
  38        If PATTERN was found, 0 is returned. Otherwise, the exit status follows
  39        the  BSD  guideline  outlined  in  #include  <sysexits.h>  if the error
  40        occured from within fag or in case the chid process exits  prematurely,
  41        its exit code is inherited. Notably, 69 is returned when the timeout is
  42        reached.
  43
  44 BUGS
  45    Known Bugs
  46        if grep gets killed (e.g. `killall grep'), fag should terminate.
  47
  48    Reporting Bugs
  49        Please  report   bugs   and   patches   to   the   issue   tracker   at
  50        https://github.com/girst/forkaftergrep/.
  51
  52 NOTES
  53        SIGNAL needs to be given as an integer. implementing mnemonics is dirty
  54        and not very portable; maybe support in the future.
  55
  56        Since 1.1, if fag gets interrupted or terminated, SIGTERM  is  sent  to
  57        PROGRAM.
  58
  59 COPYRIGHT
  60        Copyright   2017   Tobias   Girstmair.   This  is  free  software;  see
  61        https://www.gnu.org/licenses/gpl-3.0.html for conditions.
  62
  63 AUTHOR
  64        Tobias Girstmair (https://gir.st)
  65
  66 1.1                             13 October 2017                         fag(1)
  67 ```
  68
  69 ## Notes
  70
  71 I've written this program for the [`tzap`/`szap`](https://linuxtv.org/wiki/index.php/Zap) utilities. They take a few seconds until the TV card/stick is tuned, and won't fork off when they are ready (If you terminate them, the tuning will end). Instead of waiting a few seconds, and hoping for the best, this does the exactly right thing.
  72 It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.