This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Ignore a lvalue attribute after the subroutine has been defined, and warn about it...
[perl5.git] / pod / perldiag.pod
index 1dbb3e4..2b8d2c0 100644 (file)
@@ -8,7 +8,7 @@ These messages are classified as follows (listed in increasing order of
 desperation):
 
     (W) A warning (optional).
-    (D) A deprecation (optional).
+    (D) A deprecation (enabled by default).
     (S) A severe warning (enabled by default).
     (F) A fatal error (trappable).
     (P) An internal error you should never see (trappable).
@@ -316,11 +316,11 @@ release of Perl 5.
 =item Attribute "unique" is deprecated
 
 (D deprecated) You have used the attributes pragam to modify the "unique"
-attribute on a array, hash or scalar reference. The :unique attribute is has
-had no no effect since Perl 5.8.8, and will be removed in the next major
+attribute on an array, hash or scalar reference. The :unique attribute has
+had no effect since Perl 5.8.8, and will be removed in the next major
 release of Perl 5.
 
-=item Bad arg length for %s, is %d, should be %s
+=item Bad arg length for %s, is %d, should be %d
 
 (F) You passed a buffer of the wrong size to one of msgctl(), semctl()
 or shmctl().  In C parlance, the correct sizes are, respectively,
@@ -373,6 +373,11 @@ is not the same as
     $var = 'myvar';
     $sym = "mypack::$var";
 
+=item Bad plugin affecting keyword '%s'
+
+(F) An extension using the keyword plugin mechanism violated the
+plugin API.
+
 =item Bad realloc() ignored
 
 (S malloc) An internal routine called realloc() on something that had
@@ -712,9 +717,9 @@ 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 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?
+could not be found. Maybe you misspelled the name of the property?
+See L<perluniprops/Properties accessible through \p{} and \P{}>
+for a complete list of available properties.
 
 =item Can't find label %s
 
@@ -747,8 +752,10 @@ editor will have a way to help you find these characters.
 =item Can't find Unicode property definition "%s"
 
 (F) You may have tried to use C<\p> which means a Unicode property (for
-example C<\p{Lu}> is all uppercase letters).  If you did mean to use a
-Unicode property, see L<perlunicode> for the list of known properties.
+example C<\p{Lu}> matches all uppercase letters).  If you did mean to use a
+Unicode property, see
+L<perluniprops/Properties accessible through \p{} and \P{}>
+for a complete list of available properties.
 If you didn't mean to use a Unicode property, escape the C<\p>, either
 by C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, until
 possible C<\E>).
@@ -830,6 +837,12 @@ processes, Perl has reset the signal to its default value.  This
 situation typically indicates that the parent program under which Perl
 may be running (e.g. cron) is being very careless.
 
+=item Can't kill a non-numeric process ID
+
+(F) Process identifiers must be (signed) integers.  It is a fatal error to
+attempt to kill() an undefined, empty-string or otherwise non-numeric
+process identifier.
+
 =item Can't "last" outside a loop block
 
 (F) A "last" statement was executed to break out of the current block,
@@ -1032,7 +1045,7 @@ probably because you don't have write permission to the directory.
 (P) An error peculiar to VMS.  Perl thought stdin was a pipe, and tried
 to reopen it to accept binary data.  Alas, it failed.
 
-=item Can't resolve method `%s' overloading `%s' in package `%s'
+=item Can't resolve method "%s" overloading "%s" in package "%s"
 
 (F|P) Error resolving overloading specified by a method name (as opposed
 to a subroutine reference): no such method callable via the package. If
@@ -1141,6 +1154,11 @@ that is already inside a group with a byte-order modifier.
 For example you cannot force little-endianness on a type that
 is inside a big-endian group.
 
+=item Can't use keyword '%s' as a label
+
+(F) You attempted to use a reserved keyword, such as C<print> or C<BEGIN>,
+as a statement label. This is disallowed since Perl 5.11.0.
+
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
@@ -1408,6 +1426,9 @@ L<perlfunc/pack>.
 infinite recursion, unless you're writing strange benchmark programs, in
 which case it indicates something else.
 
+This threshold can be changed from 100, by recompiling the F<perl> binary,
+setting the C pre-processor macro C<PERL_SUB_DEPTH_WARN> to the desired value.
+
 =item defined(@array) is deprecated
 
 (D deprecated) defined() is not usually useful on arrays because it
@@ -1615,7 +1636,7 @@ variable and glob that.
 
 (F) The C<exec> function is not implemented in MacPerl. See L<perlport>.
 
-=item Execution of %s aborted due to compilation errors
+=item Execution of %s aborted due to compilation errors.
 
 (F) The final summary message when a Perl compilation fails.
 
@@ -1823,6 +1844,12 @@ a term, so it's looking for the corresponding right angle bracket, and
 not finding it.  Chances are you left some needed parentheses out
 earlier in the line, and you really meant a "less than".
 
+=item gmtime(%.0f) too large
+
+(W overflow) You called C<gmtime> with an number that was beyond the 64-bit
+range that it accepts, and some rounding resulted. This warning is also
+triggered with nan (the special not-a-number value).
+
 =item Got an error from DosAllocMem
 
 (P) An error peculiar to OS/2.  Most probably you're using an obsolete
@@ -1839,7 +1866,7 @@ unspecified destination.  See L<perlfunc/goto>.
 supposed to follow something: a template character or a ()-group.
  See L<perlfunc/pack>.
 
-=item %s had compilation errors
+=item %s had compilation errors.
 
 (F) The final summary message when a C<perl -c> fails.
 
@@ -1899,8 +1926,8 @@ to your Perl administrator.
 
 =item Illegal character in prototype for %s : %s
 
-(W syntax) An illegal character was found in a prototype declaration.  Legal
-characters in prototypes are $, @, %, *, ;, [, ], &, and \.
+(W illegalproto) An illegal character was found in a prototype declaration.
+Legal characters in prototypes are $, @, %, *, ;, [, ], &, and \.
 
 =item Illegal declaration of anonymous subroutine
 
@@ -1942,7 +1969,7 @@ two from 1 to 32 (or 64, if your platform supports that).
 (W digit) You may have tried to use an 8 or 9 in an octal number.
 Interpretation of the octal number stopped before the 8 or 9.
 
-=item Illegal switch in PERL5OPT: %s
+=item Illegal switch in PERL5OPT: -%c
 
 (X) The PERL5OPT environment variable may only be used to set the
 following switches: B<-[CDIMUdmtw]>.
@@ -2164,7 +2191,7 @@ strange for a machine that supports C.
 (W unopened) You tried ioctl() on a filehandle that was never opened.
 Check you control flow and number of arguments.
 
-=item IO layers (like "%s") unavailable
+=item IO layers (like '%s') unavailable
 
 (F) Your Perl has not been configured to have PerlIO, and therefore
 you cannot use IO layers.  To have PerlIO Perl must be configured
@@ -2177,13 +2204,17 @@ neither as a system call or an ioctl call (SIOCATMARK).
 
 =item $* is no longer supported
 
-(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.
+(D deprecated, syntax) The special variable C<$*>, deprecated in older perls, has
+been removed as of 5.9.0 and is no longer supported. In previous versions of perl the use of
+C<$*> enabled or disabled multi-line matching within a string.
+
+Instead of using C<$*> you should use the C</m> (and maybe C</s>) regexp
+modifiers. (In older versions: when C<$*> was set to a true value then all regular
+expressions behaved as if they were written using C</m>.)
 
 =item $# is no longer supported
 
-(S deprecated, syntax) The special variable C<$#>, deprecated in older perls, has
+(D 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.
 
@@ -2231,12 +2262,31 @@ effective uids or gids failed.
 length/code combination tried to obtain more data. This results in
 an undefined value for the length. See L<perlfunc/pack>.
 
+=item Lexing code attempted to stuff non-Latin-1 character into Latin-1 input
+
+(F) An extension is attempting to insert text into the current parse
+(using L<lex_stuff_pvn_flags|perlapi/lex_stuff_pvn_flags> or similar), but
+tried to insert a character that couldn't be part of the current input.
+This is an inherent pitfall of the stuffing mechanism, and one of the
+reasons to avoid it.  Where it is necessary to stuff, stuffing only
+plain ASCII is recommended.
+
+=item Lexing code internal error (%s)
+
+(F) Lexing code supplied by an extension violated the lexer's API in a
+detectable way.
+
 =item listen() on closed socket %s
 
 (W closed) You tried to do a listen on a closed socket.  Did you forget
 to check the return value of your socket() call?  See
 L<perlfunc/listen>.
 
+=item localtime(%.0f) too large
+
+(W overflow) You called C<localtime> with an number that was beyond the
+64-bit range that it accepts, and some rounding resulted. This warning is also triggered with nan (the special not-a-number value).
+
 =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
@@ -2257,6 +2307,14 @@ 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
+
+(W) Making a subroutine an lvalue subroutine after it has been defined
+by declaring the subroutine with a lvalue attribute is not
+possible. To make the the subroutine a lvalue subroutine add the
+lvalue attribute to the definition, or put the the declaration before
+the definition.
+
 =item Lvalue subs returning %s not implemented yet
 
 (F) Due to limitations in the current implementation, array and hash
@@ -2312,7 +2370,7 @@ See also L<Encode/"Handling Malformed Data">.
 
 =item Malformed UTF-16 surrogate
 
-Perl thought it was reading UTF-16 encoded character data but while
+(F) Perl thought it was reading UTF-16 encoded character data but while
 doing it Perl met a malformed Unicode surrogate.
 
 =item Malformed UTF-8 string in pack
@@ -2330,9 +2388,9 @@ 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
+=item Maximal count of pending signals (%d) exceeded
 
-(F) Perl aborted due to a too important number of signals pending. This
+(F) Perl aborted due to a too high 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
@@ -2377,6 +2435,11 @@ ended earlier on the current line.
 (W syntax) An underscore (underbar) in a numeric constant did not
 separate two digits.
 
+=item Missing argument in %s
+
+(W uninitialized) A printf-type format required more arguments than were
+supplied.
+
 =item Missing argument to -%c
 
 (F) The argument to the indicated command line switch must follow
@@ -2421,7 +2484,7 @@ can vary from one line to the next.
 
 =item Missing right brace on %s
 
-(F) Missing right brace in C<\p{...}> or C<\P{...}>.
+(F) Missing right brace in C<\x{...}>, C<\p{...}> or C<\P{...}>.
 
 =item Missing right curly or square bracket
 
@@ -2475,7 +2538,7 @@ couldn't be created for some peculiar reason.
 you omitted the name of the module.  Consult L<perlrun> for full details
 about C<-M> and C<-m>.
 
-=item More than one argument to open
+=item More than one argument to '%s' open
 
 (F) The C<open> function has been asked to open multiple files. This
 can happen if you are trying to open a pipe to a command that takes a
@@ -2986,6 +3049,17 @@ the string being unpacked.  See L<perlfunc/pack>.
 the string being unpacked. The string being unpacked was also invalid
 UTF-8. See L<perlfunc/pack>.
 
+=item Overloaded dereference did not return a reference
+
+(F) An object with an overloaded dereference operator was dereferenced,
+but the overloaded operation did not return a reference. See
+L<overload>.
+
+=item Overloaded qr did not return a REGEXP
+
+(F) An object with a C<qr> overload was used as part of a match, but the
+overloaded operation didn't return a compiled regexp. See L<overload>.
+
 =item %s package attribute may clash with future reserved word: %s
 
 (W reserved) A lowercase attribute name was used that had a
@@ -3202,6 +3276,11 @@ at run time.
 (P) Something tried to call utf16_to_utf8 with an odd (as opposed
 to even) byte length.
 
+=item panic: utf16_to_utf8_reversed: odd bytelen
+
+(P) Something tried to call utf16_to_utf8_reversed with an odd (as opposed
+to even) byte length.
+
 =item panic: yylex
 
 (P) The lexer got into a bad state while processing a case modifier.
@@ -3246,6 +3325,13 @@ so it was not possible to set up some or all fixed-width byte-order
 conversion functions.  This is only a problem when you're using the
 '<' or '>' modifiers in (un)pack templates.  See L<perlfunc/pack>.
 
+=item Perl_pmflag() is deprecated, and will be removed from the XS API
+
+(D deprecated) XS code called the C function C<Perl_pmflag>. This was part of
+Perl's listed public API for extending or embedding the perl interpreter. It has
+now been removed from the public API, and will be removed in a future release,
+hence XS code should be re-written not to use it.
+
 =item Perl %s required--this is only version %s, stopped
 
 (F) The module in question uses features of a version of Perl more
@@ -3457,7 +3543,7 @@ in L<perlos2>.
 
 =item Prototype after '%c' for %s : %s
 
-(W syntax) A character follows % or @ in a prototype. This is useless,
+(W illegalproto) A character follows % or @ in a prototype. This is useless,
 since % and @ gobble the rest of the subroutine arguments.
 
 =item Prototype mismatch: %s vs %s
@@ -3644,14 +3730,6 @@ always comes last, to avoid ambiguity with subsequent unary operators.
 (W io) The dirhandle you tried to do a rewinddir() on is either closed or not
 really a dirhandle.  Check your control flow.
 
-=item Runaway format
-
-(F) Your format contained the ~~ repeat-until-blank sequence, but it
-produced 200 lines at once, and the 200th line looked exactly like the
-199th line.  Apparently you didn't arrange for the arguments to exhaust
-themselves, either by using ^ instead of @ (for scalar variables), or by
-shifting or popping (for array variables).  See L<perlform>.
-
 =item Scalars leaked: %d
 
 (P) Something went wrong in Perl's internal bookkeeping of scalars:
@@ -3902,12 +3980,6 @@ the smart match.
 (F) An ancient error message that almost nobody ever runs into anymore.
 But before sort was a keyword, people sometimes used it as a filehandle.
 
-=item Sort subroutine didn't return a numeric value
-
-(F) A sort comparison routine must return a number.  You probably blew
-it by not using C<< <=> >> or C<cmp>, or by not using them correctly.
-See L<perlfunc/sort>.
-
 =item Sort subroutine didn't return single value
 
 (F) A sort comparison subroutine may not return a list value with more
@@ -3940,7 +4012,7 @@ a block by itself.
 (W unopened) You tried to use the stat() function on a filehandle that
 was either never opened or has since been closed.
 
-=item Stub found while resolving method "%s" overloading "%s"
+=item Stub found while resolving method "%s" overloading "%s" in package "%s"
 
 (P) Overloading resolution over @ISA tree may be broken by importation
 stubs.  Stubs should never be implicitly created, but explicit calls to
@@ -4151,18 +4223,18 @@ suspect you're not running on Unix.
 =item "-T" is on the #! line, it must also be used on the command line
 
 (X) The #! line (or local equivalent) in a Perl script contains the
-B<-T> option, but Perl was not invoked with B<-T> in its command line.
+B<-T> option (or the B<-t> option), but Perl was not invoked with B<-T> in its command line.
 This is an error because, by the time Perl discovers a B<-T> in a
 script, it's too late to properly taint everything from the environment.
 So Perl gives up.
 
 If the Perl script is being executed as a command using the #!
 mechanism (or its local equivalent), this error can usually be fixed by
-editing the #! line so that the B<-T> option is a part of Perl's first
-argument: e.g. change C<perl -n -T> to C<perl -T -n>.
+editing the #! line so that the B<-%c> option is a part of Perl's first
+argument: e.g. change C<perl -n -%c> to C<perl -%c -n>.
 
 If the Perl script is being executed as C<perl scriptname>, then the
-B<-T> option must appear on the command line: C<perl -T scriptname>.
+B<-%c> option must appear on the command line: C<perl -%c scriptname>.
 
 =item To%s: illegal mapping '%s'
 
@@ -4183,8 +4255,15 @@ system call to call, silly dilly.
 =item Too late for "-%s" option
 
 (X) The #! line (or local equivalent) in a Perl script contains the
-B<-M>, B<-m> or B<-C> option.  This is an error because those options
-are not intended for use inside scripts.  Use the C<use> pragma instead.
+B<-M>, B<-m> or B<-C> option.
+
+In the case of B<-M> and B<-m>, this is an error because those options are
+not intended for use inside scripts.  Use the C<use> pragma instead.
+
+The B<-C> option only works if it is specified on the command line as well
+(with the same sequence of letters or numbers following). Either specify
+this option on the command line, or, if your system supports it, make your
+script executable and run it directly instead of passing it to perl. 
 
 =item Too late to run %s block
 
@@ -4320,11 +4399,16 @@ Check the #! line, or manually feed your script into Perl yourself.
 (F) The unexec() routine failed for some reason.  See your local FSF
 representative, who probably put it there in the first place.
 
-=item Unicode character %s is illegal
+=item Unicode non-character %s is illegal for interchange
 
-(W utf8) Certain Unicode characters have been designated off-limits by
-the Unicode standard and should not be generated.  If you really know
-what you are doing you can turn off this warning by C<no warnings 'utf8';>.
+(W utf8) Certain codepoints, such as U+FFFE and U+FFFF, are defined by the
+Unicode standard to be non-characters. Those are legal codepoints, but are
+reserved for internal use; so, applications shouldn't attempt to exchange
+them.  In some cases, this message is also given if you use a codepoint that
+isn't in Unicode--that is it is above the legal maximum of U+10FFFF.  These
+aren't legal at all in Unicode, so they are illegal for interchange, but can be
+used internally in a Perl program.  If you know what you are doing you can turn
+off this warning by C<no warnings 'utf8';>.
 
 =item Unknown BYTEORDER
 
@@ -4664,12 +4748,12 @@ is deprecated. See L<perlvar/"$[">.
 
 =item Use of bare << to mean <<"" is deprecated
 
-(D deprecated, W syntax) You are now encouraged to use the explicitly quoted
+(D deprecated) You are now encouraged to use the explicitly quoted
 form if you wish to use an empty line as the terminator of the here-document.
 
 =item Use of comma-less variable list is deprecated
 
-(D deprecated, W syntax) The values you give to a format should be
+(D deprecated) The values you give to a format should be
 separated by commas, not just aligned on a line.
 
 =item Use of chdir('') or chdir(undef) as chdir() deprecated
@@ -4717,11 +4801,10 @@ to access the filehandle slot within a typeglob.
 operator.  Since C<split> always tries to match the pattern
 repeatedly, the C</g> has no effect.
 
-=item Use of implicit split to @_ is deprecated
+=item Use of "goto" to jump into a construct is deprecated
 
-(D deprecated, W syntax) It makes a lot of work for the compiler when you
-clobber a subroutine's argument list, so it's better if you assign the results
-of a split() explicitly to an array (or list).
+(D deprecated) Using C<goto> to jump from an outer scope into an inner
+scope is deprecated and should be avoided.
 
 =item Use of inherited AUTOLOAD for non-method %s() is deprecated
 
@@ -4843,7 +4926,7 @@ requesting a Unicode character between the code points 0xD800 and
 0xDFFF (inclusive).  That range is reserved exclusively for the use of
 UTF-16 encoding (by having two 16-bit UCS-2 characters); but Perl
 encodes its characters in UTF-8, so what you got is a very illegal
-character.  If you really know what you are doing you can turn off
+character.  If you really really know what you are doing you can turn off
 this warning by C<no warnings 'utf8';>.
 
 =item Value of %s can be "0"; test with defined()