[forkaftergrep.git] / fag.1

.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH fag 1 "07 February 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
searches the
.IR PROGRAM
for the string
.IR PATTERN .
This is useful if a program takes a while to initialize and prints a message to stdout or stderr when ready. When placed in a script,
.B fag
blocks execution until the pattern was found, then daemonizes the child process, returns the PID on stdout and exits.
.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.
.\".RS
.\".IP *
.\"EX_OK (0): successful termination
.\".IP *
.\"EX_UNAVAILABLE (69): PROGRAM timed out
.\".IP *
.\"EX_USAGE (64): command was used incorrectly (argument error)
.\".IP *
.\"EX_OSERR (71): system error (can't fork, pipe, etc.)
.\".IP *
.\"EX_IOERR (74): input/output error (e.g. can't read)
.\".RE
.SH BUGS
.SS Known Bugs
.IR SIGNAL
needs to be given as an integer; mnemonic should be supported in the future.
.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
Some might find the name of this program offensive. Feel free to create a symlink or alias on your system.
.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
4f83e12d	1	.\" Manpage for nuseradd.
	2	.\" Contact vivek@nixcraft.net.in to correct errors or typos.
	3	.TH fag 1 "07 February 2017" "1.0" "User Commands"
	4	.hy 0
	5	.SH NAME
	6	fag \- daemonize program after a string was found (ForkAfterGrep)
	7	.
	8	.SH SYNOPSIS
	9	.B fag
	10	.RI [ OPTIONS ]
	11	.I PATTERN
	12	.I PROGRAM
	13	.RI [ ARGUMENTS .\\|.\\|.]
	14	.br
	15	.SH DESCRIPTION
	16	.B fag
	17	searches the
	18	.IR PROGRAM
	19	for the string
	20	.IR PATTERN .
	21	This is useful if a program takes a while to initialize and prints a message to stdout or stderr when ready. When placed in a script,
	22	.B fag
	23	blocks execution until the pattern was found, then daemonizes the child process, returns the PID on stdout and exits.
	24	.SH OPTIONS
	25	.SS "Behaviour Changing Options"
	26	.TP
	27	.BI \-t " SECONDS" "\fR
	28	Set a timeout of
	29	.I SECONDS
	30	seconds.
	31	.TP
	32	.BR \-k " [" \fISIGNAL\fP "]
	33	If given, send a signal to
	34	.IR PROGRAM .
	35	.I SIGNAL
	36	defaults to
	37	.BR SIGTERM " (15)."
	38	Right now, only decimal notation is implemented.
	39	.TP
	40	.BR \-e
	41	Search
	42	.IR PATTERN
	43	on
	44	.BR stderr
	45	instead of
	46	.BR stdout .
9949154c	47	.TP
	48	.BR \-V
	49	Be verbose; print program's
	50	.BR stdout
	51	(or stderr if
	52	.BR \-e
	53	is set) to stderr.
4f83e12d	54	.SS "Generic Program Information"
	55	.TP
	56	.B \-h
	57	Output a short usage message and exit.
	58	.TP
	59	.BR \-v
	60	Display version and copyright information and exit.
	61	.SH EXIT STATUS
	62	If
	63	.IR PATTERN
	64	was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
	65	.B #include <sysexits.h>
	66	if the error occured from within
	67	.B fag
	68	or in case the chid process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
	69	.\".RS
	70	.\".IP *
	71	.\"EX_OK (0): successful termination
	72	.\".IP *
	73	.\"EX_UNAVAILABLE (69): PROGRAM timed out
	74	.\".IP *
	75	.\"EX_USAGE (64): command was used incorrectly (argument error)
	76	.\".IP *
	77	.\"EX_OSERR (71): system error (can't fork, pipe, etc.)
	78	.\".IP *
	79	.\"EX_IOERR (74): input/output error (e.g. can't read)
	80	.\".RE
	81	.SH BUGS
	82	.SS Known Bugs
4f83e12d	83	.IR SIGNAL
	84	needs to be given as an integer; mnemonic should be supported in the future.
	85	.PP
	86	Sometimes, stdin behaves strange after the program terminates.
	87	.SS Reporting Bugs
	88	Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
	89	.SH NOTES
	90	Some might find the name of this program offensive. Feel free to create a symlink or alias on your system.
	91	.SH COPYRIGHT
	92	Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
	93	.SH AUTHOR
	94	Tobias Girstmair (http://isticktoit.net)