Revert change #33676, likely to break atan(-0,0) on some platforms

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 49eb729..6af9f8d 100644 (file)
--- 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<atan2(0,0)> is implementation-defined; consult
+your atan2(3) manpage for more information.
 
 =item bind SOCKET,NAME
 X<bind>
@@ -1625,6 +1626,22 @@ normally you I<would> 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<eval BLOCK> does I<not> count as a loop, so the loop control statements
 C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
 
@@ -2667,9 +2684,10 @@ X<length> X<size>
 =item length
 
 Returns the length in I<characters> 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<scalar @array> and C<scalar keys %hash> respectively.
+omitted, returns length of C<$_>.  If EXPR is undefined, returns C<undef>.
+Note that this cannot be used on an entire array or hash to find out how
+many elements these have. For that, use C<scalar @array> and C<scalar keys
+%hash> respectively.
 
 Note the I<characters>: if the EXPR is in Unicode, you will get the
 number of characters, not the number of bytes.  To get the length
@@ -2749,7 +2767,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<localtime()> uses the current time (C<localtime(time)>).
+If EXPR is omitted, C<localtime()> uses the current time (as returned
+by time(3)).
 
 In scalar context, C<localtime()> returns the ctime(3) value:
 
@@ -4060,12 +4079,6 @@ If the package name is null, the C<main> package as assumed.  That is,
 C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
 still seen in older code).
 
-If NAMESPACE is omitted, then there is no current package, and all
-identifiers must be fully qualified or lexicals.  However, you are
-strongly advised not to make use of this feature. Its use can cause
-unexpected behaviour, even crashing some versions of Perl. It is
-deprecated, and will be removed from a future release.
-
 See L<perlmod/"Packages"> for more information about packages, modules,
 and classes.  See L<perlsub> for other scoping issues.
 
@@ -5101,6 +5114,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<undef> if
+the first argument is not a valid filehandle, or returns C<0> and sets
+C<$!> for any other failure.
+
 =item sin EXPR
 X<sin> X<sine> X<asin> X<arcsine>
 
@@ -5600,8 +5617,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,
@@ -6873,22 +6890,16 @@ of perl older than the specified one.
 
 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 that do not support this syntax.  The equivalent numeric
-version should be used instead.
-
-Alternatively, you can use a numeric version C<use 5.006> followed by a
-v-string version like C<use v5.10.1>, to avoid the unintuitive C<use
-5.010_001>. (older perl versions fail gracefully at the first C<use>,
-later perl versions understand the v-string syntax in the second).
+versions of Perl (that is, prior to 5.6.0) that do not support this
+syntax.  The equivalent numeric version should be used instead.
 
     use v5.6.1;                # compile time version check
     use 5.6.1;         # ditto
     use 5.006_001;     # ditto; preferred for backwards compatibility
-    use 5.006; use 5.6.1;      # ditto, for compatibility and readability
 
 This is often useful if you need to check the current Perl version before
-C<use>ing library modules that have changed in incompatible ways from
-older versions of Perl.  (We try not to do this more than we have to.)
+C<use>ing library modules that won't work with older versions of Perl.
+(We try not to do this more than we have to.)
 
 Also, if the specified perl version is greater than or equal to 5.9.5,
 C<use VERSION> will also load the C<feature> pragma and enable all