=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
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.
-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.
+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.
+
+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
Any of the bit masks can also be undef. The timeout, if specified, is
in seconds, which may be fractional. Note: not all implementations are
-capable of returning the$timeleft. If not, they always return
+capable of returning the $timeleft. If not, they always return
$timeleft equal to the supplied $timeout.
You can effect a sleep of 250 milliseconds this way:
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 versions 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.
+program.
-Calling C<srand> multiple times is highly suspect.
+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>.
-=over 4
+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.
-=item *
+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. And you shouldn't use
-srand() at all unless you need backward compatibility with Perls older
-than 5.004.
-
-=item *
+srand() again actually I<loses> randomness.
-Do B<not> call srand($seed) (i.e. with an argument) multiple times in
-a script for any other purpose than calling it with the I<same>
-argument to produce the I<same> sequence out of rand() I<unless> you
-know exactly what you're doing and why you're doing it. Usually doing
-anything else than reusing the same seed requires intimate knowledge of
-the implementation of srand() and rand() on your platform.
-
-=back
+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
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