=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
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:
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.]
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
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/;
=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
# 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
=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
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 ^ $$
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<$_>.
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
projects / p5sagit/p5-mst-13.2.git / blobdiff