This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Perl_sv_vcatpvfn_flags: make %n missing arg fatal
[perl5.git] / pod / perldiag.pod
index 4511dac..cf9801e 100644 (file)
@@ -418,26 +418,12 @@ assigning through that reference.  For example
 used as an lvalue, which is pretty strange.  Perhaps you forgot to
 dereference it first.  See L<perlfunc/substr>.
 
-=item Attribute "locked" is deprecated, and will disappear in Perl 5.28
-
-(D deprecated) You have used the attributes pragma to modify the
-"locked" attribute on a code reference.  The :locked attribute is
-obsolete, has had no effect since 5005 threads were removed, and
-will be removed in a Perl 5.28.
-
 =item Attribute prototype(%s) discards earlier prototype attribute in same sub
 
 (W misc) A sub was declared as sub foo : prototype(A) : prototype(B) {}, for
 example.  Since each sub can only have one prototype, the earlier
 declaration(s) are discarded while the last one is applied.
 
-=item Attribute "unique" is deprecated, and will disappear in Perl 5.28
-
-(D deprecated) You have used the attributes pragma to modify
-the "unique" 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 a Perl 5.28.
-
 =item av_reify called on tied array
 
 (S debugging) This indicates that something went wrong and Perl got I<very>
@@ -839,6 +825,13 @@ C<foreach> loop nor a C<given> block.  (Note that this error is
 issued on exit from the C<default> block, so you won't get the
 error if you use an explicit C<continue>.)
 
+=item Can't determine class of operator %s, assuming BASEOP
+
+(S) This warning indicates something wrong in the internals of perl.
+Perl was trying to find the class (e.g. LISTOP) of a particular OP,
+and was unable to do so. This is likely to be due to a bug in the perl
+internals, or due to a bug in XS code which manipulates perl optrees.
+
 =item Can't do inplace edit: %s is not a regular file
 
 (S inplace) You tried to use the B<-i> switch on a special file, such as
@@ -1539,7 +1532,7 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 
 Note that ASCII characters that don't map to control characters are
 discouraged, and will generate the warning (when enabled)
-L</""\c%c" is more clearly written simply as "%s". This will be a fatal error in Perl 5.28">.
+L</""\c%c" is more clearly written simply as "%s"">.
 
 =item Character following \%c must be '{' or a single-character Unicode property name in regex; marked by <-- HERE in m/%s/
 
@@ -1646,15 +1639,13 @@ See L<charnames/CUSTOM ALIASES>.
 
 (W unopened) You tried chdir() on a filehandle that was never opened.
 
-=item "\c%c" is more clearly written simply as "%s". This will be a fatal error in Perl 5.28
+=item "\c%c" is more clearly written simply as "%s"
 
-(D deprecated, syntax) The C<\cI<X>> construct is intended to be a
-way to specify non-printable characters.  You used it for a printable
-one, which is better written as simply itself, perhaps preceded by
-a backslash for non-word characters.  Doing it the way you did is
-not portable between ASCII and EBCDIC platforms.
-
-This usage is going to result in a fatal error in Perl 5.28.
+(W syntax) The C<\cI<X>> construct is intended to be a way to specify
+non-printable characters.  You used it for a printable one, which
+is better written as simply itself, perhaps preceded by a backslash
+for non-word characters.  Doing it the way you did is not portable
+between ASCII and EBCDIC platforms.
 
 =item Cloning substitution context is unimplemented
 
@@ -1949,17 +1940,6 @@ discovered.
 (F) You said something like "use Module 42" but in the Module file
 there are neither package declarations nor a C<$VERSION>.
 
-=item delete argument is index/value array slice, use array slice
-
-(F) You used index/value array slice syntax (C<%array[...]>) as
-the argument to C<delete>.  You probably meant C<@array[...]> with
-an @ symbol instead.
-
-=item delete argument is key/value hash slice, use hash slice
-
-(F) You used key/value hash slice syntax (C<%hash{...}>) as the argument to
-C<delete>.  You probably meant C<@hash{...}> with an @ symbol instead.
-
 =item delete argument is not a HASH or ARRAY element or slice
 
 (F) The argument to C<delete> must be either a hash or array element,
@@ -1973,6 +1953,11 @@ or a hash or array slice, such as:
     @foo[$bar, $baz, $xyzzy]
     @{$ref->[12]}{"susie", "queue"}
 
+or a hash key/value or array index/value slice, such as:
+
+    %foo[$bar, $baz, $xyzzy]
+    %{$ref->[12]}{"susie", "queue"}
+
 =item Delimiter for here document is too long
 
 (F) In a here document construct like C<<<FOO>, the label C<FOO> is too
@@ -2056,6 +2041,14 @@ define a C<$VERSION>.
 (F) You cannot put a repeat count of any kind right after the '/' code.
 See L<perlfunc/pack>.
 
+=item do "%s" failed, '.' is no longer in @INC; did you mean do "./%s"?
+
+(D deprecated) Previously C< do "somefile"; > would search the current
+directory for the specified file.  Since perl v5.26.0, F<.> has been
+removed from C<@INC> by default, so this is no longer true.  To search the
+current directory (and only the current directory) you can write
+C< do "./somefile"; >.
+
 =item Don't know how to get file name
 
 (P) C<PerlIO_getname>, a perl internal I/O function specific to VMS, was
@@ -2085,7 +2078,7 @@ subroutine or package before the current location.  You can use an empty
 (D deprecated, misc) You used the obsolescent C<dump()> built-in function,
 without fully qualifying it as C<CORE::dump()>. Maybe it's a typo.
 
-Use of a unqualified C<dump()> was deprecated in Perl 5.30, and this
+Use of a unqualified C<dump()> was deprecated in Perl 5.8.0, and this
 will not be available in Perl 5.30.
 
 See L<perlfunc/dump>.
@@ -2188,7 +2181,7 @@ variable and glob that.
 (F) The C<exec> function is not implemented on some systems, e.g., Symbian
 OS.  See L<perlport>.
 
-=item Execution of %s aborted due to compilation errors.
+=item %sExecution of %s aborted due to compilation errors.
 
 (F) The final summary message when a Perl compilation fails.
 
@@ -3112,7 +3105,7 @@ neither as a system call nor an ioctl call (SIOCATMARK).
 Perl.  The current valid ones are given in
 L<perlrebackslash/\b{}, \b, \B{}, \B>.
 
-=item %s() is deprecated on :utf8 handles
+=item %s() is deprecated on :utf8 handles. This will be a fatal error in Perl 5.30
 
 (D deprecated) The sysread(), recv(), syswrite() and send() operators are
 deprecated on handles that have the C<:utf8> layer, either explicitly, or
@@ -3128,17 +3121,40 @@ the layer is some different encoding, such as the example above.
 
 Ideally, all of these operators would completely ignore the C<:utf8> state,
 working only with bytes, but this would result in silently breaking existing
-code.  To avoid this a future version of perl will throw an exception when
-any of sysread(), recv(), syswrite() or send() are called on handle with the
-C<:utf8> layer.
+code.
+
+In Perl 5.30, it will no longer be possible to use sysread(), recv(),
+syswrite() or send() to read or send bytes from/to :utf8 handles.
 
-=item "%s" is more clearly written simply as "%s" in regex. This will be a fatal error in Perl 5.28; marked by S<<-- HERE> in m/%s/
+=item "%s" is more clearly written simply as "%s" in regex; marked by S<<-- HERE> in m/%s/
 
-(W deprecated, regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
+(W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
 You specified a character that has the given plainer way of writing it,
 and which is also portable to platforms running with different character
-sets. This usage is deprecated, and will be a fatal error in Perl 5.28.
+sets.
+
+=item $* is no longer supported. Its use will be fatal in Perl 5.30
+
+(D deprecated, syntax) The special variable C<$*>, deprecated in older
+perls, has been removed as of 5.10.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.  You can enable C</m> for a lexical scope (even a whole file)
+with C<use re '/m'>.  (In older versions: when C<$*> was set to a true value
+then all regular expressions behaved as if they were written using C</m>.)
+
+Use of this variable will be a fatal error in Perl 5.30.
+
+=item $# is no longer supported. Its use will be fatal in Perl 5.30
+
+(D deprecated, syntax) The special variable C<$#>, deprecated in older
+perls, has been removed as of 5.10.0 and is no longer supported.  You
+should use the printf/sprintf functions instead.
+
+Use of this variable will be a fatal error in Perl 5.30.
 
 =item '%s' is not a code reference
 
@@ -3377,7 +3393,7 @@ the variable, C<%s>, part of the message.
 
 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.
+8-bit data).  To guard against this, you can use C<Encode::decode('UTF-8', ...)>.
 
 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
@@ -3386,14 +3402,6 @@ message.
 
 See also L<Encode/"Handling Malformed Data">.
 
-=item Malformed UTF-8 character immediately after '%s'
-
-(F) You said C<use utf8>, but the program file doesn't comply with UTF-8
-encoding rules.  The message prints out the properly encoded characters
-just before the first bad one.  If C<utf8> warnings are enabled, a
-warning is generated that gives more details about the type of
-malformation.
-
 =item Malformed UTF-8 returned by \N{%s} immediately after '%s'
 
 (F) The charnames handler returned malformed UTF-8.
@@ -3519,6 +3527,11 @@ ended earlier on the current line.
 (W syntax) An underscore (underbar) in a numeric constant did not
 separate two digits.
 
+=item Missing argument for %n in %s
+
+(F) A C<%n> was used in a format string with no corresponding argument for
+perl to write the current string length to.
+
 =item Missing argument in %s
 
 (W missing) You called a function with fewer arguments than other
@@ -4212,14 +4225,16 @@ the braces.
 (4294967295) and therefore non-portable between systems.  See
 L<perlport> for more on portability concerns.
 
-=item Odd name/value argument for subroutine
+=item Odd name/value argument for subroutine '%s'
 
 (F) A subroutine using a slurpy hash parameter in its signature
 received an odd number of arguments to populate the hash.  It requires
 the arguments to be paired, with the same number of keys as values.
-The caller of the subroutine is presumably at fault.  Inconveniently,
-this error will be reported at the location of the subroutine, not that
-of the caller.
+The caller of the subroutine is presumably at fault.
+
+The message attempts to include the name of the called subroutine. If the
+subroutine has been aliased, the subroutine's original name will be shown,
+regardless of what name the caller used.
 
 =item Odd number of arguments for overload::constant
 
@@ -4265,21 +4280,21 @@ 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. This will be a fatal error in Perl 5.28
+=item Cannot open %s as a filehandle: it is already open as a dirhandle
 
-(D io, deprecated) You used open() to associate a filehandle to
+(F) You tried to use 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 this was deprecated in Perl 5.10. In Perl 5.28, this 
-will be a fatal error.
+This idiom might render your code confusing
+and this was deprecated in Perl 5.10. As of Perl 5.28, this
+is a fatal error.
 
-=item Opening filehandle %s also as a directory. This will be a fatal error in Perl 5.28
+=item Cannot open %s as a dirhandle: it is already open as a filehandle
 
-(D io, deprecated) You used opendir() to associate a dirhandle to
+(F) You tried to use 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 this was deprecated in Perl 5.10. In Perl 5.28, this 
-will be a fatal error.
+This idiom might render your code confusing
+and this was deprecated in Perl 5.10. As of Perl 5.28, this
+is a fatal error.
 
 =item Operand with no preceding operator in regex; marked by S<<-- HERE> in
 m/%s/
@@ -5540,9 +5555,9 @@ didn't think so.
 forget to check the return value of your socket() call?  See
 L<perlfunc/setsockopt>.
 
-=item Setting $/ to a reference to %s as a form of slurp is deprecated, treating as undef. This will be fatal in Perl 5.28
+=item Setting $/ to a reference to %s is forbidden
 
-(D deprecated) You assigned a reference to a scalar to C<$/> where the
+(F) You assigned a reference to a scalar to C<$/> where the
 referenced item is not a positive integer.  In older perls this B<appeared>
 to work the same as setting it to C<undef> but was in fact internally
 different, less efficient and with very bad luck could have resulted in
@@ -5553,8 +5568,8 @@ setting C<$/> to undef, with the exception that this warning would be
 thrown.
 
 You are recommended to change your code to set C<$/> to C<undef> explicitly
-if you wish to slurp the file.  In Perl 5.28 assigning C<$/> to a 
-reference to an integer which isn't positive will throw a fatal error.
+if you wish to slurp the file.  As of Perl 5.28 assigning C<$/> to a
+reference to an integer which isn't positive is a fatal error.
 
 =item Setting $/ to %s reference is forbidden
 
@@ -5629,6 +5644,13 @@ overhauled.
 (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 Sorry, hash keys must be smaller than 2**31 bytes
+
+(F) You tried to create a hash containing a very large key, where "very
+large" means that it needs at least 2 gigabytes to store. Unfortunately,
+Perl doesn't yet handle such large hash keys. You should
+reconsider your design to avoid hashing such a long string directly.
+
 =item Source filters apply only to byte streams
 
 (F) You tried to activate a source filter (usually by loading a
@@ -6063,12 +6085,16 @@ See L<perlunicode/"User-Defined Character Properties">.
 (F) There has to be at least one argument to syscall() to specify the
 system call to call, silly dilly.
 
-=item Too few arguments for subroutine
+=item Too few arguments for subroutine '%s'
 
 (F) A subroutine using a signature received too few arguments than
 required by the signature.  The caller of the subroutine is presumably
 at fault.
 
+The message attempts to include the name of the called subroutine. If the
+subroutine has been aliased, the subroutine's original name will be shown,
+regardless of what name the caller used.
+
 =item Too late for "-%s" option
 
 (X) The #! line (or local equivalent) in a Perl script contains the
@@ -6099,12 +6125,15 @@ BEGIN block.
 
 (F) The function requires fewer arguments than you specified.
 
-=item Too many arguments for subroutine
+=item Too many arguments for subroutine '%s'
 
 (F) A subroutine using a signature received too many arguments than
 required by the signature.  The caller of the subroutine is presumably
 at fault.
 
+The message attempts to include the name of the called subroutine. If the
+subroutine has been aliased, the subroutine's original name will be shown,
+regardless of what name the caller used.
 
 =item Too many )'s
 
@@ -6460,12 +6489,6 @@ exactly, regardless of whether C<:loose> is used or not.)  This error may
 also happen if the C<\N{}> is not in the scope of the corresponding
 C<S<use charnames>>.
 
-=item Unknown charname '' is deprecated. Its use will be fatal in Perl 5.28
-
-(D deprecated) You had a C<\N{}> with nothing between the braces.  This
-usage was deprecated in Perl 5.24, and will be made a syntax error in 
-in Perl 5.28.
-
 =item Unknown error
 
 (P) Perl was about to print an error message in C<$@>, but the C<$@> variable
@@ -6906,14 +6929,14 @@ returns no useful value.  See L<perlmod>.
 (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. Its use will be fatal in Perl 5.28
+=item Use of bare << to mean <<"" is forbidden
 
-(D deprecated) You are now encouraged to use the explicitly quoted
+(F) You are now required to use the explicitly quoted
 form if you wish to use an empty line as the terminator of the
 here-document.
 
 Use of a bare terminator was deprecated in Perl 5.000, and
-will be a fatal error in Perl 5.28.
+is a fatal error as of Perl 5.28.
 
 =item Use of /c modifier is meaningless in s///
 
@@ -6926,32 +6949,21 @@ modifier is not presently meaningful in substitutions.
 use the /g modifier.  Currently, /c is meaningful only when /g is
 used.  (This may change in the future.)
 
-=item Use of code point 0x%s is deprecated; the permissible max is 0x%s. This will be fatal in Perl 5.28
+=item Use of code point 0x%s is not allowed; the permissible max is 0x%s.
 
-(D deprecated) You used a code point that will not be allowed in a
-future perl version, because it is too large.  Unicode only allows code
-points up to 0x10FFFF, but Perl allows much larger ones.  However, the
-largest possible ones break the perl interpreter in some constructs,
-including causing it to hang in a few cases.  The known problem areas
-are in C<tr///>, regular expression pattern matching using quantifiers,
-as quote delimiters in C<qI<X>...I<X>> (where I<X> is the C<chr()> of a large
-code point), and as the upper limits in loops.
-There may be other breakages as well.  If you get this warning, and
-things aren't working correctly, you probably have found one of these.
+(F) You used a code point that is not allowed, because it is too large.
+Unicode only allows code points up to 0x10FFFF, but Perl allows much
+larger ones. Earlier versions of Perl allowed code points above IV_MAX
+(0x7FFFFFF on 32-bit platforms, 0x7FFFFFFFFFFFFFFF on 64-bit platforms),
+however, this could possibly break the perl interpreter in some constructs,
+including causing it to hang in a few cases.
 
 If your code is to run on various platforms, keep in mind that the upper
 limit depends on the platform.  It is much larger on 64-bit word sizes
 than 32-bit ones.
 
 The use of out of range code points was deprecated in Perl 5.24, and
-it will be a fatal error in Perl 5.28.
-
-=item Use of comma-less variable list is deprecated. Its use will be fatal in Perl 5.28
-
-(D deprecated) The values you give to a format should be
-separated by commas, not just aligned on a line.
-
-This usage will be fatal in Perl 5.28.
+became a fatal error in Perl 5.28.
 
 =item Use of each() on hash after insertion without resetting hash iterator results in undefined behavior
 
@@ -7003,38 +7015,21 @@ middle of an iteration causes Perl to see a freed value.
 operator.  Since C<split> always tries to match the pattern
 repeatedly, the C</g> has no effect.
 
-=item Use of "goto" to jump into a construct is deprecated. Its use will be fatal in Perl 5.28
+=item Use of "goto" to jump into a construct is deprecated
 
 (D deprecated) Using C<goto> to jump from an outer scope into an inner
 scope is deprecated and should be avoided.
 
-This was deprecated in Perl 5.12, and will be a fatal error in Perl 5.28.
-
-=item Use of inherited AUTOLOAD for non-method %s() is deprecated. This will be fatal in Perl 5.28
-
-(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD>
-subroutines are looked up as methods (using the C<@ISA> hierarchy)
-even when the subroutines to be autoloaded were called as plain
-functions (e.g. C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or
-C<< $obj->bar() >>).
+This was deprecated in Perl 5.12.
 
-This bug will be rectified in future by using method lookup only for
-methods' C<AUTOLOAD>s.  However, there is a significant base of existing
-code that may be using the old behavior.  So, as an interim step, Perl
-currently issues an optional warning when non-methods use inherited
-C<AUTOLOAD>s.
+=item Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed
 
-The simple rule is:  Inheritance will not work when autoloading
-non-methods.  The simple fix for old code is:  In any module that used
-to depend on inheriting C<AUTOLOAD> for non-methods from a base class
-named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during
-startup.
+(F) As an accidental feature, C<AUTOLOAD> subroutines were looked up as
+methods (using the C<@ISA> hierarchy), even when the subroutines to be
+autoloaded were called as plain functions (e.g. C<Foo::bar()>), not as
+methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
 
-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';>.
-
-This feature was deprecated in Perl 5.004, and will be fatal in Perl 5.28.
+This was deprecated in Perl 5.004, and was made fatal in Perl 5.28.
 
 =item Use of %s in printf format not supported
 
@@ -7065,13 +7060,23 @@ its behavior may change or even be removed in any future release of perl.
 See the explanation under L<perlvar/$_>.
 
 =item Use of strings with code points over 0xFF as arguments to %s
-operator is deprecated
+operator is not allowed
 
-(D deprecated) You tried to use one of the string bitwise operators
+(F) You tried to use one of the string bitwise operators
 (C<&> or C<|> or C<^> or C<~>) on a string containing a code point over
 0xFF.  The string bitwise operators treat their operands as strings of
 bytes, and values beyond 0xFF are nonsensical in this context.
 
+This became fatal in Perl 5.28.
+
+=item Use of strings with code points over 0xFF as arguments to C<vec>
+is deprecated. This will be a fatal error in Perl 5.32
+
+(D deprecated) You tried to use L<C<vec>|perlfunc/vec EXPR,OFFSET,BITS>
+on a string containing a code point over 0xFF, which is nonsensical here.
+
+Such usage will be a fatal error in Perl 5.32.
+
 =item Use of tainted arguments in %s is deprecated
 
 (W taint, deprecated) You have supplied C<system()> or C<exec()> with multiple
@@ -7080,7 +7085,7 @@ but will become a fatal error in a future version of perl.  Untaint your
 arguments.  See L<perlsec>.
 
 =item Use of unassigned code point or non-standalone grapheme for a
-delimiter will be a fatal error starting in Perl v5.30
+delimiter will be a fatal error starting in Perl 5.30
 
 (D deprecated)
 A grapheme is what appears to a native-speaker of a language to be a