fag.1

   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)