X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=86a09ba8dc45ab9b52c3f2160307d6cad2824aa9;hb=f1c09d8aea4b00e7799b7273c877df50e0fd657a;hp=56937f4ddfe97f3761e01c817850cac9941d12e8;hpb=ad0029c435199eaf70c06265f639c1af50f36906;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 56937f4..86a09ba 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -450,13 +450,12 @@ on systems where the run-time libraries distinguish between binary and text files. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. DISCIPLINE can be either of C<":raw"> for binary mode or C<":crlf"> for "text" mode. If the DISCIPLINE is -omitted, it defaults to C<":raw">. +omitted, it defaults to C<":raw">. Returns true on success, C on +failure. binmode() should be called after open() but before any I/O is done on the filehandle. -On many systems binmode() currently has no effect, but in future, it -will be extended to support user-defined input and output disciplines. On some systems binmode() is necessary when you're not working with a text file. For the sake of portability it is a good idea to always use it when appropriate, and to never use it when it isn't appropriate. @@ -561,11 +560,12 @@ previous time C 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 does nothing. It returns true upon success, false -otherwise. See the example under C. +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 does nothing. It returns true upon success, +false otherwise. See the example under C. =item chmod LIST @@ -807,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 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 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). This -allows your code to work with the standard C 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). +When verifying an existing encrypted string you should use the +encrypted text as the salt (like C). This allows your code to work with the standard C +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). Here's an example that makes sure that whoever runs this program knows their own password: @@ -845,6 +857,11 @@ back. Look at the F and F 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 function.] @@ -2117,7 +2134,8 @@ L.) 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 @@ -2614,8 +2632,9 @@ See the L function, which C 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/; @@ -3737,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. -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, 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, 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 @@ -3808,6 +3831,60 @@ will complain about not finding "F" there. In this case you can do: eval "require $class"; +You can also insert hooks into the import facility, by putting directly +Perl code into the @INC array. There are three forms of hooks: subroutine +references, array references and blessed objects. + +Subroutine references are the simplest case. When the inclusion system +walks through @INC and encounters a subroutine, this subroutine gets +called with two parameters, the first being a reference to itself, and the +second the name of the file to be included (e.g. "F"). The +subroutine should return C or a filehandle, from which the file to +include will be read. If C is returned, C will look at +the remaining elements of @INC. + +If the hook is an array reference, its first element must be a subroutine +reference. This subroutine is called as above, but the first parameter is +the array reference. This enables to pass indirectly some arguments to +the subroutine. + +In other words, you can write: + + push @INC, \&my_sub; + sub my_sub { + my ($coderef, $filename) = @_; # $coderef is \&my_sub + ... + } + +or: + + push @INC, [ \&my_sub, $x, $y, ... ]; + sub my_sub { + my ($arrayref, $filename) = @_; + # Retrieve $x, $y, ... + my @parameters = @$arrayref[1..$#$arrayref]; + ... + } + +If the hook is an object, it must provide an INC method, that will be +called as above, the first parameter being the object itself. (Note that +you must fully qualify the sub's name, as it is always forced into package +C
.) Here is a typical code layout: + + # In Foo.pm + package Foo; + sub new { ... } + sub Foo::INC { + my ($self, $filename) = @_; + ... + } + + # 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. + For a yet-more-powerful import facility, see L and L. =item reset EXPR @@ -4728,19 +4805,42 @@ loaded the standard Math::Complex module. =item srand -Sets the random number seed for the C operator. If EXPR is -omitted, uses a semi-random value supplied by the kernel (if it supports -the F 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