In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/a73bef781595e4d1d9c2ce5b4d4b0a845c7bfa44?hp=7f8d58fb0a9806bbceb2f22543b4599f3d791699>
- Log ----------------------------------------------------------------- commit a73bef781595e4d1d9c2ce5b4d4b0a845c7bfa44 Author: John P. Linderman <j...@research.att.com> Date: Wed May 25 08:36:27 2011 -0700 [perl #91614] Suggestion for improving documentation of $! 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. ----------------------------------------------------------------------- Summary of changes: pod/perlvar.pod | 33 ++++++++++++++++++--------------- 1 files changed, 18 insertions(+), 15 deletions(-) diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 3f1fddf..80aef04 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -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? -- Perl5 Master Repository