X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=65e019bf0641a962a2f624f9d86d776651854378;hb=3c20a832e0afaa3d5dac4e9889c4ce2f06a128c5;hp=ffaaa173709e30cc16ad3349f388f3f53bbddc5d;hpb=ad863579382841c61dc43ad0aa70b6073602d57e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index ffaaa17..65e019b 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -492,7 +492,8 @@ function, or use the familiar relation: sub tan { sin($_[0]) / cos($_[0]) } -Note that atan2(0, 0) is not well-defined. +The return value for C is implementation-defined; consult +your atan2(3) manpage for more information. =item bind SOCKET,NAME X @@ -524,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 @@ -1548,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<$@>. @@ -1561,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<$@>. @@ -1625,6 +1631,22 @@ normally you I like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. +The assignment to C<$@> occurs before restoration of localised variables, +which means a temporary is required if you want to mask some but not all +errors: + + # alter $@ on nefarious repugnancy only + { + my $e; + { + local $@; # protect existing $@ + eval { test_repugnancy() }; + # $@ =~ /nefarious/ and die $@; # DOES NOT WORK + $@ =~ /nefarious/ and $e = $@; + } + die $e if defined $e + } + C does I count as a loop, so the loop control statements C, C, or C cannot be used to leave or restart the block. @@ -1714,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}; @@ -1915,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() @@ -2327,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 @@ -2667,9 +2696,10 @@ X X =item length Returns the length in I of the value of EXPR. If EXPR is -omitted, returns length of C<$_>. Note that this cannot be used on -an entire array or hash to find out how many elements these have. -For that, use C and C respectively. +omitted, returns length of C<$_>. If EXPR is undefined, returns C. +Note that this cannot be used on an entire array or hash to find out how +many elements these have. For that, use C and C respectively. Note the I: if the EXPR is in Unicode, you will get the number of characters, not the number of bytes. To get the length @@ -2749,7 +2779,8 @@ Wednesday. C<$yday> is the day of the year, in the range C<0..364> C<$isdst> is true if the specified time occurs during Daylight Saving Time, false otherwise. -If EXPR is omitted, C uses the current time (C). +If EXPR is omitted, C uses the current time (as returned +by time(3)). In scalar context, C returns the ctime(3) value: @@ -2825,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 @@ -4192,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 @@ -4697,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 @@ -4741,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 @@ -5095,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 @@ -5114,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 @@ -5422,7 +5470,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'. @@ -5431,7 +5479,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'. @@ -5446,8 +5494,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. @@ -5474,7 +5522,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 @@ -5594,8 +5642,8 @@ to take the arguments out of order, e.g.: one or more of: - space prefix positive number with a space - + prefix positive number with a plus sign + space prefix non-negative number with a space + + prefix non-negative number with a plus sign - left-justify within the field 0 use zeros, not spaces, to right-justify # ensure the leading "0" for any octal, @@ -6627,7 +6675,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 @@ -7385,6 +7434,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