From: Jarkko Hietaniemi <jhi@iki.fi>
Date: Fri, 15 Mar 2002 15:18:46 +0000 (+0000)
Subject: Be more explicit on when is the $! worth anything.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6ab308ee9dcbdd9e40dc1aa7ca450e7f854eb8fe;p=p5sagit%2Fp5-mst-13.2.git

Be more explicit on when is the $! worth anything.

p4raw-id: //depot/perl@15237
---

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 5d04e22..1e6350b 100644
--- 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