X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=08c406c0cdd787a52aa5f47380d255a1e810fc40;hb=c1effa61278e47c916466883d74905b04fedc388;hp=2f9a85c8f6bb83e36a32497ea36ac04aab0b98b8;hpb=95731d22654e3bfea37fa18440748a4fcd003948;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 2f9a85c..08c406c 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -525,7 +525,7 @@ like for example images. If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the file handle. -When LAYER is present using binmode on text file makes sense. +When LAYER is present using binmode on a text file makes sense. If LAYER is omitted or specified as C<:raw> the filehandle is made suitable for passing binary data. This includes turning off possible CRLF @@ -982,7 +982,7 @@ X X X X Creates a digest string exactly like the crypt(3) function in the C library (assuming that you actually have a version there that has not -been extirpated as a potential munitions). +been extirpated as a potential munition). crypt() is a one-way hash function. The PLAINTEXT and SALT is turned into a short string, called a digest, which is returned. The same @@ -1012,7 +1012,7 @@ digest 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 digest string mattered, but alternative +the first eight bytes of PLAINTEXT mattered. But alternative hashing schemes (like MD5), higher level security schemes (like C2), and implementations on non-UNIX platforms may produce different strings. @@ -1234,6 +1234,10 @@ lookup: delete $ref->[$x][$y][$index]; delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; +The C construct can also be used to localize the deletion +of array/hash elements to the current block. +See L. + =item die LIST X X X X X<$@> X @@ -1271,14 +1275,14 @@ produce, respectively See also exit(), warn(), and the Carp module. -If LIST is empty and C<$@> already contains a value (typically from a +If the output is empty and C<$@> already contains a value (typically from a previous eval) that value is reused after appending C<"\t...propagated">. This is useful for propagating exceptions: eval { ... }; die unless $@ =~ /Expected exception/; -If LIST is empty and C<$@> contains an object reference that has a +If the output is empty and C<$@> contains an object reference that has a C method, that method will be called with additional file and line number parameters. The return value replaces the value in C<$@>. i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> @@ -1549,7 +1553,8 @@ itself. See L for more on how the evaluation context can be determined. If there is a syntax error or runtime error, or a C statement is -executed, an undefined value is returned by C, and C<$@> is set to the +executed, C returns an undefined value in scalar context +or an empty list in list context, and C<$@> is set to the error message. If there was no error, C<$@> is guaranteed to be a null string. Beware that using C neither silences perl from printing warnings to STDERR, nor does it stuff the text of warning messages into C<$@>. @@ -1935,25 +1940,27 @@ perl. Here's a mailbox appender for BSD systems. - use Fcntl ':flock'; # import LOCK_* constants + use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants sub lock { - flock(MBOX,LOCK_EX); - # and, in case someone appended - # while we were waiting... - seek(MBOX, 0, 2); + my ($fh) = @_; + flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n"; + + # and, in case someone appended while we were waiting... + seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n"; } sub unlock { - flock(MBOX,LOCK_UN); + my ($fh) = @_; + flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n"; } open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}") or die "Can't open mailbox: $!"; - lock(); + lock($mbox); print $mbox $msg,"\n\n"; - unlock(); + unlock($mbox); On systems that support a real flock(), locks are inherited across fork() calls, whereas those that must resort to the more capricious fcntl() @@ -2114,7 +2121,7 @@ C. X X X Returns the current priority for a process, a process group, or a user. -(See L.) Will raise a fatal exception if used on a +(See C.) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2). =item getpwnam NAME @@ -2628,11 +2635,13 @@ the super-user). This is a useful way to check that a child process is alive (even if only as a zombie) and hasn't changed its UID. See L for notes on the portability of this construct. -Unlike in the shell, if SIGNAL is negative, it kills -process groups instead of processes. (On System V, a negative I -number will also kill process groups, but that's not portable.) That -means you usually want to use positive not negative signals. You may also -use a signal name in quotes. +Unlike in the shell, if SIGNAL is negative, it kills process groups instead +of processes. That means you usually want to use positive not negative signals. +You may also use a signal name in quotes. + +The behavior of kill when a I number is zero or negative depends on +the operating system. For example, on POSIX-conforming systems, zero will +signal the current process group and -1 will signal all processes. See L for more details. @@ -2731,6 +2740,10 @@ block, file, or eval. If more than one value is listed, the list must be placed in parentheses. See L for details, including issues with tied arrays and hashes. +The C construct can also be used to localize the deletion +of array/hash elements to the current block. +See L. + =item localtime EXPR X X @@ -2853,7 +2866,7 @@ If EXPR is omitted, stats C<$_>. =item m// -The match operator. See L. +The match operator. See L. =item map BLOCK LIST X @@ -3271,7 +3284,7 @@ See L for detailed info on PerlIO. You may also, in the Bourne shell tradition, specify an EXPR beginning with C<< '>&' >>, in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be -duped (as L) and opened. You may use C<&> after C<< > >>, +duped (as C) and opened. You may use C<&> after C<< > >>, C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents @@ -3302,7 +3315,7 @@ C using various methods: If you specify C<< '<&=X' >>, where C is a file descriptor number or a filehandle, then Perl will do an equivalent of C's C of -that file descriptor (and not call L); this is more +that file descriptor (and not call C); this is more parsimonious of file descriptors. For example: # open for input, reusing the fileno of $fd @@ -3415,7 +3428,7 @@ but will not work on a filename which happens to have a trailing space, while will have exactly the opposite restrictions. -If you want a "real" C C (see L on your system), then you +If you want a "real" C C (see C on your system), then you should use the C function, which involves no such magic (but may use subtly different filemodes than Perl open(), which is mapped to C fopen()). This is @@ -4070,8 +4083,6 @@ The same template may generally also be used in unpack(). =item package NAMESPACE X X X -=item package - Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block, file, or eval (the same as the C operator). @@ -4346,8 +4357,8 @@ steps to ensure that C was successful. for (;;) { undef $!; unless (defined( $line = <> )) { + last if eof; die $! if $!; - last; # reached EOF } # ... } @@ -4618,7 +4629,7 @@ A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per call, writing the line into C<$_> and returning 1, then returning 0 at "end of file". If there is a filehandle, then the subroutine will be -called to act a simple source filter, with the line as read in C<$_>. +called to act as a simple source filter, with the line as read in C<$_>. Again, return 1 for each valid line, and 0 after all lines have been returned. @@ -4672,7 +4683,7 @@ into package C
.) Here is a typical code layout: } # In the main program - push @INC, new Foo(...); + push @INC, Foo->new(...); Note that these hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See L. @@ -4774,7 +4785,7 @@ the C function of the L module. =item s/// -The substitution operator. See L. +The substitution operator. See L. =item say FILEHANDLE LIST X @@ -5271,7 +5282,7 @@ the original quicksort was faster. 5.8 has a sort pragma for limited control of the sort. Its rather blunt control of the underlying algorithm may not persist into future Perls, but the ability to characterize the input or output in implementation -independent ways quite probably will. See L. +independent ways quite probably will. See L. Examples: @@ -5362,9 +5373,26 @@ Examples: use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; +Warning: syntactical care is required when sorting the list returned from +a function. If you want to sort the list returned by the function call +C, you can use: + + @contact = sort { $a cmp $b } find_records @key; + @contact = sort +find_records(@key); + @contact = sort &find_records(@key); + @contact = sort(find_records(@key)); + +If instead you want to sort the array @key with the comparison routine +C then you can use: + + @contact = sort { find_records() } @key; + @contact = sort find_records(@key); + @contact = sort(find_records @key); + @contact = sort(find_records (@key)); + If you're using strict, you I declare $a and $b as lexicals. They are package globals. That means -if you're in the C
package and type +that if you're in the C
package and type @articles = sort {$b <=> $a} @files; @@ -5443,9 +5471,7 @@ Splits the string EXPR into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. (If all fields are empty, they are considered to be trailing.) -In scalar context, returns the number of fields found and splits into -the C<@_> array. Use of split in scalar context is deprecated, however, -because it clobbers your subroutine arguments. +In scalar context, returns the number of fields found. If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything @@ -5519,7 +5545,7 @@ produces the list value If you had the entire header of a normal Unix email message in $header, you could split it up into fields and their values this way: - $header =~ s/\n\s+/ /g; # fix continuation lines + $header =~ s/\n(?=\s)//g; # fix continuation lines %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header); The pattern C may be replaced with an expression to specify @@ -5558,7 +5584,7 @@ X Returns a string formatted by the usual C conventions of the C library function C. See below for more details -and see L or L on your system for an explanation of +and see C or C on your system for an explanation of the general principles. For example: @@ -6444,6 +6470,9 @@ C, as described in L. Return value of -1 indicates a failure to start the program or an error of the wait(2) system call (inspect $! for the reason). +If you'd like to make C (and many other bits of Perl) die on error, +have a look at the L pragma. + Like C, C allows you to lie to a program about its name if you use the C syntax. Again, see L. @@ -6456,8 +6485,8 @@ value. system(@args) == 0 or die "system @args failed: $?" -You can check all the failure possibilities by inspecting -C<$?> like this: +If you'd like to manually inspect C's failure, you can check all +possible failure modes by inspecting C<$?> like this: if ($? == -1) { print "failed to execute: $!\n"; @@ -6672,7 +6701,8 @@ Note that times for children are included only after they terminate. =item tr/// -The transliteration operator. Same as C. See L. +The transliteration operator. Same as C. See +L. =item truncate FILEHANDLE,LENGTH X @@ -6926,6 +6956,9 @@ Cing library modules that won't work with older versions of Perl. Also, if the specified perl version is greater than or equal to 5.9.5, C will also load the C pragma and enable all features available in the requested version. See L. +Similarly, if the specified perl version is greater than or equal to +5.11.0, strictures are enabled lexically as with C (except +that the F file is not actually loaded). The C forces the C and C to happen at compile time. The C makes sure the module is loaded into memory if it hasn't been @@ -7305,7 +7338,7 @@ X Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or C<-1> if there are no child processes. The status is returned in C<$?> -and C<{^CHILD_ERROR_NATIVE}>. +and C<${^CHILD_ERROR_NATIVE}>. Note that a return value of C<-1> could mean that child processes are being automatically reaped, as described in L. @@ -7315,7 +7348,7 @@ X Waits for a particular child process to terminate and returns the pid of the deceased process, or C<-1> if there is no such child process. On some systems, a value of 0 indicates that there are processes still running. -The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say +The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say use POSIX ":sys_wait_h"; #... @@ -7359,7 +7392,7 @@ Prints the value of LIST to STDERR. If the last element of LIST does not end in a newline, it appends the same file/line number text as C does. -If LIST is empty and C<$@> already contains a value (typically from a +If the output is empty and C<$@> already contains a value (typically from a previous eval) that value is used after appending C<"\t...caught"> to C<$@>. This is useful for staying almost, but not entirely similar to C. @@ -7430,6 +7463,7 @@ Note that write is I the opposite of C. Unfortunately. =item y/// -The transliteration operator. Same as C. See L. +The transliteration operator. Same as C. See +L. =back