finish -l and -L, update man page
[forkaftergrep.git] / 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 -e Search PATTERN on stderr instead of stdout.
28
29 -V Be verbose; print program's stdout (or stderr if -e is set) to
30 stderr.
31
32 Generic Program Information
33 -h Output a short usage message and exit.
34
35 -v Display version and copyright information and exit.
36
37 EXIT STATUS
38 If PATTERN was found, 0 is returned. Otherwise, the exit status follows
39 the BSD guideline outlined in #include <sysexits.h> if the error
40 occured from within fag or in case the chid process exits prematurely,
41 its exit code is inherited. Notably, 69 is returned when the timeout is
42 reached.
43
44 BUGS
45 Known Bugs
46 if grep gets killed (e.g. `killall grep'), fag should terminate.
47
48 Reporting Bugs
49 Please report bugs and patches to the issue tracker at
50 https://github.com/girst/forkaftergrep/.
51
52 NOTES
53 SIGNAL needs to be given as an integer. implementing mnemonics is dirty
54 and not very portable; maybe support in the future.
55
56 Since 1.1, if fag gets interrupted or terminated, SIGTERM is sent to
57 PROGRAM.
58
59 COPYRIGHT
60 Copyright 2017 Tobias Girstmair. This is free software; see
61 https://www.gnu.org/licenses/gpl-3.0.html for conditions.
62
63 AUTHOR
64 Tobias Girstmair (https://gir.st)
65
66 1.1 13 October 2017 fag(1)
67 ```
68
69 ## Notes
70
71 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.
72 It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it.
Imprint / Impressum