initial version
[forkaftergrep.git] / fag.1
CommitLineData
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
6fag \- 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
17searches the
18.IR PROGRAM
19for the string
20.IR PATTERN .
21This 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
23blocks 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
28Set a timeout of
29.I SECONDS
30seconds.
31.TP
32.BR \-k " [" \fISIGNAL\fP "]
33If given, send a signal to
34.IR PROGRAM .
35.I SIGNAL
36defaults to
37.BR SIGTERM " (15)."
38Right now, only decimal notation is implemented.
39.TP
40.BR \-e
41Search
42.IR PATTERN
43on
44.BR stderr
45instead of
46.BR stdout .
47.SS "Generic Program Information"
48.TP
49.B \-h
50Output a short usage message and exit.
51.TP
52.BR \-v
53Display version and copyright information and exit.
54.SH EXIT STATUS
55If
56.IR PATTERN
57was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in
58.B #include <sysexits.h>
59if the error occured from within
60.B fag
61or 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
76Only a simple string search is performed on
77.IR PATTERN
78in this version.
79.PP
80If a
81.IR PROGRAM
82like
83.BR cat
84opens stdout/stderr, but never writes to it, the timeout isn't triggered.
85.PP
86.IR SIGNAL
87needs to be given as an integer; mnemonic should be supported in the future.
88.PP
89Sometimes, stdin behaves strange after the program terminates.
90.SS Reporting Bugs
91Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/.
92.SH NOTES
93Some might find the name of this program offensive. Feel free to create a symlink or alias on your system.
94.SH COPYRIGHT
95Copyright 2017 Tobias Girstmair. This is free software; see https://www.gnu.org/licenses/gpl-3.0.html for conditions.
96.SH AUTHOR
97Tobias Girstmair (http://isticktoit.net)
Imprint / Impressum