finish -l and -L, update man page
[forkaftergrep.git] / fag.1
1 .TH fag 1 "16 February 2018" "1.2" "User Commands"
2 .hy 0
3 .SH NAME
4 fag \- daemonize program after a regular expression pattern was matched (ForkAfterGrep)
5 .
6 .SH SYNOPSIS
7 .B fag
8 .RI [ OPTIONS ]
9 .I PATTERN
10 .I PROGRAM
11 .RI [ ARGUMENTS .\|.\|.]
12 .br
13 .SH DESCRIPTION
14 .B fag
15 uses
16 .B grep
17 to search the output of
18 .IR PROGRAM
19 for the regular expression
20 .IR PATTERN
21 and daemonizes it when a match is found. The PID is then returned on stdout.
22 .SH OPTIONS
23 .SS "Behaviour Changing Options"
24 .TP
25 .BI \-t " SECONDS" "\fR
26 Set a timeout of
27 .I SECONDS
28 seconds.
29 .TP
30 .BR \-k " [" \fISIGNAL\fP "]
31 If given, send a signal to
32 .IR PROGRAM .
33 .I SIGNAL
34 defaults to
35 .BR SIGTERM " (15)."
36 Right now, only decimal notation is implemented.
37 .TP
38 .BR \-r
39 Search
40 .IR PATTERN
41 on
42 .BR stderr
43 instead of
44 .BR stdout .
45 .TP
46 .BI \-l " FILE "
47 Log
48 .IR PROGRAM\fR's
49 .BR stdout
50 to
51 .IR FILE .
52 The file will be opened in append mode and created with permissions 0600 if it doesn't exist.
53 .TP
54 .BI \-L " FILE "
55 Same as
56 .BR \-l
57 but logs
58 .IR PROGRAM\fR's
59 .BR stderr .
60 .TP
61 .BR \-V
62 Be verbose; print program's
63 .BR stdout
64 (or stderr if
65 .BR \-r
66 is set) to stderr.
67 .SS "Generic Program Information"
68 .TP
69 .B \-h
70 Output a short usage message and exit.
71 .TP
72 .BR \-v
73 Display version and copyright information and exit.
74 .SS "Supported grep Options"
75 .TP
76 .BR \-E ", " \-F ", " \-G ", " \-P
77 Matcher selection switches for extended regular expressions, fixed strings, basic regular expressions (default) or Perl-compatible regular expressions. You may only supply one of them.
78 .TP
79 .BR \-i ", " \-w ", " \-x ", " \-U
80 Matching control switches for ignore case distinctions, whole words only, whole lines only and treat as binary.
81 .TP
82 .BR \-Z ", " \-J
83 Decompression switches for
84 .IR gzip (1)
85 and
86 .IR bzip2 (1).
87 Not widely supported; check your \fBgrep\fR's capabilities.
88 .SH EXIT STATUS
89 If
90 .IR PATTERN
91 was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
92 .B #include <sysexits.h>
93 if the error occured from within
94 .B fag
95 or in case the chid process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
96 .SH BUGS
97 .SS Known Bugs
98 if grep gets killed (e.g. `killall grep'), fag should terminate.
99 .SS Reporting Bugs
100 Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
101 .SH NOTES
102 .IR SIGNAL
103 needs to be given as an integer. implementing mnemonics is dirty and not very portable; maybe support in the future.
104 .PP
105 Since 1.1, if
106 .B fag
107 gets interrupted or terminated,
108 .BR SIGTERM
109 is sent to
110 .IR PROGRAM.
111 .PP
112 In 1.2 the command line switch
113 .B \-e was renamed to
114 .B \-r
115 to avoid overloading
116 .B grep\fR's own switches.
117 .SH COPYRIGHT
118 Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
119 .SH AUTHOR
120 Tobias Girstmair (https://gir.st)
Imprint / Impressum