[forkaftergrep.git] / README.md

# `fag` (Fork After Grep)

```
fag(1)                           User Commands                          fag(1)

NAME
       fag - daemonize program after a string was found (ForkAfterGrep)

SYNOPSIS
       fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]

DESCRIPTION
       fag  uses  grep  to  search  the  output  of  PROGRAM  for  the regular
       expression PATTERN and daemonizes it when a match is found. The PID  is
       then returned on stdout.

OPTIONS
   Behaviour Changing Options
       -t SECONDS
              Set a timeout of SECONDS seconds.

       -k [SIGNAL]
              If  given, send a signal to PROGRAM.  SIGNAL defaults to SIGTERM
              (15).  Right now, only decimal notation is implemented.

       -e     Search PATTERN on stderr instead of stdout.

       -V     Be verbose; print program's stdout (or stderr if -e is  set)  to
              stderr.

   Generic Program Information
       -h     Output a short usage message and exit.

       -v     Display version and copyright information and exit.

EXIT STATUS
       If PATTERN was found, 0 is returned. Otherwise, the exit status follows
       the BSD guideline  outlined  in  #include  <sysexits.h>  if  the  error
       occured  from within fag or in case the chid process exits prematurely,
       its exit code is inherited. Notably, 69 is returned when the timeout is
       reached.

BUGS
   Known Bugs
       SIGNAL needs to be given as an integer; mnemonic should be supported in
       the future.

       Sometimes, stdin behaves strange after the program terminates.

   Reporting Bugs
       Please  report   bugs   and   patches   to   the   issue   tracker   at
       https://github.com/girst/forkaftergrep/.

NOTES
       Some might find the name of this program offensive. Feel free to create
       a symlink or alias on your system.

COPYRIGHT
       Copyright  2017  Tobias  Girstmair.  This   is   free   software;   see
       https://www.gnu.org/licenses/gpl-3.0.html for conditions.

AUTHOR
       Tobias Girstmair (http://isticktoit.net)

1.0                              28 July 2017                           fag(1)
```

## Notes

I've written this program for the [`tzap`/`szap`](https://linuxtv.org/wiki/index.php/Zap) utilities. They take a few seconds until the TV card/stick is tuned, and won't fork off when they are ready (If you terminate them, the tuning will end). Instead of waiting a few seconds, and hoping for the best, this does the exactly right thing.
Commit	Line	Data
4f83e12d	1	# `fag` (Fork After Grep)
	2
	3	```
	4	fag(1) User Commands fag(1)
	5
	6	NAME
	7	fag - daemonize program after a string was found (ForkAfterGrep)
	8
	9	SYNOPSIS
	10	fag [OPTIONS] PATTERN PROGRAM [ARGUMENTS...]
	11
	12	DESCRIPTION
ddfcc26d	13	fag uses grep to search the output of PROGRAM for the regular
	14	expression PATTERN and daemonizes it when a match is found. The PID is
	15	then returned on stdout.
4f83e12d	16
	17	OPTIONS
	18	Behaviour Changing Options
	19	-t SECONDS
	20	Set a timeout of SECONDS seconds.
	21
	22	-k [SIGNAL]
	23	If given, send a signal to PROGRAM. SIGNAL defaults to SIGTERM
	24	(15). Right now, only decimal notation is implemented.
	25
	26	-e Search PATTERN on stderr instead of stdout.
	27
ddfcc26d	28	-V Be verbose; print program's stdout (or stderr if -e is set) to
	29	stderr.
	30
4f83e12d	31	Generic Program Information
	32	-h Output a short usage message and exit.
	33
	34	-v Display version and copyright information and exit.
	35
	36	EXIT STATUS
	37	If PATTERN was found, 0 is returned. Otherwise, the exit status follows
ddfcc26d	38	the BSD guideline outlined in #include <sysexits.h> if the error
ddfcc26d	39	occured from within fag or in case the chid process exits prematurely,
4f83e12d	40	its exit code is inherited. Notably, 69 is returned when the timeout is
	41	reached.
	42
	43	BUGS
	44	Known Bugs
4f83e12d	45	SIGNAL needs to be given as an integer; mnemonic should be supported in
	46	the future.
	47
	48	Sometimes, stdin behaves strange after the program terminates.
	49
	50	Reporting Bugs
	51	Please report bugs and patches to the issue tracker at
	52	https://github.com/girst/forkaftergrep/.
	53
	54	NOTES
	55	Some might find the name of this program offensive. Feel free to create
	56	a symlink or alias on your system.
	57
	58	COPYRIGHT
ddfcc26d	59	Copyright 2017 Tobias Girstmair. This is free software; see
4f83e12d	60	https://www.gnu.org/licenses/gpl-3.0.html for conditions.
	61
	62	AUTHOR
	63	Tobias Girstmair (http://isticktoit.net)
	64
ddfcc26d	65	1.0 28 July 2017 fag(1)
4f83e12d	66	```
3c8bd809	67
	68	## Notes
	69
	70	I've written this program for the [`tzap`/`szap`](https://linuxtv.org/wiki/index.php/Zap) utilities. They take a few seconds until the TV card/stick is tuned, and won't fork off when they are ready (If you terminate them, the tuning will end). Instead of waiting a few seconds, and hoping for the best, this does the exactly right thing.