X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=86a09ba8dc45ab9b52c3f2160307d6cad2824aa9;hb=f1c09d8aea4b00e7799b7273c877df50e0fd657a;hp=68ca8d741c027defca554c51d2c5a98e5ffa15e8;hpb=2ac1ef3d129ac2446fc0d2ea08ecbbd4bd583ff4;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 68ca8d7..86a09ba 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -560,11 +560,12 @@ previous time C<caller> was called.
 
 =item chdir EXPR
 
-Changes the working directory to EXPR, if possible.  If EXPR is omitted,
+Changes the working directory to EXPR, if possible. If EXPR is omitted,
 changes to the directory specified by C<$ENV{HOME}>, if set; if not,
-changes to the directory specified by C<$ENV{LOGDIR}>.  If neither is
-set, C<chdir> does nothing.  It returns true upon success, false
-otherwise.  See the example under C<die>.
+changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
+variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
+neither is set, C<chdir> does nothing. It returns true upon success,
+false otherwise. See the example under C<die>.
 
 =item chmod LIST
 
@@ -806,17 +807,29 @@ extirpated as a potential munition).  This can prove useful for checking
 the password file for lousy passwords, amongst other things.  Only the
 guys wearing white hats should do this.
 
-Note that C<crypt> is intended to be a one-way function, much like breaking
-eggs to make an omelette.  There is no (known) corresponding decrypt
-function.  As a result, this function isn't all that useful for
+Note that C<crypt> is intended to be a one-way function, much like
+breaking eggs to make an omelette.  There is no (known) corresponding
+decrypt function (in other words, the crypt() is a one-way hash
+function).  As a result, this function isn't all that useful for
 cryptography.  (For that, see your nearby CPAN mirror.)
 
-When verifying an existing encrypted string you should use the encrypted
-text as the salt (like C<crypt($plain, $crypted) eq $crypted>).  This
-allows your code to work with the standard C<crypt> and with more
-exotic implementations.  When choosing a new salt create a random two
-character string whose characters come from the set C<[./0-9A-Za-z]>
-(like C<join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
+When verifying an existing encrypted string you should use the
+encrypted text as the salt (like C<crypt($plain, $crypted) eq
+$crypted>).  This allows your code to work with the standard C<crypt>
+and with more exotic implementations.  In other words, do not assume
+anything about the returned string itself, or how many bytes in
+the encrypted string matter.
+
+Traditionally the result is a string of 13 bytes: two first bytes of
+the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
+the first eight bytes of the encrypted string mattered, but
+alternative hashing schemes (like MD5), higher level security schemes
+(like C2), and implementations on non-UNIX platforms may produce
+different strings.
+
+When choosing a new salt create a random two character string whose
+characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
+'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
 
 Here's an example that makes sure that whoever runs this program knows
 their own password:
@@ -844,6 +857,11 @@ back.  Look at the F<by-module/Crypt> and F<by-module/PGP> directories
 on your favorite CPAN mirror for a slew of potentially useful
 modules.
 
+If using crypt() on an Unicode string (which potentially has
+characters with codepoints above 255), Perl tries to make sense of
+the situation by using only the low eight bits of the characters when
+calling crypt().
+
 =item dbmclose HASH
 
 [This function has been largely superseded by the C<untie> function.]
@@ -2116,7 +2134,8 @@ L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex 'aF';   # same
 
 Hex strings may only represent integers.  Strings that would cause
-integer overflow trigger a warning.
+integer overflow trigger a warning.  Leading whitespace is not stripped,
+unlike oct().
 
 =item import
 
@@ -2613,8 +2632,9 @@ See the L</use> function, which C<no> is the opposite of.
 Interprets EXPR as an octal string and returns the corresponding
 value.  (If EXPR happens to start off with C<0x>, interprets it as a
 hex string.  If EXPR starts off with C<0b>, it is interpreted as a
-binary string.)  The following will handle decimal, binary, octal, and
-hex in the standard Perl or C notation:
+binary string.  Leading whitespace is ignored in all three cases.)
+The following will handle decimal, binary, octal, and hex in the standard
+Perl or C notation:
 
     $val = oct($val) if $val =~ /^0/;
 
@@ -3736,19 +3756,23 @@ rename(2) manpage or equivalent system documentation for details.
 
 =item require
 
-Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.
+Demands a version of Perl specified by VERSION, or demands some semantics
+specified by EXPR or by C<$_> if EXPR is not supplied.
+
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION).  A fatal error is produced at run time if
+VERSION is greater than the version of the current Perl interpreter.
+Compare with L</use>, which can do a similar check at compile time.
 
-If a VERSION is specified as a literal of the form v5.6.1,
-demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
-at least as recent as that version, at run time.  (For compatibility
-with older versions of Perl, a numeric argument will also be interpreted
-as VERSION.)  Compare with L</use>, which can do a similar check at
-compile time.
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     require v5.6.1;	# run time version check
     require 5.6.1;	# ditto
-    require 5.005_03;	# float version allowed for compatibility
+    require 5.006_001;	# ditto; preferred for backwards compatibility
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
@@ -3858,6 +3882,9 @@ C<main>.)  Here is a typical code layout:
     # In the main program
     push @INC, new Foo(...);
 
+Note that these hooks are also permitted to set the %INC entry
+corresponding to the files they have loaded. See L<perlvar/%INC>.
+
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
@@ -4778,19 +4805,42 @@ 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.
+
+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.
+
+If srand() is not called explicitly, it is called implicitly at the
+first use of the C<rand> operator.  However, this was not the case in
+versions of Perl before 5.004, so if your script will run under older
+Perl versions, it should call C<srand>.
 
-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>.
+Most programs won't even call srand() at all, except those that
+need a cryptographically-strong starting point rather than the
+generally acceptable default, which is based on time of day,
+process ID, and memory allocation, or the F</dev/urandom> device,
+if available. 
+
+You can call srand($seed) with the same $seed to reproduce the
+I<same> sequence from rand(), but this is usually reserved for
+generating predictable results for testing or debugging.
+Otherwise, don't call srand() more than once in your program.
+
+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.
+
+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 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
@@ -4802,12 +4852,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 ^ $$
@@ -5420,9 +5464,8 @@ otherwise.
 Returns an uppercased version of EXPR.  This is the internal function
 implementing the C<\U> escape in double-quoted strings.  Respects
 current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
-and L<perlunicode>.  Under Unicode it uses the standard Unicode
-uppercase mappings.  (It does not attempt to do titlecase mapping on
-initial letters.  See C<ucfirst> for that.)
+and L<perlunicode>.  It does not attempt to do titlecase mapping on
+initial letters.  See C<ucfirst> for that.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -5605,18 +5648,21 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-VERSION, which can be specified as a literal of the form v5.6.1, demands
-that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
-as recent as that version.  (For compatibility with older versions of Perl,
-a numeric literal will also be interpreted as VERSION.)  If the version
-of the running Perl interpreter is less than VERSION, then an error
-message is printed and Perl exits immediately without attempting to
-parse the rest of the file.  Compare with L</require>, which can do a
-similar check at run time.
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION.  A fatal error is produced if VERSION is
+greater than the version of the current Perl interpreter; Perl will not
+attempt to parse the rest of the file.  Compare with L</require>, which can
+do a similar check at run time.
+
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     use v5.6.1;		# compile time version check
     use 5.6.1;		# ditto
-    use 5.005_03;	# float version allowed for compatibility
+    use 5.006_001;	# ditto; preferred for backwards compatibility
 
 This is often useful if you need to check the current Perl version before
 C<use>ing library modules that have changed in incompatible ways from