Add notes about unbuffering
[forkaftergrep.git] / fag.1
CommitLineData
649053e3 1.TH fag 1 "16 February 2018" "1.2" "User Commands"
4f83e12d 2.hy 0
3.SH NAME
e261f90d 4fag \- daemonize program after a pattern was matched (ForkAfterGrep)
4f83e12d 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
629b060c 15uses
16.B grep
17to search the output of
4f83e12d 18.IR PROGRAM
629b060c 19for the regular expression
20.IR PATTERN
21and daemonizes it when a match is found. The PID is then returned on stdout.
4f83e12d 22.SH OPTIONS
23.SS "Behaviour Changing Options"
24.TP
e261f90d 25.BI \-t " SECONDS"
26Abort matching after
4f83e12d 27.I SECONDS
e261f90d 28seconds and print
29.IR PROGRAM 's
30PID. Unless
31.BR \-k
32is given, PROGRAM is kept running and daemonized.
4f83e12d 33.TP
4495ab75 34.BR \-k "[" \fISIGNAL\fP "]
e261f90d 35If the timeout
36.RB ( \-t )
37has been reached, send a signal to
4f83e12d 38.IR PROGRAM .
39.I SIGNAL
40defaults to
41.BR SIGTERM " (15)."
e261f90d 42The signal may only be given as a number.
4f83e12d 43.TP
649053e3 44.BR \-r
e261f90d 45Search for
4f83e12d 46.IR PATTERN
47on
48.BR stderr
49instead of
50.BR stdout .
9949154c 51.TP
c7c46781 52.BI \-l " FILE "
53Log
e261f90d 54.IR PROGRAM 's
c7c46781 55.BR stdout
56to
57.IR FILE .
e261f90d 58The file will be opened in append mode. If the file does not exist, it will be created with file mode \fI0600\fR.
c7c46781 59.TP
60.BI \-L " FILE "
61Same as
62.BR \-l
63but logs
e261f90d 64.IR PROGRAM 's
c7c46781 65.BR stderr .
66.TP
9949154c 67.BR \-V
e261f90d 68Be verbose; print
69.IR PROGRAM 's
70monitored stream
71to
72.BR stderr .
4f83e12d 73.SS "Generic Program Information"
74.TP
75.B \-h
76Output a short usage message and exit.
77.TP
78.BR \-v
79Display version and copyright information and exit.
c7c46781 80.SS "Supported grep Options"
81.TP
82.BR \-E ", " \-F ", " \-G ", " \-P
4495ab75 83Matcher selection switches for extended regular expressions, fixed strings, basic regular expressions (default) or Perl-compatible regular expressions. At most one of them may be supplied.
c7c46781 84.TP
85.BR \-i ", " \-w ", " \-x ", " \-U
86Matching control switches for ignore case distinctions, whole words only, whole lines only and treat as binary.
87.TP
88.BR \-Z ", " \-J
89Decompression switches for
90.IR gzip (1)
91and
92.IR bzip2 (1).
e261f90d 93Not widely supported; check your
94.BR grep 's
95capabilities.
4f83e12d 96.SH EXIT STATUS
97If
98.IR PATTERN
99was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
100.B #include <sysexits.h>
e261f90d 101if the error occurred from within
4f83e12d 102.B fag
e261f90d 103or in case the child process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
4f83e12d 104.SH BUGS
105.SS Known Bugs
e261f90d 106logging stops when a timeout is reached.
107.PP
b98f2a91 108if grep gets killed (e.g. `killall grep'), fag should terminate.
4f83e12d 109.SS Reporting Bugs
110Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
111.SH NOTES
4495ab75 112Usually,
113.B fag
114uses the
115.B grep
116supplied in the path. This behaviour can be overridden with the environment variable
117.IR GREP_OVERRIDE .
7966a08a 118.PP
e49d9f33 119.B fag
120works best when
121.IR PROGRAM 's
122output is line-buffered.
123.BR stdbuf (1)
124from the GNU coreutils can adjust buffering options. If a program is still too clever,
125.BR script (1)
126creates a pty to wrap around a program.
127.PP
4495ab75 128Since 1.2, if
7966a08a 129.B fag
4495ab75 130gets interrupted or terminated before a match is found (or the timeout has been reached), this signal is passed to
131.IR PROGRAM .
649053e3 132.PP
4495ab75 133In version 1.2 the command line switch
649053e3 134.B \-e was renamed to
135.B \-r
136to avoid overloading
e261f90d 137.BR grep 's
138own switches. An error will be thrown when
4495ab75 139.BR \-e
140or
141.BR \-f
142is supplied as an argument.
4f83e12d 143.SH COPYRIGHT
4495ab75 144Copyright 2017-2018 Tobias Girstmair. This is free software released under the terms of the GNU General Public License Version 3; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
4f83e12d 145.SH AUTHOR
4495ab75 146Tobias Girstmair (https://gir.st/)
Imprint / Impressum