This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #91614] Suggestion for improving documentation of $!
authorJohn P. Linderman <jpl@research.att.com>
Wed, 25 May 2011 15:36:27 +0000 (08:36 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Wed, 25 May 2011 15:36:27 +0000 (08:36 -0700)
While trying to understand a bug report at

http://www.perlmonks.org/?node_id=906466

I realized that the documentation for $! was not crystal clear.  For example

    If used numerically, yields the current value of the
    C C<errno> variable, or in other words,
    if a system or library call fails, it sets this variable.

That's not "in other words", these are totally different
concepts.  And it isn't clear whether this variable refers to
errno or $! (I assumed the latter, and was wrong, as Devel::Peek
demonstrated).  And $! cannot be undef, as asserted (later),
because errno always contains a value, however irrelevant.

pod/perlvar.pod

index 3f1fddf..80aef04 100644 (file)
@@ -1922,12 +1922,18 @@ This variable was added in Perl 5.10.
 =item $!
 X<$!> X<$ERRNO> X<$OS_ERROR>
 
-If used numerically, yields the current value of the C C<errno>
-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 my $fh, "<", $filename) {
+When referenced, C<$!> retrieves the current value
+of the C C<errno> integer variable.
+If C<$!> is assigned a numerical value, that value is stored in C<errno>.
+When referenced as a string, C<$!> yields the system error string
+corresponding to C<errno>.
+
+Many system or library calls set C<errno> if they fail,
+to indicate the cause of failure.  They usually do B<not>
+set C<errno> to zero if they succeed.  This means C<errno>,
+hence C<$!>, is meaningful only I<immediately> after a B<failure>:
+
+    if (open my $fh, "<", $filename) {
                # Here $! is meaningless.
                ...
     }
@@ -1937,16 +1943,13 @@ only I<immediately> after a B<failure>:
                # Already here $! might be meaningless.
     }
     # Since here we might have either success or failure,
-    # here $! is meaningless.
-
-The I<meaningless> stands for anything: zero, non-zero,
-C<undef>. A successful system or library call does B<not> set the
-variable to zero.
+    # $! is meaningless.
 
-If used as 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 to set
-the exit value for the C<die()> operator.
+Here, I<meaningless> means that C<$!> may be unrelated to the outcome
+of the C<open()> operator.  Assignment to C<$!> is similarly ephemeral.
+It can be used immediately before invoking the C<die()> operator,
+to set the exit value, or to inspect the system error string
+corresponding to error I<n>, or to restore C<$!> to a meaningful state.
 
 Mnemonic: What just went bang?