update date; copy current manpage to readme
[forkaftergrep.git] / fag.1
1 .TH fag 1 "12 August 2017" "1.0" "User Commands"
2 .hy 0
3 .SH NAME
4 fag \- daemonize program after a string was found (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 \-e
39 Search
40 .IR PATTERN
41 on
42 .BR stderr
43 instead of
44 .BR stdout .
45 .TP
46 .BR \-V
47 Be verbose; print program's
48 .BR stdout
49 (or stderr if
50 .BR \-e
51 is set) to stderr.
52 .SS "Generic Program Information"
53 .TP
54 .B \-h
55 Output a short usage message and exit.
56 .TP
57 .BR \-v
58 Display version and copyright information and exit.
59 .SH EXIT STATUS
60 If
61 .IR PATTERN
62 was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
63 .B #include <sysexits.h>
64 if the error occured from within
65 .B fag
66 or in case the chid process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
67 .SH BUGS
68 .SS Known Bugs
69 if grep exits with a code > 0, fag should terminate with grep's exit code and an error message. instead, fag exits as if a match was found.
70 .PP
71 Sometimes, stdin behaves strange after the program terminates.
72 .SS Reporting Bugs
73 Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
74 .SH NOTES
75 .IR SIGNAL
76 needs to be given as an integer. implementing mnemonics is dirty and not very portable; maybe support in the future.
77 .SH COPYRIGHT
78 Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
79 .SH AUTHOR
80 Tobias Girstmair (http://isticktoit.net)
Imprint / Impressum