Reorganize the srand entry.

[perl5.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 78a0cb2..1626f6e 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4778,24 +4778,54 @@ loaded the standard Math::Complex module.
 
 =item srand
 
 
 =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.
 
 
 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
 
 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.
 
 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 ^ $$
 Frequently called programs (like CGI scripts) that simply use
 
     time ^ $$