X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=174ff60f27eecf1de1601a9087d02cd3a32d4c40;hb=bbd5c0f5ad81733b079008f34cd05cd9aef7d917;hp=56937f4ddfe97f3761e01c817850cac9941d12e8;hpb=ad0029c435199eaf70c06265f639c1af50f36906;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 56937f4..174ff60 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -69,7 +69,7 @@ last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. -An named array in scalar context is quite different from what would at +A named array in scalar context is quite different from what would at first glance appear to be a list in scalar context. You can't get a list like C<(1,2,3)> into being in scalar context, because the compiler knows the context at compile time. It would generate the scalar comma operator @@ -291,7 +291,7 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> -g File has setgid bit set. -k File has sticky bit set. - -T File is an ASCII text file. + -T File is an ASCII text file (heuristic guess). -B File is a "binary" file (opposite of -T). -M Age of file in days when script started. @@ -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 @@ -682,12 +682,12 @@ On POSIX systems, you can detect this condition this way: Returns the character represented by that NUMBER in the character set. For example, C is C<"A"> in either ASCII or Unicode, and -chr(0x263a) is a Unicode smiley face. Note that characters from -127 to 255 (inclusive) are not encoded in Unicode for backward -compatibility reasons. +chr(0x263a) is a Unicode smiley face. Note that characters from 127 +to 255 (inclusive) are by default not encoded in Unicode for backward +compatibility reasons (but see L). For the reverse, use L. -See L for more about Unicode. +See L and L for more about Unicode. If NUMBER is omitted, uses C<$_>. @@ -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 a 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.] @@ -1987,7 +2004,7 @@ C extension. See L for details. =item gmtime EXPR -Converts a time as returned by the time function to a 8-element list +Converts a time as returned by the time function to an 8-element list with the time localized for the standard Greenwich time zone. Typically used as follows: @@ -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 @@ -2309,10 +2327,10 @@ C work. =item lc -Returns an lowercased version of EXPR. This is the internal function +Returns a lowercased version of EXPR. This is the internal function implementing the C<\L> escape in double-quoted strings. Respects current LC_CTYPE locale if C in force. See L -and L. +and L for more details about locale and Unicode support. If EXPR is omitted, uses C<$_>. @@ -2323,7 +2341,8 @@ If EXPR is omitted, uses C<$_>. Returns the value of EXPR with the first character lowercased. This is the internal function implementing the C<\l> escape in double-quoted strings. Respects current LC_CTYPE locale if C in force. See L and L. +locale> in force. See L and L for more +details about locale and Unicode support. If EXPR is omitted, uses C<$_>. @@ -2614,8 +2633,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/; @@ -2950,9 +2970,12 @@ DIRHANDLEs have their own namespace separate from FILEHANDLEs. =item ord -Returns the numeric (ASCII or Unicode) value of the first character of EXPR. If -EXPR is omitted, uses C<$_>. For the reverse, see L. -See L for more about Unicode. +Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC, +or Unicode) value of the first character of EXPR. If EXPR is omitted, +uses C<$_>. + +For the reverse, see L. +See L and L for more about Unicode. =item our EXPR @@ -3031,8 +3054,8 @@ sequence of characters that give the order and type of values, as follows: a A string with arbitrary binary data, will be null padded. - A An ASCII string, will be space padded. - Z A null terminated (asciz) string, will be null padded. + A A text (ASCII) string, will be space padded. + Z A null terminated (ASCIZ) string, will be null padded. b A bit string (ascending bit order inside each byte, like vec()). B A bit string (descending bit order inside each byte). @@ -3737,19 +3760,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, 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, 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 +3835,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 @@ -3844,7 +3925,7 @@ may vary from one execution to the next (see C). If no EXPR is given, returns an empty list in list context, the undefined value in scalar context, and (of course) nothing at all in a void context. -(Note that in the absence of a explicit C, a subroutine, eval, +(Note that in the absence of an explicit C, a subroutine, eval, or do FILE will automatically return the value of the last expression evaluated.) @@ -4034,7 +4115,7 @@ calling select() in scalar context just returns $nfound. 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: @@ -4728,19 +4809,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