From b111f941e13bd627870f7e812b8be15b7fee4548 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 16 Oct 2022 21:35:47 -0700 Subject: [PATCH 05/10] =?UTF-8?q?*=20doc/lispref/numbers.texi:=20Improve?= =?UTF-8?q?=20=E2=80=98random=E2=80=99=20doc.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/lispref/numbers.texi | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index fdcda328d8..c1a1349d1a 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1238,6 +1238,9 @@ Random Numbers sequence of numbers. By default, Emacs initializes the random seed at startup, in such a way that the sequence of values of @code{random} (with overwhelming likelihood) differs in each Emacs run. +The random seed is typically initialized from system entropy; +however, on obsolescent platforms lacking entropy pools, +the seed is taken from less-random volatile data such as the current time. Sometimes you want the random number sequence to be repeatable. For example, when debugging a program whose behavior depends on the random @@ -1256,12 +1259,17 @@ Random Numbers any fixnum, i.e., any integer from @code{most-negative-fixnum} through @code{most-positive-fixnum} (@pxref{Integer Basics}). +If @var{limit} is a string, it means to choose a new seed based on the +string's contents. This causes later calls to @code{random} to return +a reproducible sequence of results. + If @var{limit} is @code{t}, it means to choose a new seed as if Emacs -were restarting, typically from the system entropy. On systems -lacking entropy pools, choose the seed from less-random volatile data -such as the current time. +were restarting. This causes later calls to @code{random} to return +an unpredictable sequence of results. -If @var{limit} is a string, it means to choose a new seed based on the -string's contents. +If you need a random nonce for cryptographic purposes, @code{(random +t)} is typically not the best approach, as it can adversely affect other +parts of your program that benefit from reproducible results, and it can +leave information about the nonce scattered about Emacs's internal state. @end defun -- 2.34.1