Reorganize the srand entry.

p4raw-id: //depot/perl@11851

1 files changed, 42 insertions, 18 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 78a0cb2470..1626f6e3a2 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4778,24 +4778,54 @@ loaded the standard Math::Complex module.
 
 =item srand
 
-Sets the random number seed for the C<rand> operator.  If EXPR is
-omitted, uses a semi-random value supplied by the kernel (if it supports
-the F</dev/urandom> device) or based on the current time and process
-ID, among other things.  In versions of Perl prior to 5.004 the default
-seed was just the current C<time>.  This isn't a particularly good seed,
-so many old programs supply their own seed value (often C<time ^ $$> or
-C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
+Sets the random number seed for the C<rand> operator.
+
+It's usually not necessary to call C<srand> at all, because if it is
+not called explicitly, it is called implicitly at the first use of the
+C<rand> operator.  However, this was not the case in version of Perl
+before 5.004, so if your script will run under older Perl versions, it
+should call C<srand>.
+
+The point of the function is to "seed" the C<rand> function so that
+C<rand> can produce a different sequence each time you run your
+program.  Just do it B<once> at the top of your program, or you
+I<won't> get random numbers out of C<rand>!
+
+If EXPR is omitted, uses a semi-random value supplied by the kernel
+(if it supports the F</dev/urandom> device) or based on the current
+time and process ID, among other things.
 
 Most implementations of C<srand> take an integer and will silently
 truncate decimal numbers.  This means C<srand(42)> will usually
 produce the same results as C<srand(42.1)>.  To be safe, always pass
 C<srand> an integer.
 
-In fact, it's usually not necessary to call C<srand> at all, because if
-it is not called explicitly, it is called implicitly at the first use of
-the C<rand> operator.  However, this was not the case in version of Perl
-before 5.004, so if your script will run under older Perl versions, it
-should call C<srand>.
+Calling C<srand> multiple times is highly suspect.
+
+=over 4
+
+=item *
+
+Do B<not> call srand() (i.e. without an argument) more than once in a
+script.  The internal state of the random number generator should
+contain more entropy than can be provided by any seed, so calling
+srand() again actually I<loses> randomness.  And you shouldn't use
+srand() at all unless you need backward compatibility with Perls older
+than 5.004.
+
+=item *
+
+Do B<not> call srand($seed) (i.e. with an argument) multiple times in
+a script I<unless> you know exactly what you're doing and why you're
+doing it.  Usually this requires intimate knowledge of the
+implementation of srand() and rand() on your platform.
+
+=back
+
+In versions of Perl prior to 5.004 the default seed was just the
+current C<time>.  This isn't a particularly good seed, so many old
+programs supply their own seed value (often C<time ^ $$> or C<time ^
+($$ + ($$ << 15))>), but that isn't necessary any more.
 
 Note that you need something much more random than the default seed for
 cryptographic purposes.  Checksumming the compressed output of one or more
@@ -4807,12 +4837,6 @@ example:
 If you're particularly concerned with this, see the C<Math::TrulyRandom>
 module in CPAN.
 
-Do I<not> call C<srand> multiple times in your program unless you know
-exactly what you're doing and why you're doing it.  The point of the
-function is to "seed" the C<rand> function so that C<rand> can produce
-a different sequence each time you run your program.  Just do it once at the
-top of your program, or you I<won't> get random numbers out of C<rand>!
-
 Frequently called programs (like CGI scripts) that simply use
 
     time ^ $$