Add notes about unbuffering

[forkaftergrep.git] / fag.1

.TH fag 1 "16 February 2018" "1.2" "User Commands"
.hy 0
.SH NAME
fag \- daemonize program after a pattern was matched (ForkAfterGrep)
.
.SH SYNOPSIS
.B fag
.RI [ OPTIONS ]
.I PATTERN
.I PROGRAM
.RI [ ARGUMENTS .\|.\|.]
.br
.SH DESCRIPTION
.B fag
uses
.B grep
to search the output of
.IR PROGRAM
for the regular expression
.IR PATTERN
and daemonizes it when a match is found. The PID is then returned on stdout. 
.SH OPTIONS
.SS "Behaviour Changing Options"
.TP
.BI \-t " SECONDS"
Abort matching after
.I SECONDS
seconds and print 
.IR PROGRAM 's
PID. Unless
.BR \-k
is given, PROGRAM is kept running and daemonized.
.TP
.BR \-k "[" \fISIGNAL\fP "]
If the timeout
.RB ( \-t )
has been reached, send a signal to
.IR PROGRAM .
.I SIGNAL
defaults to 
.BR SIGTERM " (15)."
The signal may only be given as a number.
.TP
.BR \-r
Search for
.IR PATTERN
on
.BR stderr
instead of 
.BR stdout .
.TP
.BI \-l " FILE "
Log
.IR PROGRAM 's
.BR stdout
to
.IR FILE .
The file will be opened in append mode. If the file does not exist, it will be created with file mode \fI0600\fR.
.TP
.BI \-L " FILE "
Same as 
.BR \-l
but logs
.IR PROGRAM 's
.BR stderr .
.TP
.BR \-V
Be verbose; print
.IR PROGRAM 's
monitored stream
to
.BR stderr .
.SS "Generic Program Information"
.TP
.B \-h
Output a short usage message and exit.
.TP
.BR \-v
Display version and copyright information and exit.
.SS "Supported grep Options"
.TP
.BR \-E ", " \-F ", " \-G ", " \-P
Matcher 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.
.TP
.BR \-i ", " \-w ", " \-x ", " \-U
Matching control switches for ignore case distinctions, whole words only, whole lines only and treat as binary. 
.TP
.BR \-Z ", " \-J
Decompression switches for 
.IR gzip (1)
and 
.IR bzip2 (1).
Not widely supported; check your
.BR grep 's
capabilities.
.SH EXIT STATUS
If
.IR PATTERN
was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in 
.B #include <sysexits.h>
if the error occurred from within
.B fag
or in case the child process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
.SH BUGS
.SS Known Bugs
logging stops when a timeout is reached.
.PP
if grep gets killed (e.g. `killall grep'), fag should terminate. 
.SS Reporting Bugs
Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/. 
.SH NOTES
Usually,
.B fag
uses the
.B grep 
supplied in the path. This behaviour can be overridden with the environment variable
.IR GREP_OVERRIDE .
.PP
.B fag
works best when
.IR PROGRAM 's
output is line-buffered.
.BR stdbuf (1)
from the GNU coreutils can adjust buffering options. If a program is still too clever,
.BR script (1)
creates a pty to wrap around a program.
.PP
Since 1.2, if
.B fag
gets interrupted or terminated before a match is found (or the timeout has been reached), this signal is passed to 
.IR PROGRAM .
.PP
In version 1.2 the command line switch 
.B \-e was renamed to 
.B \-r
to avoid overloading 
.BR grep 's
own switches. An error will be thrown when
.BR \-e
or
.BR \-f
is supplied as an argument.
.SH COPYRIGHT
Copyright 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.
.SH AUTHOR
Tobias Girstmair (https://gir.st/)