git.gir.st - forkaftergrep.git/blame_incremental

... / ...

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