[forkaftergrep.git] / fag.1

.TH fag 1 "12 August 2017" "1.0" "User Commands"
.hy 0
.SH NAME
fag \- daemonize program after a string was found (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" "\fR
Set a timeout of
.I SECONDS
seconds.
.TP
.BR \-k " [" \fISIGNAL\fP "]
If given, send a signal to
.IR PROGRAM .
.I SIGNAL
defaults to 
.BR SIGTERM " (15)."
Right now, only decimal notation is implemented.
.TP
.BR \-e
Search
.IR PATTERN
on
.BR stderr
instead of 
.BR stdout .
.TP
.BR \-V
Be verbose; print program's
.BR stdout
(or stderr if
.BR \-e
is set) to 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.
.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 occured from within
.B fag
or in case the chid process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
.SH BUGS
.SS Known Bugs
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. 
.PP
Sometimes, stdin behaves strange after the program terminates. 
.SS Reporting Bugs
Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/. 
.SH NOTES
.IR SIGNAL
needs to be given as an integer. implementing mnemonics is dirty and not very portable; maybe support in the future.
.SH COPYRIGHT
Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
.SH AUTHOR
Tobias Girstmair (http://isticktoit.net)
Commit	Line	Data
9505a99f	1	.TH fag 1 "12 August 2017" "1.0" "User Commands"
4f83e12d	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
629b060c	15	uses
	16	.B grep
	17	to search the output of
4f83e12d	18	.IR PROGRAM
629b060c	19	for the regular expression
	20	.IR PATTERN
	21	and 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
	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 .
9949154c	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.
4f83e12d	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.
4f83e12d	67	.SH BUGS
4f83e12d	68	.SS Known Bugs
05257d9b	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.
05257d9b	70	.PP
4f83e12d	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
de1e8d30	75	.IR SIGNAL
de1e8d30	76	needs to be given as an integer. implementing mnemonics is dirty and not very portable; maybe support in the future.
4f83e12d	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)