From: girst Date: Fri, 16 Feb 2018 18:04:06 +0000 (+0100) Subject: cleanup makefile and man page, add examples to readme X-Git-Url: https://git.gir.st/forkaftergrep.git/commitdiff_plain/e261f90d6c1ea6e8558a74e357ed430efc07bd4f cleanup makefile and man page, add examples to readme --- diff --git a/Makefile b/Makefile index afaf910..3dea843 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,19 @@ -.PHONY: all clean +.PHONY: all clean install uninstall + +CC = gcc +CFLAGS = -std=c99 -Wall -Werror -Wextra +PREFIX = $(DESTDIR)/usr/local all: fag fag: fag.c fag.h - gcc -std=c99 -Wall -Werror -Wextra fag.c -o fag + $(CC) $(CFLAGS) $< -o $@ clean: rm -f fag + +install: fag + install -D -m 0755 -t $(PREFIX)/bin/ $^ + +uninstall: + rm -f $(PREFIX)/bin/fag diff --git a/README.md b/README.md index 2073686..84bbf27 100644 --- a/README.md +++ b/README.md @@ -4,37 +4,38 @@ fag(1) User Commands fag(1) NAME - fag - daemonize program after a regular expression pattern was matched - (ForkAfterGrep) + fag - daemonize program after a pattern was matched (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 + 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. + Abort matching after SECONDS seconds and print PROGRAM's PID. + Unless -k is given, PROGRAM is kept running and daemonized. -k[SIGNAL] - If given, send a signal to PROGRAM. SIGNAL defaults to SIGTERM - (15). Right now, only decimal notation is implemented. + If the timeout (-t) has been reached, send a signal to PROGRAM. + SIGNAL defaults to SIGTERM (15). The signal may only be given + as a number. - -r Search PATTERN on stderr instead of stdout. + -r Search for PATTERN on stderr instead of stdout. -l FILE Log PROGRAM's stdout to FILE. The file will be opened in append - mode and created with permissions 0600 if it doesn't exist. + mode. If the file does not exist, it will be created with file + mode 0600. -L FILE Same as -l but logs PROGRAM's stderr. - -V Be verbose; print program's stdout (or stderr if -r is set) to - stderr. + -V Be verbose; print PROGRAM's monitored stream to stderr. Generic Program Information -h Output a short usage message and exit. @@ -43,48 +44,50 @@ OPTIONS Supported grep Options -E, -F, -G, -P - Matcher selection switches for extended regular expressions, - fixed strings, basic regular expressions (default) or Perl- - compatible regular expressions. At most one of them may be + Matcher selection switches for extended regular expressions, + fixed strings, basic regular expressions (default) or Perl- + compatible regular expressions. At most one of them may be supplied. -i, -w, -x, -U - Matching control switches for ignore case distinctions, whole + Matching control switches for ignore case distinctions, whole words only, whole lines only and treat as binary. - -Z, -J Decompression switches for gzip(1) and bzip2(1). Not widely + -Z, -J Decompression switches for gzip(1) and bzip2(1). Not widely supported; check your grep's capabilities. EXIT STATUS If PATTERN was found, 0 is returned. Otherwise, the exit status follows - the BSD guideline outlined in #include 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. + the BSD guideline outlined in #include if the error + occurred from within fag or in case the child process exits + prematurely, its exit code is inherited. Notably, 69 is returned when + the timeout is reached. BUGS Known Bugs + logging stops when a timeout is reached. + if grep gets killed (e.g. `killall grep'), fag should terminate. Reporting Bugs - Please report bugs and patches to the issue tracker at + Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/. NOTES - Usually, fag uses the grep supplied in the path. This behaviour can be + Usually, fag uses the grep supplied in the path. This behaviour can be overridden with the environment variable GREP_OVERRIDE. - Since 1.2, if fag gets interrupted or terminated before a match is - found (or the timeout has been reached), this signal is passed to + Since 1.2, if fag gets interrupted or terminated before a match is + found (or the timeout has been reached), this signal is passed to PROGRAM. - In version 1.2 the command line switch -e was renamed to -r to avoid - overloading grep's own switches. An error will be thrown when -e or -f + In version 1.2 the command line switch -e was renamed to -r to avoid + overloading grep's own switches. An error will be thrown when -e or -f is supplied as an argument. COPYRIGHT - Copyright 2017-2018 Tobias Girstmair. This is free software released - under the terms of the GNU General Public License Version 3; see + Copyright 2017-2018 Tobias Girstmair. This is free software released + under the terms of the GNU General Public License Version 3; see https://www.gnu.org/licenses/gpl-3.0.html for conditions. AUTHOR @@ -93,7 +96,23 @@ AUTHOR 1.2 16 February 2018 fag(1) ``` +## Installation + +Compile the program by issuing `make`. Targets `install` and `uninstall` should work as expected. + ## 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. It also comes handy for `mopidy`, which takes a while to start up and before one can connect to it. + +## Examples + +Wait for `tzap-t2` (DVB-T2 version of `tzap`) to tune into a channel or abort after 1 minute: + + fag -t 60 -k FE_HAS_LOCK ./tzap-t2 -a0 -f1 -V -c channels.vdr "ORF1;ORF" + +--- + +Start [mopidy](https://www.mopidy.com/) and wait for the MPD service to have started up: + + fag -rV -L /tmp/mopidy.log "MPD server running at" mopidy diff --git a/fag.1 b/fag.1 index 793be99..dde70fc 100644 --- a/fag.1 +++ b/fag.1 @@ -1,7 +1,7 @@ .TH fag 1 "16 February 2018" "1.2" "User Commands" .hy 0 .SH NAME -fag \- daemonize program after a regular expression pattern was matched (ForkAfterGrep) +fag \- daemonize program after a pattern was matched (ForkAfterGrep) . .SH SYNOPSIS .B fag @@ -22,21 +22,27 @@ and daemonizes it when a match is found. The PID is then returned on stdout. .SH OPTIONS .SS "Behaviour Changing Options" .TP -.BI \-t " SECONDS" "\fR -Set a timeout of +.BI \-t " SECONDS" +Abort matching after .I SECONDS -seconds. +seconds and print +.IR PROGRAM 's +PID. Unless +.BR \-k +is given, PROGRAM is kept running and daemonized. .TP .BR \-k "[" \fISIGNAL\fP "] -If given, send a signal to +If the timeout +.RB ( \-t ) +has been reached, send a signal to .IR PROGRAM . .I SIGNAL defaults to .BR SIGTERM " (15)." -Right now, only decimal notation is implemented. +The signal may only be given as a number. .TP .BR \-r -Search +Search for .IR PATTERN on .BR stderr @@ -45,25 +51,25 @@ instead of .TP .BI \-l " FILE " Log -.IR PROGRAM\fR's +.IR PROGRAM 's .BR stdout to .IR FILE . -The file will be opened in append mode and created with permissions 0600 if it doesn't exist. +The file will be opened in append mode. If the file does not exist, it will be created with file mode \fI0600\fR. .TP .BI \-L " FILE " Same as .BR \-l but logs -.IR PROGRAM\fR's +.IR PROGRAM 's .BR stderr . .TP .BR \-V -Be verbose; print program's -.BR stdout -(or stderr if -.BR \-r -is set) to stderr. +Be verbose; print +.IR PROGRAM 's +monitored stream +to +.BR stderr . .SS "Generic Program Information" .TP .B \-h @@ -84,17 +90,21 @@ Decompression switches for .IR gzip (1) and .IR bzip2 (1). -Not widely supported; check your \fBgrep\fR's capabilities. +Not widely supported; check your +.BR grep 's +capabilities. .SH EXIT STATUS If .IR PATTERN was found, 0 is returned. Otherwise, the exit status follows the BSD guideline outlined in .B #include -if the error occured from within +if the error occurred 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. +or in case the child process exits prematurely, its exit code is inherited. Notably, \fI69\fP is returned when the timeout is reached. .SH BUGS .SS Known Bugs +logging stops when a timeout is reached. +.PP if grep gets killed (e.g. `killall grep'), fag should terminate. .SS Reporting Bugs Please report bugs and patches to the issue tracker at https://github.com/girst/forkaftergrep/. @@ -115,7 +125,8 @@ In version 1.2 the command line switch .B \-e was renamed to .B \-r to avoid overloading -.B grep\fR's own switches. An error will be thrown when +.BR grep 's +own switches. An error will be thrown when .BR \-e or .BR \-f diff --git a/fag.c b/fag.c index 1ba077d..cd2fe66 100644 --- a/fag.c +++ b/fag.c @@ -329,7 +329,11 @@ int fork_after_grep (struct opt opts) { timersub (&now, &begin, &diff); if (diff.tv_sec >= opts.timeout) { fprintf (stderr, "Timeout reached. \n"); + printf ("%d\n", cpid); + fflush (stdout); + if (opts.kill_sig > 0) kill (cpid, opts.kill_sig); + close (pipefd[0]); close (grep_pipefd[1]); close (primary_logfile);