X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=2169a4434e8e9363ff97b518cb86ab3b8ef6fe81;hb=a9320c62d9034275ce0ce1fa301011823fbbe2a4;hp=3e107c93faf55d47e07d699c09e4b6bab29a7693;hpb=9f5e10ca92116e50ba77fee2d7f4b85b0cfe80e9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 3e107c9..2169a44 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -492,8 +492,8 @@ function, or use the familiar relation: sub tan { sin($_[0]) / cos($_[0]) } -Note that atan2(0, 0) is not well-defined, however the Perl -implmentation returns C<0> for this value. +The return value for C is implementation-defined; consult +your atan2(3) manpage for more information. =item bind SOCKET,NAME X @@ -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. @@ -1549,7 +1549,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<$@>. @@ -1562,6 +1563,10 @@ determining whether a particular feature (such as C or C) is implemented. It is also Perl's exception trapping mechanism, where the die operator is used to raise exceptions. +If you want to trap errors when loading an XS module, some problems with +the binary interface (such as Perl version skew) may be fatal even with +C unless C<$ENV{PERL_DL_NONLAZY}> is set. See L. + If the code to be executed doesn't vary, you may use the eval-BLOCK form to trap run-time errors without incurring the penalty of recompiling each time. The error, if any, is still returned in C<$@>. @@ -1731,8 +1736,7 @@ X X Given an expression that specifies a hash element or array element, returns true if the specified element in the hash or array has ever -been initialized, even if the corresponding value is undefined. The -element is not autovivified if it doesn't exist. +been initialized, even if the corresponding value is undefined. print "Exists\n" if exists $hash{$key}; print "Defined\n" if defined $hash{$key}; @@ -1932,25 +1936,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() @@ -2111,7 +2117,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 @@ -2344,8 +2350,14 @@ implementing the C<< <*.c> >> operator, but you can use it directly. If EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in more detail in L. +Note that C will split its arguments on whitespace, treating +each segment as separate pattern. As such, C would +match all files with a F<.c> or F<.h> extension. The expression +C would match all files in the current working directory. + Beginning with v5.6.0, this operator is implemented using the standard -C extension. See L for details. +C extension. See L for details, including +C which does not treat whitespace as a pattern separator. =item gmtime EXPR X X X @@ -2844,7 +2856,7 @@ If EXPR is omitted, stats C<$_>. =item m// -The match operator. See L. +The match operator. See L. =item map BLOCK LIST X @@ -3262,7 +3274,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 @@ -3293,7 +3305,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 @@ -3406,7 +3418,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 @@ -4211,13 +4223,15 @@ the completed C. =item qq/STRING/ -=item qr/STRING/ - =item qx/STRING/ =item qw/STRING/ -Generalized quotes. See L. +Generalized quotes. See L. + +=item qr/STRING/ + +Regexp-like quote. See L. =item quotemeta EXPR X X @@ -4335,8 +4349,8 @@ steps to ensure that C was successful. for (;;) { undef $!; unless (defined( $line = <> )) { + last if eof; die $! if $!; - last; # reached EOF } # ... } @@ -4607,7 +4621,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. @@ -4661,7 +4675,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. @@ -4716,13 +4730,16 @@ of LIST in the opposite order. In scalar context, concatenates the elements of LIST and returns a string value with all characters in the opposite order. - print reverse <>; # line tac, last line first + print join(", ", reverse "world", "Hello"); # Hello, world - undef $/; # for efficiency of <> - print scalar reverse <>; # character tac, last line tsrif + print scalar reverse "dlrow ,", "olleH"; # Hello, world Used without arguments in scalar context, reverse() reverses C<$_>. + $_ = "dlrow ,olleH"; + print reverse; # No output, list context + print scalar reverse; # Hello, world + This operator is also handy for inverting a hash, although there are some caveats. If a value is duplicated in the original hash, only one of those can be represented as a key in the inverted hash. Also, this has to @@ -4760,7 +4777,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 @@ -5114,6 +5131,10 @@ It's also a more insistent form of close because it also disables the file descriptor in any forked copies in other processes. +Returns C<1> for success. In the case of error, returns C if +the first argument is not a valid filehandle, or returns C<0> and sets +C<$!> for any other failure. + =item sin EXPR X X X X @@ -5133,10 +5154,18 @@ X X =item sleep Causes the script to sleep for EXPR seconds, or forever if no EXPR. +Returns the number of seconds actually slept. + May be interrupted if the process receives a signal such as C. -Returns the number of seconds actually slept. You probably cannot -mix C and C calls, because C is often implemented -using C. + + eval { + local $SIG{ALARM} = sub { die "Alarm!\n" }; + sleep; + }; + die $@ unless $@ eq "Alarm!\n"; + +You probably cannot mix C and C calls, because C +is often implemented using C. On some older systems, it may sleep up to a full second less than what you requested, depending on how it counts seconds. Most modern systems @@ -5245,7 +5274,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: @@ -5336,6 +5365,24 @@ Examples: use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; + +Warning: Care is required when sorting the list returned from a function. + +If you want to sort returned by the function call: find_records(@key) then +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 +find_records 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 @@ -5441,7 +5488,7 @@ a null pattern C, which is just one member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example: - print join(':', split(/ */, 'hi there')); + print join(':', split(/ */, 'hi there')), "\n"; produces the output 'h:i:t:h:e:r:e'. @@ -5450,7 +5497,7 @@ matches only the null string, and is not be confused with the regular use of C to mean "the last successful pattern match". So, for C, the following: - print join(':', split(//, 'hi there')); + print join(':', split(//, 'hi there')), "\n"; produces the output 'h:i: :t:h:e:r:e'. @@ -5465,8 +5512,8 @@ hand, are produced when there is a match at the end of the string (and when LIMIT is given and is not 0), regardless of the length of the match. For example: - print join(':', split(//, 'hi there!', -1)); - print join(':', split(/\W/, 'hi there!', -1)); + print join(':', split(//, 'hi there!', -1)), "\n"; + print join(':', split(/\W/, 'hi there!', -1)), "\n"; produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively, both with an empty trailing field. @@ -5493,7 +5540,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 @@ -5532,7 +5579,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: @@ -6646,7 +6693,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 @@ -7279,7 +7327,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. @@ -7289,7 +7337,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"; #... @@ -7404,6 +7452,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