This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 2384afee9 / #123553
[perl5.git] / pod / perldiag.pod
index d9dd692..84577ae 100644 (file)
@@ -469,6 +469,11 @@ that wasn't a symbol table entry.
 (P) An internal request asked to add a hash entry to something that
 wasn't a symbol table entry.
 
+=item Bad symbol for scalar
+
+(P) An internal request asked to add a scalar entry to something that
+wasn't a symbol table entry.
+
 =item Bareword found in conditional
 
 (W bareword) The compiler found a bareword where it expected a
@@ -2728,13 +2733,6 @@ instead, except within S<C<(?[   ])>>, where it is a fatal error.
 The S<<-- HERE> shows whereabouts in the regular expression the
 escape was discovered.
 
-=item %s: Invalid handshake key got %p needed %p, binaries are mismatched
-
-(P) A dynamic loading library C<.so> or C<.dll> was being loaded into the
-process that was built against a different build of perl than the
-said library was compiled against.  Reinstalling the XS module will
-likely fix this error.
-
 =item Invalid hexadecimal number in \N{U+...}
 
 =item Invalid hexadecimal number in \N{U+...} in regex; marked by
@@ -2980,18 +2978,25 @@ L<perlfunc/listen>.
 form of C<open> does not support pipes, such as C<open($pipe, '|-', @args)>.
 Use the two-argument C<open($pipe, '|prog arg1 arg2...')> form instead.
 
+=item %s: loadable library and perl binaries are mismatched (got handshake key %p, needed %p)
+
+(P) A dynamic loading library C<.so> or C<.dll> was being loaded into the
+process that was built against a different build of perl than the
+said library was compiled against.  Reinstalling the XS module will
+likely fix this error.
+
 =item Locale '%s' may not work well.%s
 
-(W locale) The named locale that Perl is now trying to use is not fully
-compatible with Perl.  The second C<%s> gives a reason.
+(W locale) You are using the named locale, which is a non-UTF-8 one, and
+which Perl has determined is not fully compatible with Perl.  The second
+C<%s> gives a reason.
 
 By far the most common reason is that the locale has characters in it
 that are represented by more than one byte.  The only such locales that
 Perl can handle are the UTF-8 locales.  Most likely the specified locale
 is a non-UTF-8 one for an East Asian language such as Chinese or
 Japanese.  If the locale is a superset of ASCII, the ASCII portion of it
-may work in Perl.  Read on for problems when it isn't a superset of
-ASCII.
+may work in Perl.
 
 Some essentially obsolete locales that aren't supersets of ASCII, mainly
 those in ISO 646 or other 7-bit locales, such as ASMO 449, can also have
@@ -2999,6 +3004,18 @@ problems, depending on what portions of the ASCII character set get
 changed by the locale and are also used by the program.
 The warning message lists the determinable conflicting characters.
 
+Note that not all incompatibilities are found.
+
+If this happens to you, there's not much you can do except switch to use a
+different locale or use L<Encode> to translate from the locale into
+UTF-8; if that's impracticable, you have been warned that some things
+may break.
+
+This message is output once each time a bad locale is switched into
+within the scope of C<S<use locale>>, or on the first possibly-affected
+operation if the C<S<use locale>> inherits a bad one.  It is not raised
+for any operations from the L<POSIX> module.
+
 =item localtime(%f) failed
 
 (W overflow) You called C<localtime> with a number that it could not handle:
@@ -3307,6 +3324,8 @@ file-specification as an argument.  See L<perlfunc/require>.
 
 (F) Missing right brace in C<\x{...}>, C<\p{...}>, C<\P{...}>, or C<\N{...}>.
 
+=item Missing right brace on \N{}
+
 =item Missing right brace on \N{} or unescaped left brace after \N
 
 (F) C<\N> has two meanings.
@@ -3685,6 +3704,12 @@ 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 Non-finite repeat count does nothing
+
+(W numeric) You tried to execute the
+L<C<x>|perlop/Multiplicative Operators> repetition operator C<Inf> (or
+C<-Inf>) or C<NaN> times, which doesn't make sense.
+
 =item Non-hex character in regex; marked by S<<-- HERE> in m/%s/
 
 (F) In a regular expression, there was a non-hexadecimal character where
@@ -5219,6 +5244,11 @@ didn't think so.
 forget to check the return value of your socket() call?  See
 L<perlfunc/setsockopt>.
 
+=item Setting ${^ENCODING} is deprecated
+
+(D deprecated) You assigned a non-C<undef> value to C<${^ENCODING}>.
+This is deprecated; see C<L<perlvar/${^ENCODING}>> for details.
+
 =item Setting $/ to a reference to %s as a form of slurp is deprecated, treating as undef
 
 (D deprecated) You assigned a reference to a scalar to C<$/> where the
@@ -5442,6 +5472,25 @@ the scope or until all closure references to it are destroyed.
        eval "sub name { ... }";
     }
 
+=item Subroutine "%s" will not stay shared
+
+(W closure) An inner (nested) I<named> subroutine is referencing a "my"
+subroutine defined in an outer named subroutine.
+
+When the inner subroutine is called, it will see the value of the outer
+subroutine's lexical subroutine as it was before and during the *first*
+call to the outer subroutine; in this case, after the first call to the
+outer subroutine is complete, the inner and outer subroutines will no
+longer share a common value for the lexical subroutine.  In other words,
+it will no longer be shared.  This will especially make a difference
+if the lexical subroutines accesses lexical variables declared in its
+surrounding scope.
+
+This problem can usually be solved by making the inner subroutine
+anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
+reference lexical subroutines in outer subroutines are created, they
+are automatically rebound to the current values of such lexical subs.
+
 =item Substitution loop
 
 (P) The substitution was looping infinitely.  (Obviously, a substitution
@@ -6447,6 +6496,17 @@ since they are often used in statements like
 String constants that would normally evaluate to 0 or 1 are warned
 about.
 
+=item Unusual use of %s in void context
+
+(W void_unusual) Similar to the "Useless use of %s in void context"
+warning, but only turned on by the top-level "pedantic" warning
+category, used for e.g. C<grep> in void context, which may indicate a
+bug, but could also just be someone using C<grep> for its side-effects
+as a loop.
+
+Enabled as part of "extra" warnings, not in the "all" category. See
+L<warnings> for details
+
 =item Useless use of (?-p) in regex; marked by S<<-- HERE> in m/%s/
 
 (W regexp) The C<p> modifier cannot be turned off once set.  Trying to do
@@ -6915,6 +6975,20 @@ warning is to add C<no warnings 'utf8';> but that is often closer to
 cheating.  In general, you are supposed to explicitly mark the
 filehandle with an encoding, see L<open> and L<perlfunc/binmode>.
 
+=item Wide character (U+%X) in %s
+
+(W locale) While in a single-byte locale (I<i.e.>, a non-UTF-8
+one), a multi-byte character was encountered.   Perl considers this
+character to be the specified Unicode code point.  Combining non-UTF8
+locales and Unicode is dangerous.  Almost certainly some characters
+will have two different representations.  For example, in the ISO 8859-7
+(Greek) locale, the code point 0xC3 represents a Capital Gamma.  But so
+also does 0x393.  This will make string comparisons unreliable.
+
+You likely need to figure out how this multi-byte character got mixed up
+with your single-byte locale (or perhaps you thought you had a UTF-8
+locale, but Perl disagrees).
+
 =item Within []-length '%c' not allowed
 
 (F) The count in the (un)pack template may be replaced by C<[TEMPLATE]>