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        -r     Search PATTERN on stderr instead of stdout.
  28
  29        -l FILE
  30               Log PROGRAM's stdout to FILE.  The file will be opened in append
  31               mode and created with permissions 0600 if it doesn't exist.
  32
  33        -L FILE
  34               Same as -l but logs PROGRAM's stderr.
  35
  36        -V     Be verbose; print program's stdout (or stderr if -r is  set)  to
  37               stderr.
  38
  39    Generic Program Information
  40        -h     Output a short usage message and exit.
  41
  42        -v     Display version and copyright information and exit.
  43
  44    Supported grep Options
  45        -E, -F, -G, -P
  46               Matcher  selection  switches  for  extended regular expressions,
  47               fixed strings, basic  regular  expressions  (default)  or  Perl-
  48               compatible  regular  expressions.  At  most  one  of them may be
  49               supplied.
  50
  51        -i, -w, -x, -U
  52               Matching control switches for ignore  case  distinctions,  whole
  53               words only, whole lines only and treat as binary.
  54
  55        -Z, -J Decompression  switches  for  gzip(1)  and bzip2(1).  Not widely
  56               supported; check your grep's capabilities.
  57
  58 EXIT STATUS
  59        If PATTERN was found, 0 is returned. Otherwise, the exit status follows
  60        the  BSD  guideline  outlined  in  #include  <sysexits.h>  if the error
  61        occured from within fag or in case the chid process exits  prematurely,
  62        its exit code is inherited. Notably, 69 is returned when the timeout is
  63        reached.
  64
  65 BUGS
  66    Known Bugs
  67        if grep gets killed (e.g. `killall grep'), fag should terminate.
  68
  69    Reporting Bugs
  70        Please  report   bugs   and   patches   to   the   issue   tracker   at
  71        https://github.com/girst/forkaftergrep/.
  72
  73 NOTES
  74        Usually,  fag uses the grep supplied in the path. This behaviour can be
  75        overridden with the environment variable GREP_OVERRIDE.
  76
  77        Since 1.2, if fag gets interrupted or  terminated  before  a  match  is
  78        found  (or  the  timeout  has  been  reached), this signal is passed to
  79        PROGRAM.
  80
  81        In version 1.2 the command line switch -e was renamed to  -r  to  avoid
  82        overloading  grep's own switches. An error will be thrown when -e or -f
  83        is supplied as an argument.
  84
  85 COPYRIGHT
  86        Copyright 2017-2018 Tobias Girstmair. This is  free  software  released
  87        under  the  terms  of  the  GNU  General  Public License Version 3; see
  88        https://www.gnu.org/licenses/gpl-3.0.html for conditions.
  89
  90 AUTHOR
  91        Tobias Girstmair (https://gir.st/)
  92
  93 1.2                            16 February 2018                         fag(1)
  94 ```
  95
  96 ## Notes
  97
  98 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.
  99 It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.