Revert #15200 for backwards compatiblity reasons.

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

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index ac4ebf8..1e6350b 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -673,9 +673,25 @@ see L<encode>.  An opaque C<Encode::XS> object.
 =item $!
 
 If used numerically, yields the current value of the C C<errno>
-variable, with all the usual caveats.  (This means that you shouldn't
-depend on the value of C<$!> to be anything in particular unless
-you've gotten a specific error return indicating a system error.)
+variable, or in other words, if a system or library call fails, it
+sets this variable.  This means that the value of C<$!> is meaningful
+only I<immediately> after a B<failure>:
+
+    if (open(FH, $filename)) {
+       # Here $! is meaningless.
+       ...
+    } else {
+       # ONLY here is $! meaningful.
+       ...
+       # Already here $! might be meaningless.
+    }
+    # Since here we might have either success or failure,
+    # here $! is meaningless.
+
+In the above I<meaningless> stands for anything: zero, non-zero,
+C<undef>.  A successful system or library call does B<not> set
+the variable to zero.
+
 If used an a string, yields the corresponding system error string.
 You can assign a number to C<$!> to set I<errno> if, for instance,
 you want C<"$!"> to return the string for error I<n>, or you want
@@ -1077,6 +1093,11 @@ Control.)  Example:
 
     warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
 
+To convert C<$^V> into its string representation use sprintf()'s
+C<"%vd"> conversion:
+
+    printf "version is v%vd\n", $^V;  # Perl's version
+
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.