README.md

   1 # consume
   2 The **consume** program splits input, feeds it into the given utility and consumes it if successful.
   3
   4 ## Features
   5 * Quality
   6     * Compiled with security hardening flags.
   7     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
   8     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
   9     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`.
  10     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9).
  11 * Portable
  12     * C99 compliant *and* may be built in an environment which provides POSIX.1-2008 system interfaces.
  13     * Self-contained, no external dependencies.
  14     * Easy to compile and uses POSIX make.
  15
  16 ## Limitations
  17 * Input lines are limited to `LINE_MAX` bytes in lenght.
  18 * Input file names are limited to `BUFSIZ` bytes in length.
  19
  20 ## Build dependencies
  21 The only dependency is a toolchain supporting the following flags:
  22
  23 ```
  24 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
  25         -Walloca -Wcast-qual -Wconversion -Wformat=2 -Wformat-security \
  26         -Wnull-dereference -Wstack-protector -Wvla -Warray-bounds \
  27         -Wbad-function-cast -Wconversion -Wshadow -Wstrict-overflow=4 -Wundef \
  28         -Wstrict-prototypes -Wswitch-default -Wfloat-equal -Wimplicit-fallthrough \
  29         -Wpointer-arith -Wswitch-enum \
  30         -D_FORTIFY_SOURCE=2 \
  31         -fstack-protector-strong -fPIE -fstack-clash-protection
  32
  33 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack -Wl,-z,separate-code
  34 ```
  35
  36 Otherwise you can just remove the security flags and compile it with
  37 ```
  38 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic
  39 LDFLAGS =
  40 ```
  41
  42 or pass your own flags to make
  43 ```sh
  44 make CC=gcc CFLAGS=... LDFLAGS=...
  45 ```
  46
  47 ## Installation
  48 Clone this repository then
  49
  50 ```sh
  51 $ make PREFIX=/usr install
  52 ```
  53
  54 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
  55 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
  56 not have to be installed before use.
  57
  58 ## Usage
  59 ```
  60 consume [-0ach] [-i file] [-v] [utility [argument ...]]
  61 ```
  62 The **consume** program reads input from the file named by the `file` operand or from `stdin` if absent, and splits it
  63 when encountering the given delimiter (defaults to newline). It then invokes the `utility` repeatedly, feeding it the
  64 generated data as input. On success the given data is consumed (removed) from the input file, if any.
  65
  66 The options are as follows:
  67
  68 * `-a` input items are fed as a command-line argument to `utility`.
  69 * `-0` input items are teminated by a null character instead of by newline. The GNU find -print0 option produces input
  70 suitable for this mode.
  71 * `-c` continue even if `utility` failed.
  72 * `-h` print usage information and exit.
  73 * `-i file` read items from `file` instead of standard input.
  74 * `-v` print the command line on the standard error ouput before executing it.
  75
  76 ### Examples
  77 Count the number of words in each line of 'La Divina Commedia':
  78 ```sh
  79 $ curl -s https://dmf.unicatt.it/~della/pythoncourse18/commedia.txt | consume wc -w
  80 ```
  81 Find files named `core` in or below the directory `/tmp` and delete them. Before deleting each file the full command is
  82 printed to `stderr`:
  83 ```sh
  84 $ find /tmp -name core -type f -print | consume -a -v /bin/rm -f
  85 ```
  86 Consume all lines delimited by `0` in biglistoflinks.txt that wget has downloaded successfully:
  87 ```sh
  88 $ consume -0 -a -i biglistoflinks.txt wget -qc
  89 ```
  90
  91 ### Static analysis
  92 Static analysis on the code base is done by using clang's static analyzer run through `scan-build.sh` which wraps the
  93 `scan-build` utility. The checkers used are part of the
  94 [Experimental Checkers](https://releases.llvm.org/12.0.0/tools/clang/docs/analyzer/checkers.html#alpha-checkers)
  95 (aka *alpha* checkers):
  96
  97 * `alpha.security`
  98 * `alpha.core.CastSize`
  99 * `alpha.core.CastToStruct`
 100 * `alpha.core.IdenticalExpr`
 101 * `alpha.core.PointerArithm`
 102 * `alpha.core.PointerSub`
 103 * `alpha.core.SizeofPtr`
 104 * `alpha.core.TestAfterDivZero`
 105 * `alpha.unix`
 106
 107 ## Contributing
 108 Send patches on the [mailing list](https://www.freelists.org/list/consume-dev), report bugs on the [issue tracker](https://todo.sr.ht/~spidernet/consume).
 109
 110 ## License
 111 BSD 2-Clause FreeBSD License, see LICENSE.