shuf.1

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   2
   3 .\" Copyright (c) 2022 Alessio Chiapperini
   4
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25
  26 .Dd January 21, 2022
  27 .Dt SHUF 1
  28 .Os
  29 .Sh NAME
  30 .Nm shuf
  31 .Nd generate random permutations
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl h
  35 .Op Fl n Ar count
  36 .Op Fl o Ar outfile
  37 .Op Fl r
  38 .Op Ar file
  39 .Nm
  40 .Op Fl h
  41 .Fl e
  42 .Op Fl n Ar count
  43 .Op Fl o Ar outfile
  44 .Op Fl r
  45 .Op Ar args ...
  46 .Nm
  47 .Op Fl h
  48 .Fl i Ar lo-hi
  49 .Op Fl n Ar count
  50 .Op Fl o Ar outfile
  51 .Op Fl r
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 utility shuffles its input by outputting a random permutation of its input lines.
  56 .Pp
  57 The options are as follows:
  58 .Bl -tag -width indent
  59 .It Fl e
  60 Treat each command-line operand in
  61 .Ar args
  62 as an input line.
  63 .Pp
  64 Cannot be combined with
  65 .Fl i .
  66 .It Fl h
  67 Print usage information and exit
  68 .It Fl i Ar lo-hi
  69 act as input came from a file containing the numbers in the interval of unsigned integers
  70 .Ar lo-hi
  71 one on each line. The range of possible values for
  72 .Ar lo-hi
  73 is [0,
  74 .Dv LONG_MAX Ns -1].
  75 .It Fl n Ar count
  76 output at most
  77 .Ar count
  78 lines.
  79 .It Fl o Ar outfile
  80 output lines are printed on
  81 .Ar outfile
  82 instead of standard output.
  83 .It Fl r
  84 repeat values. When this option is turned on, the output no longer contains permutations of the input lines,
  85 instead each output line is randomly chosen from all the input lines. If
  86 .Fl n
  87 is not also given,
  88 .Nm
  89 prints randomly chosen input lines indefinitely.
  90 .El
  91 .Sh "EXIT STATUS"
  92 The
  93 .Nm
  94 utility exits 0 on success, and 1 if an error occurs.
  95 .Sh EXAMPLES
  96 Output 5 random numbers in the range 0-2:
  97 .Dl "shuf -n 5 -r -i 0-2"
  98 .Pp
  99 Flip a coin ten times:
 100 .Dl shuf -e -n 10 -r Heads Tails
 101 .Pp
 102 Select five numbers from 10 to 20:
 103 .Dl shuf -i 10-20 -n 5
 104 .Pp
 105 Shuffle what is provided on standard input and write the output to
 106 .Ar out
 107 .Dl shuf -o out
 108 .Sh BUGS
 109 .Bl -tag -width indent
 110 .It Input lines are limited to BUFSIZ bytes in length.
 111 .It Does not implement the -z and --random-source=file flags present in GNU coreutils' Nm
 112 .It Uses the rand() function from stdlib.h.
 113 .El
 114 .Sh AUTHOR
 115 .An Alessio Chiapperini Aq Mt alessio.chiapperini@\:nullbuffer.com
 116
 117