]>
Commit | Line | Data |
---|---|---|
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 |