cleanup makefile and man page, add examples to readme
authorgirst <girst@users.noreply.github.com>
Fri, 16 Feb 2018 18:04:06 +0000 (19:04 +0100)
committergirst <girst@users.noreply.github.com>
Fri, 16 Feb 2018 18:04:06 +0000 (19:04 +0100)
Makefile
README.md
fag.1
fag.c

index afaf910b08d3eb14c31c7fc859edb044cf2af281..3dea84393008842f208737a440cdd0540c794502 100644 (file)
--- 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
index 2073686e1de8d8cbca14a6b47769d45b4e038d31..84bbf270c58f87fb0dba32c4eb8a7d9ddc842469 100644 (file)
--- 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  <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.
+       the BSD guideline  outlined  in  #include  <sysexits.h>  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 793be99cd6f790f7f114a43629d68ebe5b7cc763..dde70fc56f495e05e742581f5aaf7188f7365f4a 100644 (file)
--- 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 <sysexits.h>
-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 1ba077d0b9f486ff0dfeaa27b8ec16114fef4593..cd2fe660adab10c6c3e6860e2ccf7febe480e323 100644 (file)
--- 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);
Imprint / Impressum