X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=7c69ff60282074f3d0799f70a8f8bd93c9f611c3;hb=a3bcc51ebd4e201d85a37d8410b7a375b8d94244;hp=3bc93d9743345e342274dd06bcd923cdff5cd464;hpb=ef8b303fa642d3551ce0bbad06f755d6571f1c0c;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 3bc93d9..7c69ff6 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -473,8 +473,8 @@ When LAYER is present using binmode on 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 translation and marking it as bytes (as opposed to Unicode characters). -Note that as despite what may be implied in I<"Programming Perl"> -(the Camel) or elsewhere C<:raw> is I the simply inverse of C<:crlf> +Note that, despite what may be implied in I<"Programming Perl"> (the +Camel) or elsewhere, C<:raw> is I the simply inverse of C<:crlf> -- other layers which would affect binary nature of the stream are I disabled. See L, L and the discussion about the PERLIO environment variable. @@ -728,9 +728,9 @@ 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 by default not encoded in Unicode for backward -compatibility reasons (but see L). +chr(0x263a) is a Unicode smiley face. Note that characters from 128 +to 255 (inclusive) are by default not encoded in UTF-8 Unicode for +backward compatibility reasons (but see L). If NUMBER is omitted, uses C<$_>. @@ -1654,6 +1654,18 @@ Note that C will produce a fatal error if used on a machine that doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) manpage to learn what functions are available on your system. +Here's an example of setting a filehandle named C to be +non-blocking at the system level. You'll have to negotiate C<$|> +on your own, though. + + use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); + + $flags = fcntl(REMOTE, F_GETFL, 0) + or die "Can't get flags for the socket: $!\n"; + + $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) + or die "Can't set flags for the socket: $!\n"; + =item fileno FILEHANDLE Returns the file descriptor for a filehandle, or undefined if the @@ -2286,21 +2298,9 @@ system: $retval = ioctl(...) || -1; printf "System returned %d\n", $retval; -The special string "C<0> but true" is exempt from B<-w> complaints +The special string C<"0 but true"> is exempt from B<-w> complaints about improper numeric conversions. -Here's an example of setting a filehandle named C to be -non-blocking at the system level. You'll have to negotiate C<$|> -on your own, though. - - use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); - - $flags = fcntl(REMOTE, F_GETFL, 0) - or die "Can't get flags for the socket: $!\n"; - - $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) - or die "Can't set flags for the socket: $!\n"; - =item join EXPR,LIST Joins the separate strings of LIST into a single string with fields @@ -2325,7 +2325,8 @@ Perl for security reasons (see L). As a side effect, calling keys() resets the HASH's internal iterator, -see L. +see L. (In particular, calling keys() in void context resets +the iterator with no other overhead.) Here is yet another way to print your environment: @@ -3533,12 +3534,13 @@ equal $foo). =item * -If the pattern begins with a C, the resulting string will be treated -as Unicode-encoded. You can force UTF8 encoding on in a string with an -initial C, and the bytes that follow will be interpreted as Unicode -characters. If you don't want this to happen, you can begin your pattern -with C (or anything else) to force Perl not to UTF8 encode your -string, and then follow this with a C somewhere in your pattern. +If the pattern begins with a C, the resulting string will be +treated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a +string with an initial C, and the bytes that follow will be +interpreted as Unicode characters. If you don't want this to happen, +you can begin your pattern with C (or anything else) to force Perl +not to UTF-8 encode your string, and then follow this with a C +somewhere in your pattern. =item * @@ -3986,7 +3988,8 @@ C work. =item ref -Returns a true value if EXPR is a reference, false otherwise. If EXPR +Returns a non-empty string if EXPR is a reference, the empty +string otherwise. If EXPR is not specified, C<$_> will be used. The value returned depends on the type of thing the reference is a reference to. Builtin types include: @@ -4052,32 +4055,42 @@ version should be used instead. 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 -essentially just a variety of C. Has semantics similar to the following -subroutine: +essentially just a variety of C. Has semantics similar to the +following subroutine: sub require { - my($filename) = @_; - return 1 if $INC{$filename}; - my($realfilename,$result); - ITER: { - foreach $prefix (@INC) { - $realfilename = "$prefix/$filename"; - if (-f $realfilename) { - $INC{$filename} = $realfilename; - $result = do $realfilename; - last ITER; - } - } - die "Can't find $filename in \@INC"; - } - delete $INC{$filename} if $@ || !$result; - die $@ if $@; - die "$filename did not return true value" unless $result; - return $result; + my ($filename) = @_; + if (exists $INC{$filename}) { + return 1 if $INC{$filename}; + die "Compilation failed in require"; + } + my ($realfilename,$result); + ITER: { + foreach $prefix (@INC) { + $realfilename = "$prefix/$filename"; + if (-f $realfilename) { + $INC{$filename} = $realfilename; + $result = do $realfilename; + last ITER; + } + } + die "Can't find $filename in \@INC"; + } + if ($@) { + $INC{$filename} = undef; + die $@; + } elsif (!$result) { + delete $INC{$filename}; + die "$filename did not return true value"; + } else { + return $result; + } } Note that the file will not be included twice under the same specified -name. The file must return true as the last statement to indicate +name. + +The file must return true as the last statement to indicate successful execution of any initialization code, so it's customary to end such a file with C<1;> unless you're sure it'll return true otherwise. But it's better just to put the C<1;>, in case you add more @@ -5744,9 +5757,17 @@ your program. You can check all the failure possibilities by inspecting C<$?> like this: - $exit_value = $? >> 8; - $signal_num = $? & 127; - $dumped_core = $? & 128; + if ($? == -1) { + print "failed to execute: $!\n"; + } + elsif ($? & 127) { + printf "child died with signal %d, %s coredump\n", + ($? & 127), ($? & 128) ? 'with' : 'without'; + } + else { + printf "child exited with value %d\n", $? >> 8; + } + or more portably by using the W*() calls of the POSIX extension; see L for more information. @@ -5850,6 +5871,7 @@ A class implementing a hash should have the following methods: EXISTS this, key FIRSTKEY this NEXTKEY this, lastkey + SCALAR this DESTROY this UNTIE this @@ -6242,12 +6264,8 @@ to the current time. For example, this code has the same effect as the Unix touch(1) command when the files I. #!/usr/bin/perl - $now = time; - utime $now, $now, @ARGV; - -B Under NFS, touch(1) uses the time of the NFS server, not -the time of the local machine. If there is a time synchronization -problem, the NFS server and local machine will have different times. + $atime = $mtime = time; + utime $atime, $mtime, @ARGV; Since perl 5.7.2, if the first two elements of the list are C, then the utime(2) function in the C library will be called with a null second @@ -6257,6 +6275,17 @@ above.) utime undef, undef, @ARGV; +Under NFS this will use the time of the NFS server, not the time of +the local machine. If there is a time synchronization problem, the +NFS server and local machine will have different times. The Unix +touch(1) command will in fact normally use this form instead of the +one shown in the first example. + +Note that only passing one of the first two elements as C will +be equivalent of passing it as 0 and will not have the same effect as +described when they are both C. This case will also trigger an +uninitialized warning. + =item values HASH Returns a list consisting of all the values of the named hash. @@ -6270,7 +6299,8 @@ function would produce on the same (unmodified) hash. Since Perl for security reasons (see L). As a side effect, calling values() resets the HASH's internal iterator, -see L. +see L. (In particular, calling values() in void context resets +the iterator with no other overhead.) Note that the values are not copied, which means modifying them will modify the contents of the hash: @@ -6314,10 +6344,10 @@ extend the string with sufficiently many zero bytes. It is an error to try to write off the beginning of the string (i.e. negative OFFSET). The string should not contain any character with the value > 255 (which -can only happen if you're using UTF8 encoding). If it does, it will be -treated as something which is not UTF8 encoded. When the C was +can only happen if you're using UTF-8 encoding). If it does, it will be +treated as something which is not UTF-8 encoded. When the C was assigned to, other parts of your program will also no longer consider the -string to be UTF8 encoded. In other words, if you do have such characters +string to be UTF-8 encoded. In other words, if you do have such characters in your string, vec() will operate on the actual byte string, and not the conceptual character string.