Document the changes with regards to running of END blocks.
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 17b4b1b..5a9eb4e 100644 (file)
@@ -72,7 +72,7 @@ Alternatively, you can import the subroutine (or pretend that it's
 imported with the C<use subs> pragma).
 
 To silently interpret it as the Perl operator, use the C<CORE::> prefix
-on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
+on the operator (e.g. C<CORE::log($x)>) or declare the subroutine
 to be an object method (see L<perlsub/"Subroutine Attributes"> or
 L<attributes>).
 
@@ -112,8 +112,8 @@ which 'splits' output into two streams, such as
 
 =item Applying %s to %s will act on scalar(%s)
 
-(W misc) The pattern match (//), substitution (s///), and
-transliteration (tr///) operators work on scalar values.  If you apply
+(W misc) The pattern match (C<//>), substitution (C<s///>), and
+transliteration (C<tr///>) operators work on scalar values.  If you apply
 one of them to an array or a hash, it will convert the array or hash to
 a scalar value -- the length of an array, or the population info of a
 hash -- and then work on that scalar value.  This is probably not what
@@ -184,7 +184,7 @@ know which context to supply to the right side.
 
 =item Negative offset to vec in lvalue context
 
-(F) When vec is called in an lvalue context, the second argument must be
+(F) When C<vec> is called in an lvalue context, the second argument must be
 greater than or equal to zero.
 
 =item Attempt to bless into a reference
@@ -270,7 +270,7 @@ S<sizeof(struct shmid_ds *)>.
 
 =item Bad evalled substitution pattern
 
-(F) You've used the /e switch to evaluate the replacement for a
+(F) You've used the C</e> switch to evaluate the replacement for a
 substitution, but perl found a syntax error in the code to evaluate,
 most likely an unexpected right brace '}'.
 
@@ -631,7 +631,7 @@ is no builtin with the name C<word>.
 =item Can't find %s character property "%s"
 
 (F) You used C<\p{}> or C<\P{}> but the character property by that name
-could not be find.  Maybe you mispelled the name of the property
+could not be found. Maybe you misspelled the name of the property
 (remember that the names of character properties consist only of
 alphanumeric characters), or maybe you forgot the C<Is> or C<In> prefix?
 
@@ -1106,16 +1106,6 @@ and so on) and not for Unicode characters, so Perl behaved as if you meant
 If you actually want to pack Unicode codepoints, use the C<"U"> format
 instead.
 
-=item chmod() mode argument is missing initial 0
-
-(W chmod) A novice will sometimes say
-
-    chmod 777, $filename
-
-not realizing that 777 will be interpreted as a decimal number,
-equivalent to 01411.  Octal constants are introduced with a leading 0 in
-Perl, as in C.
-
 =item close() on unopened filehandle %s
 
 (W unopened) You tried to close a filehandle that was never opened.
@@ -1448,7 +1438,9 @@ some time before now.  Check your control flow.  flock() operates on
 filehandles.  Are you attempting to call flock() on a dirhandle by the
 same name?
 
-=item Quantifier follows nothing in regex; marked by <-- HERE in m/%s/
+=item Quantifier follows nothing in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) You started a regular expression with a quantifier. Backslash it if you
 meant it literally. The <-- HERE shows in the regular expression about
@@ -1846,7 +1838,9 @@ instead on the filehandle.)
 values cannot be returned in subroutines used in lvalue context.  See
 L<perlsub/"Lvalue subroutines">.
 
-=item Lookbehind longer than %d not implemented in regex; marked by <-- HERE in m/%s/
+=item Lookbehind longer than %d not implemented in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) There is currently a limit on the length of string which lookbehind can
 handle. This restriction may be eased in a future release. The <-- HERE
@@ -1876,13 +1870,21 @@ Perl detected something that didn't comply with UTF-8 encoding rules.
 Perl thought it was reading UTF-16 encoded character data but while
 doing it Perl met a malformed Unicode surrogate.
 
-=item %s matches null string many times in regex; marked by <-- HERE in m/%s/
+=item %s matches null string many times in regex;
+
+marked by <-- HERE in m/%s/
 
 (W regexp) The pattern you've specified would be an infinite loop if the
 regular expression engine didn't specifically check for that.  The <-- HERE
 shows in the regular expression about where the problem was discovered.
 See L<perlre>.
 
+=item "%s" may clash with future reserved word
+
+(W) This warning may be due to running a perl5 script through a perl4
+interpreter, especially if the word that is being warned about is
+"use" or "my".
+
 =item % may only be used in unpack
 
 (F) You can't pack a string by supplying a checksum, because the
@@ -2435,6 +2437,12 @@ package-specific handler.  That name might have a meaning to Perl itself
 some day, even though it doesn't yet.  Perhaps you should use a
 mixed-case attribute name, instead.  See L<attributes>.
 
+=item Package '%s' not found (did you use the incorrect case?)
+
+(W misc) You included a package file via C<use>, but the package name
+did not match the file name. It's possible that you misspelled the
+package name.
+
 =item page overflow
 
 (W io) A single call to write() produced more lines than can fit on a
@@ -2691,7 +2699,9 @@ value of the environment variable PERLIO.
 process which isn't a subprocess of the current process.  While this is
 fine from VMS' perspective, it's probably not what you intended.
 
-=item POSIX syntax [%s] belongs inside character classes in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [%s] belongs inside character classes in regex;
+
+marked by <-- HERE in m/%s/
 
 (W unsafe) The character class constructs [: :], [= =], and [. .]  go
 I<inside> character classes, the [] are part of the construct, for example:
@@ -2700,7 +2710,9 @@ implemented; they are simply placeholders for future extensions and will
 cause fatal errors.  The <-- HERE shows in the regular expression about
 where the problem was discovered.  See L<perlre>.
 
-=item POSIX syntax [. .] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [. .] is reserved for future extensions in regex;
+
+marked by <-- HERE in m/%s/
 
 (F regexp) Within regular expression character classes ([]) the syntax
 beginning with "[." and ending with ".]" is reserved for future extensions.
@@ -2709,7 +2721,9 @@ expression character class, just quote the square brackets with the
 backslash: "\[." and ".\]".  The <-- HERE shows in the regular expression
 about where the problem was discovered.  See L<perlre>.
 
-=item POSIX syntax [= =] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [= =] is reserved for future extensions in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) Within regular expression character classes ([]) the syntax beginning
 with "[=" and ending with "=]" is reserved for future extensions.  If you
@@ -2718,7 +2732,9 @@ character class, just quote the square brackets with the backslash: "\[="
 and "=\]".  The <-- HERE shows in the regular expression about where the
 problem was discovered.  See L<perlre>.
 
-=item POSIX class [:%s:] unknown in regex; marked by <-- HERE in m/%s/
+=item POSIX class [:%s:] unknown in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) The class in the character class [: :] syntax is unknown.  The <-- HERE
 shows in the regular expression about where the problem was discovered.
@@ -2846,13 +2862,17 @@ in L<perlos2>.
 (S unsafe) The subroutine being declared or defined had previously been
 declared or defined with a different function prototype.
 
-=item Quantifier in {,} bigger than %d in regex; marked by <-- HERE in m/%s/
+=item Quantifier in {,} bigger than %d in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) There is currently a limit to the size of the min and max values of the
 {min,max} construct. The <-- HERE shows in the regular expression about where
 the problem was discovered. See L<perlre>.
 
-=item Quantifier unexpected on zero-length expression; marked by <-- HERE in m/%s/
+=item Quantifier unexpected on zero-length expression;
+
+marked by <-- HERE in m/%s/
 
 (W regexp) You applied a regular expression quantifier in a place where
 it makes no sense, such as on a zero-width assertion.  Try putting the
@@ -2923,7 +2943,9 @@ Doing so has no effect.
 (W internal) The internal sv_replace() function was handed a new SV with
 a reference count of other than 1.
 
-=item Reference to nonexistent group in regex; marked by <-- HERE in m/%s/
+=item Reference to nonexistent group in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) You used something like C<\7> in your regular expression, but there are
 not at least seven sets of capturing parentheses in the expression. If you
@@ -3053,26 +3075,34 @@ before now.  Check your control flow.
 shows in the regular expression about where the problem was discovered. See
 L<perlre>.
 
-=item Sequence (?{...}) not terminated or not {}-balanced in regex; marked by <-- HERE in m/%s/
+=item Sequence (?{...}) not terminated or not {}-balanced in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) If the contents of a (?{...}) clause contains braces, they must balance
 for Perl to properly detect the end of the clause. The <-- HERE shows in
 the regular expression about where the problem was discovered. See
 L<perlre>.
 
-=item Sequence (?%s...) not implemented in regex; marked by <-- HERE in m/%s/
+=item Sequence (?%s...) not implemented in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) A proposed regular expression extension has the character reserved but
 has not yet been written. The <-- HERE shows in the regular expression about
 where the problem was discovered. See L<perlre>.
 
-=item Sequence (?%s...) not recognized in regex; marked by <-- HERE in m/%s/
+=item Sequence (?%s...) not recognized in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) You used a regular expression extension that doesn't make sense.  The
 <-- HERE shows in the regular expression about where the problem was
 discovered.  See L<perlre>.
 
-=item Sequence (?#... not terminated in regex; marked by <-- HERE in m/%s/
+=item Sequence (?#... not terminated in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) A regular expression comment must be terminated by a closing
 parenthesis.  Embedded parentheses aren't allowed.  The <-- HERE shows in
@@ -3258,7 +3288,9 @@ assignment or as a subroutine argument for example).
 (F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but
 a version of the setuid emulator somehow got run anyway.
 
-=item Switch (?(condition)... contains too many branches in regex; marked by <-- HERE in m/%s/
+=item Switch (?(condition)... contains too many branches in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) A (?(condition)if-clause|else-clause) construct can have at most two
 branches (the if-clause and the else-clause). If you want one or both to
@@ -3270,7 +3302,9 @@ clustering parentheses:
 The <-- HERE shows in the regular expression about where the problem was
 discovered. See L<perlre>.
 
-=item Switch condition not recognized in regex; marked by <-- HERE in m/%s/
+=item Switch condition not recognized in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) If the argument to the (?(...)if-clause|else-clause) construct is a
 number, it can be only a number. The <-- HERE shows in the regular expression
@@ -3309,6 +3343,12 @@ questions>.
 of Perl.  Check the #! line, or manually feed your script into Perl
 yourself.
 
+=item syntax error in file %s at line %d, next 2 tokens "%s"
+
+(F) This error is likely to occur if you run a perl5 script through
+a perl4 interpreter, especially if the next 2 tokens are "use strict"
+or "my $var" or "our $var".
+
 =item %s syntax OK
 
 (F) The final summary message when a C<perl -c> succeeds.
@@ -3465,11 +3505,6 @@ certain type.  Arrays must be @NAME or C<@{EXPR}>.  Hashes must be
 %NAME or C<%{EXPR}>.  No implicit dereferencing is allowed--use the
 {EXPR} forms as an explicit dereference.  See L<perlref>.
 
-=item umask: argument is missing initial 0
-
-(W umask) A umask of 222 is incorrect.  It should be 0222, because octal
-literals always start with 0 in Perl, as in C.
-
 =item umask not implemented
 
 (F) Your machine doesn't implement the umask function and you tried to
@@ -3551,7 +3586,13 @@ representative, who probably put it there in the first place.
 (F) There are no byte-swapping functions for a machine with this byte
 order.
 
-=item Unknown switch condition (?(%.2s in regex; marked by <-- HERE in m/%s/
+=item Unknown "re" subpragma '%s' (known ones are: %s)
+
+You tried to use an unknown subpragma of the "re" pragma.
+
+=item Unknown switch condition (?(%.2s in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) The condition part of a (?(condition)if-clause|else-clause) construct
 is not known. The condition may be lookahead or lookbehind (the condition
@@ -3616,7 +3657,9 @@ script, a binary program, or a directory as a Perl program.
 recognized by Perl inside character classes.  The character was
 understood literally.
 
-=item Unrecognized escape \\%c passed through in regex; marked by <-- HERE in m/%s/
+=item Unrecognized escape \\%c passed through in regex;
+
+marked by <-- HERE in m/%s/
 
 (W regexp) You used a backslash-character combination which is not
 recognized by Perl. This combination appears in an interpolated variable or
@@ -3706,7 +3749,9 @@ earlier in the line, and you really meant a "less than".
 (W untie) A copy of the object returned from C<tie> (or C<tied>) was
 still valid when C<untie> was called.
 
-=item Useless (?%s) - use /%s modifier in regex; marked by <-- HERE in m/%s/
+=item Useless (?%s) - use /%s modifier in regex;
+
+marked by <-- HERE in m/%s/
 
 (W regexp) You have used an internal modifier such as (?o) that has no
 meaning unless applied to the entire regexp:
@@ -3720,7 +3765,9 @@ must be written as
 The <-- HERE shows in the regular expression about
 where the problem was discovered. See L<perlre>.
 
-=item Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in m/%s/
+=item Useless (?-%s) - don't use /%s modifier in regex;
+
+marked by <-- HERE in m/%s/
 
 (W regexp) You have used an internal modifier such as (?-o) that has no
 meaning unless removed from the entire regexp:
@@ -3827,6 +3874,13 @@ In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);>
 you should remove AutoLoader from @ISA and change C<use AutoLoader;> to
 C<use AutoLoader 'AUTOLOAD';>.
 
+=item Use of "package" with no arguments is deprecated
+
+(D deprecated) You used the C<package> keyword without specifying a package
+name. So no namespace is current at all. Using this can cause many
+otherwise reasonable constructs to fail in baffling ways. C<use strict;>
+instead.
+
 =item Use of %s in printf format not supported
 
 (F) You attempted to use a feature of printf that is accessible from
@@ -3886,16 +3940,17 @@ program.
 
 =item Using a hash as a reference is deprecated
 
-(D deprecated) You tried to use a hash as a reference, as in C<%foo->{"bar"}>
-or C<%$ref->{"hello"}.  Versions of perl <= 5.6.1 used to allow this syntax,
-but shouldn't have. It is now deprecated, and will be removed in a future
-version.
+(D deprecated) You tried to use a hash as a reference, as in
+C<< %foo->{"bar"} >> or C<< %$ref->{"hello"} >>.  Versions of perl <= 5.6.1 
+used to allow this syntax, but shouldn't have. It is now deprecated, and will 
+be removed in a future version.
 
 =item Using an array as a reference is deprecated
 
-(D deprecated) You tried to use an array as a reference, as in C<@foo->[23]>
-or C<@$ref->[99]>.  Versions of perl <= 5.6.1 used to allow this syntax, but
-shouldn't have. It is now deprecated, and will be removed in a future version.
+(D deprecated) You tried to use an array as a reference, as in
+C<< @foo->[23] >> or C<< @$ref->[99] >>.  Versions of perl <= 5.6.1 used to 
+allow this syntax, but shouldn't have. It is now deprecated, and will be 
+removed in a future version.
 
 =item Value of %s can be "0"; test with defined()
 
@@ -3977,7 +4032,9 @@ anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
 reference variables in outer subroutines are called or referenced, they
 are automatically rebound to the current values of such variables.
 
-=item Variable length lookbehind not implemented in regex; marked by <-- HERE in m/%s/
+=item Variable length lookbehind not implemented in regex;
+
+marked by <-- HERE in m/%s/
 
 (F) Lookbehind is allowed only for subexpressions whose length is fixed and
 known at compile time. The <-- HERE shows in the regular expression about
@@ -4058,8 +4115,8 @@ Use a filename instead.
 
 (F) And you probably never will, because you probably don't have the
 sources to your kernel, and your vendor probably doesn't give a rip
-about what you want.  Your best bet is to use the wrapsuid script in the
-eg directory to put a setuid C wrapper around your script.
+about what you want.  Your best bet is to put a setuid C wrapper around 
+your script.
 
 =item You need to quote "%s"