Reverse change #31978
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index e9d2326..1d2650f 100644 (file)
@@ -9,7 +9,7 @@ desperation):
 
     (W) A warning (optional).
     (D) A deprecation (optional).
-    (S) A severe warning (default).
+    (S) A severe warning (enabled by default).
     (F) A fatal error (trappable).
     (P) An internal error you should never see (trappable).
     (X) A very fatal error (nontrappable).
@@ -27,7 +27,7 @@ and B<-W> switches. Warnings may be captured by setting C<$SIG{__WARN__}>
 to a reference to a routine that will be called on each warning instead
 of printing it.  See L<perlvar>.
 
-Default warnings are always enabled unless they are explicitly disabled
+Severe warnings are always enabled, unless they are explicitly disabled
 with the C<warnings> pragma or the B<-X> switch.
 
 Trappable errors may be trapped using the eval operator.  See
@@ -282,6 +282,13 @@ invalid anytime, even before the end of the current statement.  Use
 literals or global values as arguments to the "p" pack() template to
 avoid this warning.
 
+=item Attempt to reload %s aborted.
+
+(F) You tried to load a file with C<use> or C<require> that failed to
+compile once already.  Perl will not try to compile this file again
+unless you delete its entry from %INC.  See L<perlfunc/require> and
+L<perlvar/%INC>.
+
 =item Attempt to set length of freed array
 
 (W) You tried to set the length of an array which has been freed.  You
@@ -493,6 +500,11 @@ then tried to access that symbol via conventional Perl syntax. The access
 triggers Perl to autovivify that typeglob, but it there is no legal conversion
 from that type of reference to a typeglob.
 
+=item Cannot copy to %s in %s
+
+(P) Perl detected an attempt to copy a value to an internal type that cannot
+be directly assigned not.
+
 =item Can only compress unsigned integers in pack
 
 (F) An argument to pack("w",...) was not an integer.  The BER compressed
@@ -601,13 +613,13 @@ quotas or other plumbing problems.
 =item Can't declare class for non-scalar %s in "%s"
 
 (F) Currently, only scalar variables can be declared with a specific
-class qualifier in a "my" or "our" declaration.  The semantics may be
+class qualifier in a "my", "our" or "state" declaration.  The semantics may be
 extended for other types of variables in future.
 
 =item Can't declare %s in "%s"
 
-(F) Only scalar, array, and hash variables may be declared as "my" or
-"our" variables.  They must have ordinary identifiers as names.
+(F) Only scalar, array, and hash variables may be declared as "my", "our" or
+"state" variables.  They must have ordinary identifiers as names.
 
 =item Can't do inplace edit: %s is not a regular file
 
@@ -825,6 +837,11 @@ usually double the curlies to get the same effect though, because the
 inner curlies will be considered a block that loops once.  See
 L<perlfunc/last>.
 
+=item Can't linearize anonymous symbol table
+
+(F) Perl tried to calculate the method resolution order (MRO) of a
+package, but failed because the package stash has no name.
+
 =item Can't load '%s' for module %s
 
 (F) The module you tried to load failed to load a dynamic extension. This
@@ -838,7 +855,7 @@ extensions.
 =item Can't localize lexical variable %s
 
 (F) You used local on a variable name that was previously declared as a
-lexical variable using "my".  This is not allowed.  If you want to
+lexical variable using "my" or "state".  This is not allowed.  If you want to
 localize a package variable of the same name, qualify it with the
 package name.
 
@@ -883,6 +900,13 @@ method, nor does any of its base classes.  See L<perlobj>.
 (W syntax) The @ISA array contained the name of another package that
 doesn't seem to exist.
 
+=item Can't locate package %s for the parents of %s
+
+(W syntax) You did not define (or require/use) the first package,
+which is named as a (possibly indirect) parent of the second by
+C<@ISA> inheritance.  Perl will treat this as if the undefined
+package had an empty C<@ISA>.
+
 =item Can't locate PerlIO%s
 
 (F) You tried to use in open() a PerlIO layer that does not exist,
@@ -1116,7 +1140,7 @@ allowed.  See L<perlfunc/pack>.
 (F) Only a simple scalar variable may be used as a loop variable on a
 foreach.
 
-=item Can't use global %s in "my"
+=item Can't use global %s in "%s"
 
 (F) You tried to declare a magical variable as a lexical variable.  This
 is not allowed, because the magic can be tied to only one location
@@ -1673,6 +1697,11 @@ you which section of the Perl source code is distressed.
 (F) Your machine apparently doesn't implement fcntl().  What is this, a
 PDP-11 or something?
 
+=item FETCHSIZE returned a negative value
+
+(F) A tied array claimed to have a negative number of elements, which
+is not possible.
+
 =item Field too wide in 'u' format in pack
 
 (W pack) Each line in an uuencoded string start with a length indicator
@@ -1782,10 +1811,10 @@ L<perlfunc/getsockopt>.
 
 =item Global symbol "%s" requires explicit package name
 
-(F) You've said "use strict vars", which indicates that all variables
-must either be lexically scoped (using "my"), declared beforehand using
-"our", or explicitly qualified to say which package the global variable
-is in (using "::").
+(F) You've said "use strict" or "use strict vars", which indicates 
+that all variables must either be lexically scoped (using "my" or "state"), 
+declared beforehand using "our", or explicitly qualified to say 
+which package the global variable is in (using "::").
 
 =item glob failed (%s)
 
@@ -1859,7 +1888,7 @@ of Perl are likely to eliminate these arbitrary limitations.
 
 =item Ignoring %s in character class in regex; marked by <-- HERE in m/%s/
 
-(W) Named unicode character escapes (\N{...}) may return multi-char
+(W) Named Unicode character escapes (\N{...}) may return multi-char
 or zero length sequences. When such an escape is used in a character class
 its behaviour is not well defined. Check that the correct escape has
 been used, and the correct charname handler is in scope.
@@ -1945,11 +1974,6 @@ name or CLI symbol definition when preparing to iterate over %ENV, and
 didn't see the expected delimiter between key and value, so the line was
 ignored.
 
-=item Impossible to activate assertion call
-
-(W assertions) You're calling an assertion function in a block that is
-not under the control of the C<assertions> pragma.
-
 =item (in cleanup) %s
 
 (W misc) This prefix usually indicates that a DESTROY() method raised
@@ -1961,6 +1985,12 @@ would otherwise result in the same message being repeated.
 Failure of user callbacks dispatched using the C<G_KEEPERR> flag could
 also result in this warning.  See L<perlcall/G_KEEPERR>.
 
+=item Inconsistent hierarchy during C3 merge of class '%s': merging failed on parent '%s'
+
+(F) The method resolution order (MRO) of the given class is not
+C3-consistent, and you have enabled the C3 MRO for this class.  See the C3
+documentation in L<mro> for more information.
+
 =item In EBCDIC the v-string components cannot exceed 2147483647
 
 (F) An error peculiar to EBCDIC.  Internally, v-strings are stored as
@@ -1976,6 +2006,13 @@ either consume text or fail.
 The <-- HERE shows in the regular expression about where the problem was
 discovered.
 
+=item Initialization of state variables in list context currently forbidden
+
+(F) Currently the implementation of "state" only permits the initialization
+of scalar variables in scalar context. Re-write C<state ($a) = 42> as
+C<state $a = 42> to change from list to scalar context. Constructions such
+as C<state (@a) = foo()> will be supported in a future perl release.
+
 =item Insecure dependency in %s
 
 (F) You tried to do something that the tainting mechanism didn't like.
@@ -2080,6 +2117,12 @@ The escape was replaced with REPLACEMENT CHARACTER (U+FFFD) instead.
 The <-- HERE shows in the regular expression about where the
 escape was discovered.
 
+=item Invalid mro name: '%s'
+
+(F) You tried to C<mro::set_mro("classname", "foo")>
+or C<use mro 'foo'>, where C<foo> is not a valid method resolution order (MRO).
+(Currently, the only valid ones are C<dfs> and C<c3>). See L<mro>.
+
 =item Invalid [] range "%s" in regex; marked by <-- HERE in m/%s/
 
 (F) The range specified in a character class had a minimum character
@@ -2148,13 +2191,13 @@ neither as a system call or an ioctl call (SIOCATMARK).
 
 =item $* is no longer supported
 
-(D deprecated) The special variable C<$*>, deprecated in older perls, has
+(S deprecated, syntax) The special variable C<$*>, deprecated in older perls, has
 been removed as of 5.9.0 and is no longer supported. You should use the
 C<//m> and C<//s> regexp modifiers instead.
 
 =item $# is no longer supported
 
-(D deprecated) The special variable C<$#>, deprecated in older perls, has
+(S deprecated, syntax) The special variable C<$#>, deprecated in older perls, has
 been removed as of 5.9.3 and is no longer supported. You should use the
 printf/sprintf functions instead.
 
@@ -2208,11 +2251,10 @@ an undefined value for the length. See L<perlfunc/pack>.
 to check the return value of your socket() call?  See
 L<perlfunc/listen>.
 
-=item Lookbehind longer than %d not implemented in regex; marked by <-- HERE in m/%s/
+=item Lookbehind longer than %d not implemented in regex 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
-shows in the regular expression about where the problem was discovered.
+handle. This restriction may be eased in a future release. 
 
 =item lstat() on filehandle %s
 
@@ -2259,12 +2301,19 @@ when the function is called.
 
 =item Malformed UTF-8 character (%s)
 
-(S utf8) (F) Perl detected something that didn't comply with UTF-8
-encoding rules.
+(S utf8) (F) Perl detected a string that didn't comply with UTF-8
+encoding rules, even though it had the UTF8 flag on.
 
-One possible cause is that you read in data that you thought to be in
-UTF-8 but it wasn't (it was for example legacy 8-bit data).  Another
-possibility is careless use of utf8::upgrade().
+One possible cause is that you set the UTF8 flag yourself for data that
+you thought to be in UTF-8 but it wasn't (it was for example legacy
+8-bit data). To guard against this, you can use Encode::decode_utf8.
+
+If you use the C<:encoding(UTF-8)> PerlIO layer for input, invalid byte
+sequences are handled gracefully, but if you use C<:utf8>, the flag is
+set without validating the data, possibly resulting in this error
+message.
+
+See also L<Encode/"Handling Malformed Data">.
 
 =item Malformed UTF-16 surrogate
 
@@ -2286,6 +2335,14 @@ rules and perl was unable to guess how to make more progress.
 (F) You tried to unpack something that didn't comply with UTF-8 encoding
 rules and perl was unable to guess how to make more progress.
 
+=item Maximal count of pending signals (%s) exceeded
+
+(F) Perl aborted due to a too important number of signals pending. This
+usually indicates that your operating system tried to deliver signals
+too fast (with a very high priority), starving the perl process from
+resources it would need to reach a point where it can process signals
+safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.)
+
 =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
@@ -2450,7 +2507,7 @@ See L<perlfunc/pack>.
 (F) Lexically scoped subroutines are not yet implemented.  Don't try
 that yet.
 
-=item "my" variable %s can't be in a package
+=item "%s" variable %s can't be in a package
 
 (F) Lexically scoped variables aren't in a package, so it doesn't make
 sense to try to declare one with a package qualifier on the front.  Use
@@ -2497,6 +2554,12 @@ C<??> appear to be nested quantifiers, but aren't.  See L<perlre>.
 (S internal) The symbol in question was declared but somehow went out of
 scope before it could possibly have been used.
 
+=item next::method/next::can/maybe::next::method cannot find enclosing method
+
+(F) C<next::method> needs to be called within the context of a
+real method in a real package, and it could not find such a context.
+See L<mro>.
+
 =item No %s allowed while running setuid
 
 (F) Certain operations are deemed to be too insecure for a setuid or
@@ -2573,6 +2636,13 @@ name of the file from which to read data for stdin.
 (F) The setuid emulator requires that scripts have a well-formed #! line
 even on machines that don't support the #! construct.
 
+=item No next::method '%s' found for %s
+
+(F) C<next::method> found no further instances of this method name
+in the remaining packages of the MRO of this class.  If you don't want
+it throwing an exception, use C<maybe::next::method>
+or C<next::can>. See L<mro>.
+
 =item "no" not allowed in expression
 
 (F) The "no" keyword is recognized and executed at compile time, and
@@ -2624,7 +2694,7 @@ package has restricted the set of allowed keys using the L<fields> pragma.
 
 =item No such class %s
 
-(F) You provided a class qualifier in a "my" or "our" declaration, but
+(F) You provided a class qualifier in a "my", "our" or "state" declaration, but
 this class doesn't exist at this point in your program.
 
 =item No such pipe open
@@ -2817,6 +2887,20 @@ that isn't open.  Check your control flow.  See also L<perlfunc/-X>.
 
 (S internal) An internal warning that the grammar is screwed up.
 
+=item Opening dirhandle %s also as a file
+
+(W io deprecated) You used open() to associate a filehandle to
+a symbol (glob or scalar) that already holds a dirhandle.
+Although legal, this idiom might render your code confusing
+and is deprecated.
+
+=item Opening filehandle %s also as a directory
+
+(W io deprecated) You used opendir() to associate a dirhandle to
+a symbol (glob or scalar) that already holds a filehandle.
+Although legal, this idiom might render your code confusing
+and is deprecated.
+
 =item Operation "%s": no method found, %s
 
 (F) An attempt was made to perform an overloaded operation for which no
@@ -3136,7 +3220,7 @@ when you meant
 
     my ($foo, $bar) = @_;
 
-Remember that "my", "our", and "local" bind tighter than comma.
+Remember that "my", "our", "local" and "state" bind tighter than comma.
 
 =item C<-p> destination: %s
 
@@ -3454,8 +3538,9 @@ which is why it's currently left out of your copy.
 
 =item Recursive inheritance detected in package '%s'
 
-(F) More than 100 levels of inheritance were used.  Probably indicates
-an unintended loop in your inheritance hierarchy.
+(F) While calculating the method resolution order (MRO) of a package, Perl
+believes it found an infinite loop in the C<@ISA> hierarchy.  This is a
+crude check that bails out after 100 levels of C<@ISA> depth.
 
 =item Recursive inheritance detected while looking for method %s
 
@@ -3485,6 +3570,13 @@ 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 invalid group 0
+
+(F) You used C<\g0> or similar in a regular expression. You may refer to
+capturing parentheses only with strictly positive integers (normal
+backreferences) or with stricly negative integers (relative
+backreferences), but using 0 does not make sense.
+
 =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
@@ -3495,6 +3587,15 @@ prepend a zero to make the number at least two digits: C<\07>
 The <-- HERE shows in the regular expression about where the problem was
 discovered.
 
+=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE in m/%s/
+
+(F) You used something like C<\g{-7}> in your regular expression, but there are
+not at least seven sets of closed capturing parentheses in the expression before
+where the C<\g{-7}> was located.
+
+The <-- HERE shows in the regular expression about where the problem was
+discovered.
+
 =item Reference to nonexistent named group in regex; marked by <-- HERE in m/%s/
 
 (F) You used something like C<\k'NAME'> or C<< \k<NAME> >> in your regular
@@ -3667,6 +3768,11 @@ where the problem was discovered. See L<perlre>.
 <-- HERE shows in the regular expression about where the problem was
 discovered.  See L<perlre>.
 
+=item Sequence \\%s... not terminated in regex; marked by <-- HERE in m/%s/
+
+(F) The regular expression expects a mandatory argument following the escape
+sequence and this has been omitted or incorrectly written.
+
 =item Sequence (?#... not terminated in regex; marked by <-- HERE in m/%s/
 
 (F) A regular expression comment must be terminated by a closing
@@ -3817,16 +3923,6 @@ L<perlfunc/splice>.
 iterate more times than there are characters of input, which is what
 happened.) See L<perlfunc/split>.
 
-=item State variable %s will be reinitialized
-
-(W misc) You're declaring a C<state> variable inside a list. The list
-assignment will be treated by perl as a regular assignment, which means
-that the C<state> variable will be reinitialized each time the statement
-is run. The solution to have it initialized only once is to write the
-assignment on its own line, as in:
-
-    state $var = 42;
-
 =item Statement unlikely to be reached
 
 (W exec) You did an exec() with some statement after it other than a
@@ -4328,11 +4424,11 @@ reserved word.  It's best to put such a word in quotes, or capitalize it
 somehow, or insert an underbar into it.  You might also declare it as a
 subroutine.
 
-=item Unrecognized character %s
+=item Unrecognized character %s in column %d
 
 (F) The Perl parser has no idea what to do with the specified character
-in your Perl script (or eval).  Perhaps you tried to run a compressed
-script, a binary program, or a directory as a Perl program.
+in your Perl script (or eval) at the specified column.  Perhaps you tried 
+to run a compressed script, a binary program, or a directory as a Perl program.
 
 =item Unrecognized escape \\%c in character class passed through in regex; marked by <-- HERE in m/%s/
 
@@ -4429,6 +4525,10 @@ the pattern with a C<)>. Fix the pattern and retry.
 (F) You used a pattern of the form C<(*VERB:ARG)> but did not terminate
 the pattern with a C<)>. Fix the pattern and retry.
 
+=item Unterminated \g{...} pattern in regex; marked by <-- HERE in m/%s/
+
+(F) You missed a close brace on a \g{..} pattern (group reference) in
+a regular expression. Fix the pattern and retry.
 
 =item Unterminated <> operator
 
@@ -4776,27 +4876,14 @@ something else of the same name (usually a subroutine) is exported by
 that module.  It usually means you put the wrong funny character on the
 front of your variable.
 
-=item Variable length lookbehind not implemented in regex; marked by <-- HERE in m/%s/
+=item Variable length lookbehind not implemented 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
-where the problem was discovered. See L<perlre>.
-
-=item Variable length character upgraded in print
-
-(W utf8) Perl met a variable length character that is not marked with
-Unicode in the output, but the output layer (like the C<:utf8> layer) does
-not expect that. (A variable length character is defined by having
-different memory representations between the native encoding (ISO-8859-1
-or single-byte EBCDIC) and perl's Unicode encoding (UTF-8 or UTF-EBCDIC).)
-Perl assumes any strings that are not marked as Unicode to be encoded in
-the native encoding, and implicitly converts (upgrades) them into perl's
-Unicode encoding on print. If you had intended to treat them as Unicode
-strings, you might have failed to cope with them properly.
+known at compile time.  See L<perlre>.
 
 =item "%s" variable %s masks earlier declaration in same %s
 
-(W misc) A "my" or "our" variable has been redeclared in the current
+(W misc) A "my", "our" or "state" variable has been redeclared in the current
 scope or statement, effectively eliminating all access to the previous
 instance.  This is almost always a typographical error.  Note that the
 earlier variable will still exist until the end of the scope or until
@@ -4859,7 +4946,7 @@ minimum version.
 =item Warning: something's wrong
 
 (W) You passed warn() an empty string (the equivalent of C<warn "">) or
-you called it with no args and C<$_> was empty.
+you called it with no args and C<$@> was empty.
 
 =item Warning: unable to close filehandle %s properly
 
@@ -4951,4 +5038,8 @@ Something Very Wrong.
 
 =back
 
+=head1 SEE ALSO
+
+L<warnings>, L<perllexwarn>.
+
 =cut