[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 .
.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
Only a simple string search is performed on
.IR PATTERN
in this version.
.PP
If a
.IR PROGRAM
like
.BR cat
opens stdout/stderr, but never writes to it, the timeout isn't triggered.
.PP
.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 .
	47	.SS "Generic Program Information"
	48	.TP
	49	.B \-h
	50	Output a short usage message and exit.
	51	.TP
	52	.BR \-v
	53	Display version and copyright information and exit.
	54	.SH EXIT STATUS
	55	If
	56	.IR PATTERN
	57	was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
	58	.B #include <sysexits.h>
	59	if the error occured from within
	60	.B fag
	61	or in case the chid process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached.
	62	.\".RS
	63	.\".IP *
	64	.\"EX_OK (0): successful termination
65	.\".IP *
66	.\"EX_UNAVAILABLE (69): PROGRAM timed out
67	.\".IP *
68	.\"EX_USAGE (64): command was used incorrectly (argument error)
69	.\".IP *
70	.\"EX_OSERR (71): system error (can't fork, pipe, etc.)
71	.\".IP *
72	.\"EX_IOERR (74): input/output error (e.g. can't read)
73	.\".RE
74	.SH BUGS
75	.SS Known Bugs
76	Only a simple string search is performed on
77	.IR PATTERN
78	in this version.
79	.PP
80	If a
81	.IR PROGRAM
82	like
83	.BR cat
84	opens stdout/stderr, but never writes to it, the timeout isn't triggered.
85	.PP
86	.IR SIGNAL
87	needs to be given as an integer; mnemonic should be supported in the future.
88	.PP
89	Sometimes, stdin behaves strange after the program terminates.
90	.SS Reporting Bugs
91	Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
92	.SH NOTES
93	Some might find the name of this program offensive. Feel free to create a symlink or alias on your system.
94	.SH COPYRIGHT
95	Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
96	.SH AUTHOR
97	Tobias Girstmair (http://isticktoit.net)