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 pattern was matched (ForkAfterGrep)
   8
   9 SYNOPSIS
  10        fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]
  11
  12 DESCRIPTION
  13        fag  uses  grep  to  search  the  output  of  PROGRAM  for  the regular
  14        expression PATTERN and daemonizes it when a match is found. The PID  is
  15        then returned on stdout.
  16
  17 OPTIONS
  18    Behaviour Changing Options
  19        -t SECONDS
  20               Abort  matching  after  SECONDS seconds and print PROGRAM's PID.
  21               Unless -k is given, PROGRAM is kept running and daemonized.
  22
  23        -k[SIGNAL]
  24               If the timeout (-t) has been reached, send a signal to  PROGRAM.
  25               SIGNAL  defaults  to SIGTERM (15).  The signal may only be given
  26               as a number.
  27
  28        -r     Search for PATTERN on stderr instead of stdout.
  29
  30        -l FILE
  31               Log PROGRAM's stdout to FILE.  The file will be opened in append
  32               mode.  If  the file does not exist, it will be created with file
  33               mode 0600.
  34
  35        -L FILE
  36               Same as -l but logs PROGRAM's stderr.
  37
  38        -V     Be verbose; print PROGRAM's monitored stream to stderr.
  39
  40    Generic Program Information
  41        -h     Output a short usage message and exit.
  42
  43        -v     Display version and copyright information and exit.
  44
  45    Supported grep Options
  46        -E, -F, -G, -P
  47               Matcher selection switches  for  extended  regular  expressions,
  48               fixed  strings,  basic  regular  expressions  (default) or Perl-
  49               compatible regular expressions. At  most  one  of  them  may  be
  50               supplied.
  51
  52        -i, -w, -x, -U
  53               Matching  control  switches  for ignore case distinctions, whole
  54               words only, whole lines only and treat as binary.
  55
  56        -Z, -J Decompression switches for gzip(1)  and  bzip2(1).   Not  widely
  57               supported; check your grep's capabilities.
  58
  59 EXIT STATUS
  60        If PATTERN was found, 0 is returned. Otherwise, the exit status follows
  61        the BSD guideline  outlined  in  #include  <sysexits.h>  if  the  error
  62        occurred   from   within  fag  or  in  case  the  child  process  exits
  63        prematurely, its exit code is inherited. Notably, 69 is  returned  when
  64        the timeout is reached.
  65
  66 BUGS
  67    Known Bugs
  68        logging stops when a timeout is reached.
  69
  70        if grep gets killed (e.g. `killall grep'), fag should terminate.
  71
  72    Reporting Bugs
  73        Please   report   bugs   and   patches   to   the   issue   tracker  at
  74        https://github.com/girst/forkaftergrep/.
  75
  76 NOTES
  77        Usually, fag uses the grep supplied in the path. This behaviour can  be
  78        overridden with the environment variable GREP_OVERRIDE.
  79
  80        Since  1.2,  if  fag  gets  interrupted or terminated before a match is
  81        found (or the timeout has been  reached),  this  signal  is  passed  to
  82        PROGRAM.
  83
  84        In  version  1.2  the command line switch -e was renamed to -r to avoid
  85        overloading grep's own switches. An error will be thrown when -e or  -f
  86        is supplied as an argument.
  87
  88 COPYRIGHT
  89        Copyright  2017-2018  Tobias  Girstmair. This is free software released
  90        under the terms of the  GNU  General  Public  License  Version  3;  see
  91        https://www.gnu.org/licenses/gpl-3.0.html for conditions.
  92
  93 AUTHOR
  94        Tobias Girstmair (https://gir.st/)
  95
  96 1.2                            16 February 2018                         fag(1)
  97 ```
  98
  99 ## Installation
 100
 101 Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected.
 102
 103 ## Notes
 104
 105 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.
 106 It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.
 107
 108 ## Examples
 109
 110 Wait for `tzap-t2` (DVB-T2 version of `tzap`) to tune into a channel or abort after 1 minute:
 111
 112     fag -t 60 -k FE_HAS_LOCK ./tzap-t2 -a0 -f1 -V -c channels.vdr "ORF1;ORF"
 113
 114 ---
 115
 116 Start [mopidy](https://www.mopidy.com/) and wait for the MPD service to have started up:
 117
 118     fag -rV -L /tmp/mopidy.log "MPD server running at" mopidy