Add notes about unbuffering
[forkaftergrep.git] / README.md
CommitLineData
4f83e12d 1# `fag` (Fork After Grep)
2
3```
4fag(1) User Commands fag(1)
5
6NAME
e261f90d 7 fag - daemonize program after a pattern was matched (ForkAfterGrep)
4f83e12d 8
9SYNOPSIS
10 fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]
11
12DESCRIPTION
e261f90d 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
ddfcc26d 15 then returned on stdout.
4f83e12d 16
17OPTIONS
18 Behaviour Changing Options
19 -t SECONDS
e261f90d 20 Abort matching after SECONDS seconds and print PROGRAM's PID.
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
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
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
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.
55
e261f90d 56 -Z, -J Decompression switches for gzip(1) and bzip2(1). Not widely
4495ab75 57 supported; check your grep's capabilities.
58
4f83e12d 59EXIT STATUS
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
66BUGS
67 Known Bugs
e261f90d 68 logging stops when a timeout is reached.
69
c96f2b19 70 if grep gets killed (e.g. `killall grep'), fag should terminate.
4f83e12d 71
72 Reporting Bugs
e261f90d 73 Please report bugs and patches to the issue tracker at
4f83e12d 74 https://github.com/girst/forkaftergrep/.
75
76NOTES
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
85 found (or the timeout has been reached), this signal is passed to
c96f2b19 86 PROGRAM.
87
e261f90d 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
4495ab75 90 is supplied as an argument.
91
4f83e12d 92COPYRIGHT
e261f90d 93 Copyright 2017-2018 Tobias Girstmair. This is free software released
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
97AUTHOR
4495ab75 98 Tobias Girstmair (https://gir.st/)
4f83e12d 99
4495ab75 1001.2 16 February 2018 fag(1)
4f83e12d 101```
3c8bd809 102
e261f90d 103## Installation
104
105Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected.
106
3c8bd809 107## Notes
108
c96f2b19 109I'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.
110It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.
e261f90d 111
112## Examples
113
114Wait 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
120Start [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
127Some 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
131Stubborn 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
Imprint / Impressum