This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #93638] $ENV{LS_COLORS} causes miniperl glob failure
[perl5.git] / pod / perldiag.pod
index e1660fc..9ef46e4 100644 (file)
@@ -76,17 +76,6 @@ 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>).
 
-=item Ambiguous overloaded argument to %s resolved as %s
-
-(W ambiguous) You called C<keys>, C<values> or C<each> on an object that had
-overloading of C<%{}> or C<@{}> or both.  In such a case, the object is
-dereferenced according to its overloading, not its underlying reference type.
-The warning is issued when C<%{}> overloading exists on a blessed arrayref,
-when C<@{}> overloading exists on a blessed hashref, or when both overloadings
-are defined (in which case C<%{}> is used).  You can force the interpretation
-of the object by explicitly dereferencing it as an array or hash instead of
-passing the object itself to C<keys>, C<values> or C<each>.
-
 =item Ambiguous range in transliteration operator
 
 (F) You wrote something like C<tr/a-z-0//> which doesn't mean anything at
@@ -115,7 +104,7 @@ really meant to multiply a glob by the result of calling a function.
 (W ambiguous) You wrote something like C<@{foo}>, which might be
 asking for the variable C<@foo>, or it might be calling a function
 named foo, and dereferencing it as an array reference.  If you wanted
-the varable, you can just write C<@foo>.  If you wanted to call the
+the variable, you can just write C<@foo>.  If you wanted to call the
 function, write C<@{foo()}> ... or you could just not have a variable
 and a function with the same name, and save yourself a lot of trouble.
 
@@ -146,6 +135,18 @@ string C<"-foo">, or a call to the function C<foo>, negated.  If you meant
 the string, just write C<"-foo">.  If you meant the function call,
 write C<-foo()>.
 
+=item Ambiguous use of 's//le...' resolved as 's// le...'; Rewrite as 's//el' if you meant 'use locale rules and evaluate rhs as an expression'.  In Perl 5.16, it will be resolved the other way
+
+(W deprecated, ambiguous)  You wrote a pattern match with substitution
+immediately followed by "le".  In Perl 5.14 and earlier, this is
+resolved as meaning to take the result of the substitution, and see if
+it is stringwise less-than-or-equal-to what follows in the expression.
+Having the "le" immediately following a pattern is deprecated behavior,
+so in Perl 5.16, this expression will be resolved as meaning to do the
+pattern match using the rules of the current locale, and evaluate the
+rhs as an expression when doing the substitution.  In 5.14, if you want
+the latter interpretation, you can simply write "el" instead.
+
 =item '|' and '<' may not both be specified on command line
 
 (F) An error peculiar to VMS.  Perl does its own command line
@@ -237,6 +238,11 @@ spots.  This is now heavily deprecated.
 
 (P) A general assertion failed.  The file in question must be examined.
 
+=item Assigning non-zero to $[ is no longer possible
+
+(F) The special variable C<$[>, deprecated in older perls, is now a fixed
+zero value, because the feature that it used to control has been removed.
+
 =item Assignment to both a list and a scalar
 
 (F) If you assign to a conditional operator, the 2nd and 3rd arguments
@@ -444,7 +450,6 @@ wasn't a symbol table entry.
 (P) An internal request asked to add a dirhandle entry to something
 that wasn't a symbol table entry.
 
-
 =item Bad symbol for filehandle
 
 (P) An internal request asked to add a filehandle entry to something
@@ -780,9 +785,11 @@ nesting levels, the following is missing its final parenthesis:
 
     print q(The character '(' starts a side comment.);
 
-If you're getting this error from a here-document, you may have included
-unseen whitespace before or after your closing tag. A good programmer's
-editor will have a way to help you find these characters.
+If you're getting this error from a here-document, you may have
+included unseen whitespace before or after your closing tag or there
+may not be a linebreak after it.  A good programmer's editor will have
+a way to help you find these characters (or lack of characters).  See
+L<perlop> for the full details on here-documents.
 
 =item Can't find Unicode property definition "%s"
 
@@ -1448,7 +1455,6 @@ the character name specified in the C<\N{...}> escape.  Perhaps you
 forgot to load the corresponding C<charnames> pragma?
 See L<charnames>.
 
-
 =item Constant is not %s reference
 
 (F) A constant value (perhaps declared using the C<use constant> pragma)
@@ -1474,6 +1480,16 @@ workarounds.
 (F) The method which overloads "=" is buggy. See
 L<overload/Copy Constructor>.
 
+=item &CORE::%s cannot be called directly
+
+(F) You tried to call a subroutine in the C<CORE::> namespace
+with C<&foo> syntax or through a reference.  Most subroutines
+in this package cannot yet be called that way, but must be
+called as barewords.  Something like this will work:
+
+    BEGIN { *shove = \&CORE::push; }
+    shove @array, 1,2,3; # pushes on to @array
+
 =item CORE::%s is not a keyword
 
 (F) The CORE:: namespace is reserved for Perl keywords.
@@ -1516,9 +1532,26 @@ array is empty, just use C<if (@array) { # not empty }> for example.
 
 =item defined(%hash) is deprecated
 
-(D deprecated) defined() is not usually useful on hashes because it
-checks for an undefined I<scalar> value.  If you want to see if the hash
-is empty, just use C<if (%hash) { # not empty }> for example.
+(D deprecated) C<defined()> is not usually right on hashes and has been
+discouraged since 5.004.
+
+Although C<defined %hash> is false on a plain not-yet-used hash, it
+becomes true in several non-obvious circumstances, including iterators,
+weak references, stash names, even remaining true after C<undef %hash>.
+These things make C<defined %hash> fairly useless in practice.
+
+If a check for non-empty is what you wanted then just put it in boolean
+context (see L<perldata/Scalar values>):
+
+    if (%hash) {
+       # not empty
+    }
+
+If you had C<defined %Foo::Bar::QUUX> to check whether such a package
+variable exists then that's never really been reliable, and isn't
+a good way to enquire about the features of a package, or whether
+it's loaded, etc.
+
 
 =item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/
 
@@ -1946,14 +1979,14 @@ earlier in the line, and you really meant a "less than".
 
 (W overflow) You called C<gmtime> with a number that was larger than
 it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
+date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item gmtime(%f) too small
 
 (W overflow) You called C<gmtime> with a number that was smaller than
 it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
+date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item Got an error from DosAllocMem
@@ -1996,11 +2029,10 @@ Further error messages would likely be uninformative.
 (D syntax)
 
 You had a word that isn't a regex modifier immediately following a
-pattern without an intervening space or you used one of the regex
-modifiers ("a", "d", "l", and "u") that in 5.14 are disallowed as
-suffixes. In that case, use the infix form, like C</(?a:...)/>.  In the
-other case, add white space between the pattern and following word.
-As an example of the latter, the two constructs:
+pattern without an intervening space.  If you are trying to use the C</le>
+flags on a substitution, use C</el> instead.  Otherwise, add white space
+between the pattern and following word to eliminate the warning. As an
+example of the latter, the two constructs:
 
  $a =~ m/$foo/sand $bar
  $a =~ m/$foo/s and $bar
@@ -2042,6 +2074,11 @@ been used, and the correct charname handler is in scope.
 binary number.  Interpretation of the binary number stopped before the
 offending digit.
 
+=item Illegal character after '_' in prototype for %s : %s
+
+(W illegalproto) An illegal character was found in a prototype declaration.
+Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
+
 =item Illegal character \%o (carriage return)
 
 (F) Perl normally treats carriage returns in the program text as it
@@ -2177,6 +2214,13 @@ C<$ENV{ENV}>, C<$ENV{BASH_ENV}> or C<$ENV{TERM}> are derived from data
 supplied (or potentially supplied) by the user.  The script must set
 the path to a known value, using trustworthy data.  See L<perlsec>.
 
+=item Insecure user-defined property %s
+
+(F) Perl detected tainted data when trying to compile a regular
+expression that contains a call to a user-defined character property
+function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>.
+See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
+
 =item Integer overflow in format string for %s
 
 (F) The indexes and widths specified in the format string of C<printf()>
@@ -2437,14 +2481,14 @@ L<perlfunc/listen>.
 
 (W overflow) You called C<localtime> with a number that was larger
 than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
+wrong date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item localtime(%f) too small
 
 (W overflow) You called C<localtime> with a number that was smaller
 than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
+wrong date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item Lookbehind longer than %d not implemented in regex m/%s/
@@ -2467,19 +2511,18 @@ You may wish to switch to using L<Math::BigInt> explicitly.
 by that?  lstat() makes sense only on filenames.  (Perl did a fstat()
 instead on the filehandle.)
 
-=item lvalue attribute ignored after the subroutine has been defined
+=item lvalue attribute cannot be removed after the subroutine has been defined
 
-(W misc) Making a subroutine an lvalue subroutine after it has been defined
-by declaring the subroutine with an lvalue attribute is not
-possible. To make the subroutine an lvalue subroutine add the
-lvalue attribute to the definition, or put the declaration before
-the definition.
+(W misc) The lvalue attribute on a Perl subroutine cannot be turned off
+once the subroutine is defined.
 
-=item Lvalue subs returning %s not implemented yet
+=item lvalue attribute ignored after the subroutine has been defined
 
-(F) Due to limitations in the current implementation, array and hash
-values cannot be returned in subroutines used in lvalue context.  See
-L<perlsub/"Lvalue subroutines">.
+(W misc) Making a Perl subroutine an lvalue subroutine after it has been
+defined, whether by declaring the subroutine with an lvalue attribute
+or by using L<attributes.pm|attributes>, is not possible.  To make the subroutine an
+lvalue subroutine, add the lvalue attribute to the definition, or put
+the declaration before the definition.
 
 =item Malformed integer in [] in pack
 
@@ -3029,6 +3072,12 @@ find out what kind of ref it really was.  See L<perlref>.
 a reference to something else instead.  You can use the ref() function
 to find out what kind of ref it really was.  See L<perlref>.
 
+=item Not an unblessed ARRAY reference
+
+(F) You passed a reference to a blessed array to C<push>, C<shift> or
+another array function.  These only accept unblessed array references
+or arrays beginning explicitly with C<@>.
+
 =item Not a SCALAR reference
 
 (F) Perl was trying to evaluate a reference to a scalar value, but found
@@ -3364,13 +3413,6 @@ there are in the savestack.
 (P) Failed an internal consistency check while trying to reset a weak
 reference.
 
-=item panic: Devel::DProf inconsistent subroutine return
-
-(P) Devel::DProf called a subroutine that exited using goto(LABEL),
-last(LABEL) or next(LABEL). Leaving that way a subroutine called from
-an XSUB will lead very probably to a crash of the interpreter. This is
-a bug that will hopefully one day get fixed.
-
 =item panic: die %s
 
 (P) We popped the context stack to an eval context, and then discovered
@@ -3407,13 +3449,6 @@ repeatedly, but each time something re-created entries in the glob. Most
 likely the glob contains an object with a reference back to the glob and a
 destructor that adds a new object to the glob.
 
-=item panic: hfreeentries failed to free hash
-
-(P) The internal routine used to clear a hash's entries tried repeatedly,
-but each time something added more entries to the hash. Most likely the hash
-contains an object with a reference back to the hash and a destructor that
-adds a new object to the hash.
-
 =item panic: INTERPCASEMOD
 
 (P) The lexer got into a bad state at a case modifier.
@@ -3527,6 +3562,12 @@ scalar's string buffer.
 (P) The sv_insert() routine was told to remove more string than there
 was string.
 
+=item panic: strxfrm() gets absurd - a => %u, ab => %u
+
+(P) The interpreter's sanity check of the C function strxfrm() failed.
+In your current locale the returned transformation of the string "ab" is
+shorter than that of the string "a", which makes no sense.
+
 =item panic: top_env
 
 (P) The compiler attempted to do a goto, or something weird like that.
@@ -3588,6 +3629,15 @@ redirected it with select().)
 "Can't locate object method \"%s\" via package \"%s\"".  It often means
 that a method requires a package that has not been loaded.
 
+=item Perl folding rules are not up-to-date for 0x%x; please use the perlbug utility to report
+
+(W regex, deprecated) You used a regular expression with
+case-insensitive matching, and there is a bug in Perl in which the
+built-in regular expression folding rules are not accurate.  This may
+lead to incorrect results.  Please report this as a bug using the
+"perlbug" utility.  (This message is marked deprecated, so that it by
+default will be turned-on.)
+
 =item Perl_my_%s() not available
 
 (F) Your platform has very uncommon byte-order and integer size,
@@ -3984,6 +4034,26 @@ discovered.
 (P) The regular expression engine got confused by what the regular
 expression compiler gave it.
 
+=item Regexp modifier "/%c" may appear a maximum of twice
+
+=item Regexp modifier "/%c" may not appear twice
+
+(F syntax, regexp) The regular expression pattern had too many occurrences
+of the specified modifier.  Remove the extraneous ones.
+
+=item Regexp modifier "%c" may not appear after the "-"
+
+(F regexp) Turning off the given modifier has the side effect of turning
+on another one.  Perl currently doesn't allow this.  Reword the regular
+expression to use the modifier you want to turn on (and place it before
+the minus), instead of the one you want to turn off.
+
+=item Regexp modifiers "/%c" and "/%c" are mutually exclusive
+
+(F syntax, regexp) The regular expression pattern had more than one of these
+mutually exclusive modifiers.  Retain only the modifier that is
+supposed to be there.
+
 =item Regexp out of space
 
 (P) A "can't happen" error, because safemalloc() should have caught it
@@ -4125,9 +4195,7 @@ where the problem was discovered. See L<perlre>.
 <-- HERE shows in the regular expression about where the problem was
 discovered.  This happens when using the C<(?^...)> construct to tell
 Perl to use the default regular expression modifiers, and you
-redundantly specify a default modifier; or having a modifier that can't
-be turned off (such as C<"p"> or C<"l">) after a minus; or specifying
-more than one of the C<"d">, C<"l">, or C<"u"> modifiers.  For other
+redundantly specify a default modifier.  For other
 causes, see L<perlre>.
 
 =item Sequence \%s... not terminated in regex; marked by <-- HERE in m/%s/
@@ -4387,8 +4455,7 @@ before this, because Perl is good at understanding random input.
 Occasionally the line number may be misleading, and once in a blue moon
 the only way to figure out what's triggering the error is to call
 C<perl -c> repeatedly, chopping away half the program each time to see
-if the error went away.  Sort of the cybernetic version of S<20
-questions>.
+if the error went away.  Sort of the cybernetic version of S<20 questions>.
 
 =item syntax error at line %d: `%s' unexpected
 
@@ -4442,21 +4509,6 @@ a dirhandle.  Check your control flow.
 (W unopened) You tried to use the tell() function on a filehandle that
 was either never opened or has since been closed.
 
-=item That use of $[ is unsupported
-
-(F) Assignment to C<$[> is now strictly circumscribed, and interpreted
-as a compiler directive.  You may say only one of
-
-    $[ = 0;
-    $[ = 1;
-    ...
-    local $[ = 0;
-    local $[ = 1;
-    ...
-
-This is to prevent the problem of one module changing the array base out
-from under another module inadvertently.  See L<perlvar/$[>.
-
 =item The crypt() function is unimplemented due to excessive paranoia
 
 (F) Configure couldn't find the crypt() function on your machine,
@@ -4599,6 +4651,13 @@ disallowed. See L<Safe>.
 (F) Your machine doesn't implement a file truncation mechanism that
 Configure knows about.
 
+=item Type of arg %d to &CORE::%s must be %s
+
+(F) The subroutine in question in the CORE package requires its argument
+to be a hard reference to data of the specified type.  Overloading is
+ignored, so a reference to an object that is not the specified type, but
+nonetheless has overloading to handle it, will still not be accepted.
+
 =item Type of arg %d to %s must be %s (not %s)
 
 (F) This function requires the argument in that position to be of a
@@ -4606,10 +4665,10 @@ 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 Type of argument to %s must be hashref or arrayref
+=item Type of argument to %s must be unblessed hashref or arrayref
 
-(F) You called C<keys>, C<values> or C<each> with an argument that was
-expected to be a reference to a hash or a reference to an array.
+(F) You called C<keys>, C<values> or C<each> with a scalar argument that
+was not a reference to an unblessed hash or array.
 
 =item umask not implemented
 
@@ -4938,6 +4997,12 @@ See L<POSIX/FUNCTIONS> for more information.
 (F) You called a Win32 function with incorrect arguments.
 See L<Win32> for more information.
 
+=item Useless assignment to a temporary
+
+(W misc) You assigned to an lvalue subroutine, but what
+the subroutine returned was a temporary scalar about to
+be discarded, so the assignment had no effect.
+
 =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
@@ -5044,11 +5109,6 @@ you can write it as C<push(@tied_array,())> to avoid this warning.
 (F) The "use" keyword is recognized and executed at compile time, and
 returns no useful value.  See L<perlmod>.
 
-=item Use of assignment to $[ is deprecated
-
-(D deprecated) The C<$[> variable (index of the first element in an array)
-is deprecated. See L<perlvar/"$[">.
-
 =item Use of bare << to mean <<"" is deprecated
 
 (D deprecated) You are now encouraged to use the explicitly quoted
@@ -5254,14 +5314,6 @@ removed in a future version.
 Currently all but the first one are discarded when used in a regular
 expression pattern bracketed character class.
 
-=item Using just the first characters returned by \N{}
-
-(W) A charnames handler may return a sequence of characters.  There is a
-finite limit as to the number of characters that can be used, which this
-sequence exceeded.  In the message, the characters in the sequence are
-separated by dots, and each is shown by its ordinal in hex.  Anything to
-the left of the C<HERE> was retained; anything to the right was discarded.
-
 =item Using !~ with %s doesn't make sense
 
 (F) Using the C<!~> operator with C<s///r>, C<tr///r> or C<y///r> is
@@ -5269,15 +5321,6 @@ currently reserved for future use, as the exact behaviour has not
 been decided. (Simply returning the boolean opposite of the
 modified string is usually not particularly useful.)
 
-=item User-defined case-mapping '%s' is deprecated
-
-(W deprecated) You defined a function, such as C<ToLower> that overrides
-the standard case mapping, such as C<lc()> gives.  This feature is being
-deprecated due to its many issues, as documented in
-L<perlunicode/User-Defined Case Mappings (for serious hackers only)>.
-It is planned to remove this feature in Perl 5.16.  A CPAN module
-providing improved functionality is being prepared.
-
 =item UTF-16 surrogate U+%X
 
 (W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
@@ -5497,6 +5540,6 @@ Something Very Wrong.
 
 =head1 SEE ALSO
 
-L<warnings>, L<perllexwarn>.
+L<warnings>, L<perllexwarn>, L<diagnostics>.
 
 =cut