[forkaftergrep.git] / README.md

# `fag` (Fork After Grep)

```
fag(1)                           User Commands                          fag(1)

NAME
       fag - daemonize program after a pattern was matched (ForkAfterGrep)

SYNOPSIS
       fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]

DESCRIPTION
       fag  uses  grep  to  search  the  output  of  PROGRAM  for  the regular
       expression PATTERN and daemonizes it when a match is found. The PID  is
       then returned on stdout.

OPTIONS
   Behaviour Changing Options
       -t SECONDS
              Abort  matching  after  SECONDS seconds and print PROGRAM's PID.
              Unless -k is given, PROGRAM is kept running and daemonized.

       -k[SIGNAL]
              If the timeout (-t) has been reached, send a signal to  PROGRAM.
              SIGNAL  defaults  to SIGTERM (15).  The signal may only be given
              as a number.

       -r     Search for PATTERN on stderr instead of stdout.

       -l FILE
              Log PROGRAM's stdout to FILE.  The file will be opened in append
              mode.  If  the file does not exist, it will be created with file
              mode 0600.

       -L FILE
              Same as -l but logs PROGRAM's stderr.

       -V     Be verbose; print PROGRAM's monitored stream to stderr.

   Generic Program Information
       -h     Output a short usage message and exit.

       -v     Display version and copyright information and exit.

   Supported grep Options
       -E, -F, -G, -P
              Matcher selection switches  for  extended  regular  expressions,
              fixed  strings,  basic  regular  expressions  (default) or Perl-
              compatible regular expressions. At  most  one  of  them  may  be
              supplied.

       -i, -w, -x, -U
              Matching  control  switches  for ignore case distinctions, whole
              words only, whole lines only and treat as binary.

       -Z, -J Decompression switches for gzip(1)  and  bzip2(1).   Not  widely
              supported; check your grep's capabilities.

EXIT STATUS
       If PATTERN was found, 0 is returned. Otherwise, the exit status follows
       the BSD guideline  outlined  in  #include  <sysexits.h>  if  the  error
       occurred   from   within  fag  or  in  case  the  child  process  exits
       prematurely, its exit code is inherited. Notably, 69 is  returned  when
       the timeout is reached.

BUGS
   Known Bugs
       logging stops when a timeout is reached.

       if grep gets killed (e.g. `killall grep'), fag should terminate.

   Reporting Bugs
       Please   report   bugs   and   patches   to   the   issue   tracker  at
       https://github.com/girst/forkaftergrep/.

NOTES
       Usually, fag uses the grep supplied in the path. This behaviour can  be
       overridden with the environment variable GREP_OVERRIDE.

       fag  works best when PROGRAM's output is line-buffered.  stdbuf(1) from
       the GNU coreutils can adjust buffering options. If a program  is  still
       too clever, script(1) creates a pty to wrap around a program.

       Since  1.2,  if  fag  gets  interrupted or terminated before a match is
       found (or the timeout has been  reached),  this  signal  is  passed  to
       PROGRAM.

       In  version  1.2  the command line switch -e was renamed to -r to avoid
       overloading grep's own switches. An error will be thrown when -e or  -f
       is supplied as an argument.

COPYRIGHT
       Copyright  2017-2018  Tobias  Girstmair. This is free software released
       under the terms of the  GNU  General  Public  License  Version  3;  see
       https://www.gnu.org/licenses/gpl-3.0.html for conditions.

AUTHOR
       Tobias Girstmair (https://gir.st/)

1.2                            16 February 2018                         fag(1)
```

## Installation

Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected.

## Notes

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.    
It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.

## Examples

Wait for `tzap-t2` (DVB-T2 version of `tzap`) to tune into a channel or abort after 1 minute:

    fag -t 60 -k FE_HAS_LOCK ./tzap-t2 -a0 -f1 -V -c channels.vdr "ORF1;ORF"

---

Start [mopidy](https://www.mopidy.com/) and wait for the MPD service to have started up:

    fag -rV -L /tmp/mopidy.log "MPD server running at" mopidy


### On Buffering

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:

    fag PATTTERN stdbuf -oL PROGRAM

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)

    script -qfc "$(printf "%q " "$@")" /dev/null
Commit	Line	Data
4f83e12d	1	# `fag` (Fork After Grep)
	2
	3	```
	4	fag(1) User Commands fag(1)
	5
	6	NAME
e261f90d	7	fag - daemonize program after a pattern was matched (ForkAfterGrep)
4f83e12d	8
	9	SYNOPSIS
	10	fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]
	11
	12	DESCRIPTION
e261f90d	13	fag uses grep to search the output of PROGRAM for the regular
e261f90d	14	expression PATTERN and daemonizes it when a match is found. The PID is
ddfcc26d	15	then returned on stdout.
4f83e12d	16
	17	OPTIONS
	18	Behaviour Changing Options
	19	-t SECONDS
e261f90d	20	Abort matching after SECONDS seconds and print PROGRAM's PID.
e261f90d	21	Unless -k is given, PROGRAM is kept running and daemonized.
4f83e12d	22
4495ab75	23	-k[SIGNAL]
e261f90d	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.
4f83e12d	27
e261f90d	28	-r Search for PATTERN on stderr instead of stdout.
4f83e12d	29
4495ab75	30	-l FILE
4495ab75	31	Log PROGRAM's stdout to FILE. The file will be opened in append
e261f90d	32	mode. If the file does not exist, it will be created with file
e261f90d	33	mode 0600.
4495ab75	34
	35	-L FILE
	36	Same as -l but logs PROGRAM's stderr.
	37
e261f90d	38	-V Be verbose; print PROGRAM's monitored stream to stderr.
ddfcc26d	39
4f83e12d	40	Generic Program Information
	41	-h Output a short usage message and exit.
	42
	43	-v Display version and copyright information and exit.
	44
4495ab75	45	Supported grep Options
4495ab75	46	-E, -F, -G, -P
e261f90d	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
4495ab75	50	supplied.
	51
	52	-i, -w, -x, -U
e261f90d	53	Matching control switches for ignore case distinctions, whole
4495ab75	54	words only, whole lines only and treat as binary.
4495ab75	55
e261f90d	56	-Z, -J Decompression switches for gzip(1) and bzip2(1). Not widely
4495ab75	57	supported; check your grep's capabilities.
4495ab75	58
4f83e12d	59	EXIT STATUS
4f83e12d	60	If PATTERN was found, 0 is returned. Otherwise, the exit status follows
e261f90d	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.
4f83e12d	65
	66	BUGS
	67	Known Bugs
e261f90d	68	logging stops when a timeout is reached.
e261f90d	69
c96f2b19	70	if grep gets killed (e.g. `killall grep'), fag should terminate.
4f83e12d	71
4f83e12d	72	Reporting Bugs
e261f90d	73	Please report bugs and patches to the issue tracker at
4f83e12d	74	https://github.com/girst/forkaftergrep/.
	75
	76	NOTES
e261f90d	77	Usually, fag uses the grep supplied in the path. This behaviour can be
4495ab75	78	overridden with the environment variable GREP_OVERRIDE.
4f83e12d	79
e49d9f33	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
e261f90d	84	Since 1.2, if fag gets interrupted or terminated before a match is
e261f90d	85	found (or the timeout has been reached), this signal is passed to
c96f2b19	86	PROGRAM.
c96f2b19	87
e261f90d	88	In version 1.2 the command line switch -e was renamed to -r to avoid
e261f90d	89	overloading grep's own switches. An error will be thrown when -e or -f
4495ab75	90	is supplied as an argument.
4495ab75	91
4f83e12d	92	COPYRIGHT
e261f90d	93	Copyright 2017-2018 Tobias Girstmair. This is free software released
e261f90d	94	under the terms of the GNU General Public License Version 3; see
4f83e12d	95	https://www.gnu.org/licenses/gpl-3.0.html for conditions.
	96
	97	AUTHOR
4495ab75	98	Tobias Girstmair (https://gir.st/)
4f83e12d	99
4495ab75	100	1.2 16 February 2018 fag(1)
4f83e12d	101	```
3c8bd809	102
e261f90d	103	## Installation
	104
	105	Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected.
	106
3c8bd809	107	## Notes
3c8bd809	108
c96f2b19	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.
c96f2b19	110	It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.
e261f90d	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
e49d9f33	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