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        fag  works best when PROGRAM's output is line-buffered.  stdbuf(1) from
  81        the GNU coreutils can adjust buffering options. If a program  is  still
  82        too clever, script(1) creates a pty to wrap around a program.
  83
  84        Since  1.2,  if  fag  gets  interrupted or terminated before a match is
  85        found (or the timeout has been  reached),  this  signal  is  passed  to
  86        PROGRAM.
  87
  88        In  version  1.2  the command line switch -e was renamed to -r to avoid
  89        overloading grep's own switches. An error will be thrown when -e or  -f
  90        is supplied as an argument.
  91
  92 COPYRIGHT
  93        Copyright  2017-2018  Tobias  Girstmair. This is free software released
  94        under the terms of the  GNU  General  Public  License  Version  3;  see
  95        https://www.gnu.org/licenses/gpl-3.0.html for conditions.
  96
  97 AUTHOR
  98        Tobias Girstmair (https://gir.st/)
  99
 100 1.2                            16 February 2018                         fag(1)
 101 ```
 102
 103 ## Installation
 104
 105 Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected.
 106
 107 ## Notes
 108
 109 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.
 110 It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.
 111
 112 ## Examples
 113
 114 Wait for `tzap-t2` (DVB-T2 version of `tzap`) to tune into a channel or abort after 1 minute:
 115
 116     fag -t 60 -k FE_HAS_LOCK ./tzap-t2 -a0 -f1 -V -c channels.vdr "ORF1;ORF"
 117
 118 ---
 119
 120 Start [mopidy](https://www.mopidy.com/) and wait for the MPD service to have started up:
 121
 122     fag -rV -L /tmp/mopidy.log "MPD server running at" mopidy
 123
 124
 125 ### On Buffering
 126
 127 Some programs will detect that their output is not going to a terminal and switch to using a large buffer size. Most of the time it is sufficient to wrap such a program with `stdbuf`(1) like so:
 128
 129     fag PATTTERN stdbuf -oL PROGRAM
 130
 131 Stubborn programs can also be coaxed into line-buffering by executing them in a pty, for example with `script`(1): [via](https://stackoverflow.com/a/55655115)
 132
 133     script -qfc "$(printf "%q " "$@")" /dev/null