README.md

   1 # shuf
   2 The **shuf** utility shuffles its input by outputting a random permutation of its input lines.
   3 It is not a one-to-one reimplementation of the `shuf(1)` utility from GNU coreutils since it lacks some of its
   4 command-line options.
   5
   6 ## Features
   7 * Quality
   8     * Compiled with security hardening flags.
   9     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
  10     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
  11     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`.
  12     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9).
  13 * Portable
  14     * C99 compliant *and* may be built in an environment which provides POSIX.1-2001 system interfaces.
  15     * Self-contained, no external dependencies.
  16     * Easy to compile and uses POSIX make.
  17
  18 ## Limitations
  19 * Input lines are limited to `BUFSIZ` bytes in lenght.
  20 * Does not implement the `-z` and `--random-source=file` flags present in GNU coreutils' `shuf(1)`.
  21 * Uses the `rand()` function from `stdlib.h`.
  22
  23 ## Build dependencies
  24 The only dependency is a toolchain supporting the following flags:
  25
  26 ```
  27 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
  28         -Walloca -Wcast-qual -Wconversion -Wformat=2 -Wformat-security \
  29         -Wnull-dereference -Wstack-protector -Wvla -Warray-bounds \
  30         -Wbad-function-cast -Wconversion -Wshadow -Wstrict-overflow=4 -Wundef \
  31         -Wstrict-prototypes -Wswitch-default -Wfloat-equal -Wimplicit-fallthrough \
  32         -Wpointer-arith -Wswitch-enum \
  33         -D_FORTIFY_SOURCE=2 \
  34         -fstack-protector-strong -fPIE -fstack-clash-protection
  35
  36 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack -Wl,-z,separate-code
  37 ```
  38
  39 Otherwise you can just remove the security flags and compile it with
  40 ```
  41 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic
  42 LDFLAGS =
  43 ```
  44
  45 or pass your own flags to make
  46 ```sh
  47 make CC=gcc CFLAGS=... LDFLAGS=...
  48 ```
  49
  50 ## Installation
  51 Clone this repository then
  52
  53 ```sh
  54 $ make PREFIX=/usr install
  55 ```
  56
  57 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
  58 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
  59 not have to be installed before use.
  60
  61 ## Usage
  62 ```
  63 shuf [-h] [-n count] [-o outfile] [-r] [file]
  64 shuf [-h] -e [-n count] [-o outfile] [-r] [args ...]
  65 shuf [-h] -i lo-hi [-n count] [-o outfile] [-r]
  66 ```
  67 **shuf** has three modes of operation that control how the input is obtained. By default it takes input from standard
  68 input. The input file can be omitted, in this case the program takes the input from the standard input until `EOF` or
  69 `^D` is reached. If a file is a single dash (‘-’), **shuf** reads from standard input. The other two modes can be
  70 switched by means of the `-e` and `-i` flags:
  71
  72 * `-e` treats each command-line operand as an input line.
  73 * `-i` acts as input came from a file containing the numbers in the interval of unsigned integers [lo,hi] one on each
  74 line.
  75
  76 The three modes cannot be mixed together.
  77
  78 The other options are as follows:
  79
  80 * `-h` print usage information and exit.
  81 * `-n count` output at most `count` lines.
  82 * `-o outfile` output lines are printed on the specified file instead of standard output.
  83 * `-r` repeat values. When this option is turned on, the output no longer contains permutations of the input lines,
  84 instead each output line is randomly chosen from all the input lines. If `-n` is not also given, `shuf` prints randomly
  85 chosen input lines indefinitely.
  86
  87 ### Examples
  88 Output 5 random numbers in the range 0-2:
  89 ```sh
  90 $ shuf -n 5 -r -i 0-2
  91 ```
  92 Flip a coin ten times:
  93 ```sh
  94 $ shuf -e -n 10 -r Heads Tails
  95 ```
  96 Select five numbers from 10 to 20:
  97 ```sh
  98 $ shuf -i 10-20 -n 5
  99 ```
 100 Shuffle what is provided on standard input and write the output to out
 101 ```sh
 102 $ shuf -o out
 103 ```
 104
 105 ### Static analysis
 106 Static analysis on the code base is done by using clang's static analyzer run through `scan-build.sh` which wraps the
 107 `scan-build` utility. The checkers used are part of the
 108 [Experimental Checkers](https://releases.llvm.org/12.0.0/tools/clang/docs/analyzer/checkers.html#alpha-checkers)
 109 (aka *alpha* checkers):
 110
 111 * `alpha.security`
 112 * `alpha.core.CastSize`
 113 * `alpha.core.CastToStruct`
 114 * `alpha.core.IdenticalExpr`
 115 * `alpha.core.PointerArithm`
 116 * `alpha.core.PointerSub`
 117 * `alpha.core.SizeofPtr`
 118 * `alpha.core.TestAfterDivZero`
 119 * `alpha.unix`
 120
 121 ## Contributing
 122 Send patches on the [mailing list](https://www.freelists.org/list/shuf-dev), report bugs using [git-bug](https://github.com/MichaelMure/git-bug/).
 123
 124 ## License
 125 BSD 2-Clause FreeBSD License, see LICENSE.
 126