1 files changed, 117 insertions, 0 deletions
diff --git a/usr.bin/random/random.6 b/usr.bin/random/random.6
new file mode 100644
index 000000000000..3cbcfa1e6085
--- /dev/null
+++ b/usr.bin/random/random.6
@@ -0,0 +1,117 @@
+.\" Copyright (c) 1994
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd February 15, 2020
+.Dt RANDOM 6
+.Os
+.Sh NAME
+.Nm random
+.Nd random lines from a file or random numbers
+.Sh SYNOPSIS
+.Nm
+.Op Fl elrUuw
+.Op Fl f Ar filename
+.Op Ar denominator
+.Sh DESCRIPTION
+.Nm Random
+has two distinct modes of operations.
+The default is to read lines from standard input and write them to standard
+output with a probability of 1.0 /
+.Ar denominator .
+.Ar ( denominator
+is a real number greater than or equal to 1.0.)
+The default
+.Ar denominator
+for this mode of operation is 2.0, giving each line a 50% chance of
+being displayed.
+.Pp
+The second mode of operation, selected with the
+.Fl f Ar filename
+option, reads the specified file and outputs the randomized contents to
+standard output.
+The contents can be randomized in units of lines (split on newline characters)
+or in units of words (split on space characters as determined by
+.Xr isspace 3 . )
+The default
+.Ar denominator
+for this mode of operation is 1.0, which displays every line.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl e
+If the
+.Fl e
+option is specified,
+.Nm
+does not read or write anything, and simply exits with a random
+exit value of 0 to
+.Ar denominator
+\&- 1, inclusive.
+In this mode,
+.Ar denominator
+must be less than or equal to 256.
+.It Fl f Ar filename
+The
+.Fl f
+option is used to specify the
+.Ar filename
+to read from.
+Standard input is used if
+.Ar filename
+is
+.Sq - .
+.It Fl l
+Randomize the input via newlines (the default).
+.It Fl r
+Do not buffer output.
+.It Fl U
+Reuse any given line or word when creating a randomized output.
+.It Fl u
+Do not select the same line or word from a file more than once (the default).
+This does not guarantee uniqueness if there are two of the
+same tokens in the input.
+.It Fl w
+Randomize words separated by
+.Xr isspace 3
+instead of newlines.
+.El
+.Sh SEE ALSO
+.Xr fortune 6
+.Sh HISTORY
+The
+functionality to randomizing lines and words was added in 2003 by
+.An Sean Chittenden Aq Mt seanc@FreeBSD.org .
+.Sh BUGS
+This tool is a remnant of the "games" collection formerly part of
+.Fx
+base.
+It probably should have been removed to ports with the rest of that collection.
+It does not have a coherent purpose and the motivation for it to be a core base
+utility is nonobvious.
+.Pp
+No index is used when printing out tokens from the list which
+makes it rather slow for large files (10MB+).