This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
detect sub attributes following a signature
[perl5.git] / pod / perldiag.pod
index 2cf2040..c24be8a 100644 (file)
@@ -1031,6 +1031,25 @@ pipe, Perl can't retrieve its name for later use.
 (P) An error peculiar to VMS.  Perl asked $GETSYI how big you want your
 mailbox buffers to be, and didn't get an answer.
 
+=item Can't "goto" into a binary or list expression
+
+(F) A "goto" statement was executed to jump into the middle of a binary
+or list expression.  You can't get there from here.  The reason for this
+restriction is that the interpreter would get confused as to how many
+arguments there are, resulting in stack corruption or crashes.  This
+error occurs in cases such as these:
+
+    goto F;
+    print do { F: }; # Can't jump into the arguments to print
+
+    goto G;
+    $x + do { G: $y }; # How is + supposed to get its first operand?
+
+=item Can't "goto" into a "given" block
+
+(F) A "goto" statement was executed to jump into the middle of a C<given>
+block.  You can't get there from here.  See L<perlfunc/goto>.
+
 =item Can't "goto" into the middle of a foreach loop
 
 (F) A "goto" statement was executed to jump into the middle of a foreach
@@ -1316,16 +1335,16 @@ loops once.  See L<perlfunc/redo>.
 file.  Perl was unable to remove the original file to replace it with
 the modified file.  The file was left unmodified.
 
-=item Can't rename %s to %s: %s, skipping file
-
-(F) The rename done by the B<-i> switch failed for some reason,
-probably because you don't have write permission to the directory.
-
 =item Can't rename in-place work file '%s' to '%s': %s
 
 (F) When closed implicitly, the temporary file for in-place editing
 couldn't be renamed to the original filename.
 
+=item Can't rename %s to %s: %s, skipping file
+
+(F) The rename done by the B<-i> switch failed for some reason,
+probably because you don't have write permission to the directory.
+
 =item Can't reopen input pipe (name: %s) in binary mode
 
 (P) An error peculiar to VMS.  Perl thought stdin was a pipe, and tried
@@ -1394,6 +1413,11 @@ with Perl, though, if you really want to do that.
 however, redefine it while it's running, and you can even undef the
 redefined subroutine while the old routine is running.  Go figure.
 
+=item Can't unweaken a nonreference
+
+(F) You attempted to unweaken something that was not a reference.  Only
+references can be unweakened.
+
 =item Can't upgrade %s (%d) to %d
 
 (P) The internal sv_upgrade routine adds "members" to an SV, making it
@@ -1536,11 +1560,6 @@ expression pattern.  Trying to do this in ordinary Perl code produces a
 value that prints out looking like SCALAR(0xdecaf).  Use the $1 form
 instead.
 
-=item Can't unweaken a nonreference
-
-(F) You attempted to unweaken something that was not a reference.  Only
-references can be unweakened.
-
 =item Can't weaken a nonreference
 
 (F) You attempted to weaken something that was not a reference.  Only
@@ -2047,7 +2066,7 @@ some such.
 
 =item (Did you mean "local" instead of "our"?)
 
-(W misc) Remember that "our" does not localize the declared global
+(W shadow) Remember that "our" does not localize the declared global
 variable.  You have declared it again in the same lexical scope, which
 seems superfluous.
 
@@ -2271,6 +2290,26 @@ to denote a capturing group of the form
 L<C<(?I<PARNO>)>|perlre/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>,
 but omitted the C<")">.
 
+=item Expecting close paren for nested extended charclass in regex; marked
+by <-- HERE in m/%s/
+
+(F) While parsing a nested extended character class like:
+
+    (?[ ... (?flags:(?[ ... ])) ... ])
+                             ^
+
+we expected to see a close paren ')' (marked by ^) but did not.
+
+=item Expecting close paren for wrapper for nested extended charclass in
+regex; marked by <-- HERE in m/%s/
+
+(F) While parsing a nested extended character class like:
+
+    (?[ ... (?flags:(?[ ... ])) ... ])
+                              ^
+
+we expected to see a close paren ')' (marked by ^) but did not.
+
 =item Expecting '(?flags:(?[...' in regex; marked by S<<-- HERE> in m/%s/
 
 (F) The C<(?[...])> extended character class regular expression construct
@@ -2652,17 +2691,6 @@ this error when Perl was built using standard options.  For some
 reason, your version of Perl appears to have been built without
 this support.  Talk to your Perl administrator.
 
-=item Illegal operator following parameter in a subroutine signature
-
-(F) A parameter in a subroutine signature, was followed by something
-other than C<=> introducing a default, C<,> or C<)>.
-
-    use feature 'signatures';
-    sub foo ($=1) {}           # legal
-    sub foo ($a = 1) {}        # legal
-    sub foo ($a += 1) {}       # illegal
-    sub foo ($a == 1) {}       # illegal
-
 =item Illegal character following sigil in a subroutine signature
 
 (F) A parameter in a subroutine signature contained an unexpected character
@@ -2727,6 +2755,17 @@ 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 operator following parameter in a subroutine signature
+
+(F) A parameter in a subroutine signature, was followed by something
+other than C<=> introducing a default, C<,> or C<)>.
+
+    use feature 'signatures';
+    sub foo ($=1) {}           # legal
+    sub foo ($a = 1) {}        # legal
+    sub foo ($a += 1) {}       # illegal
+    sub foo ($a == 1) {}       # illegal
+
 =item Illegal pattern in regex; marked by S<<-- HERE> in m/%s/
 
 (F) You wrote something like
@@ -2970,6 +3009,14 @@ expression pattern should be an indivisible token, with nothing
 intervening between the C<"("> and the C<"?">, but you separated them
 with whitespace.
 
+=item In '(*...)', the '(' and '*' must be adjacent in regex;
+marked by S<<-- HERE> in m/%s/
+
+(F) The two-character sequence C<"(*"> in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the C<"("> and the C<"*">, but you separated them.
+Fix the pattern and retry.
+
 =item Invalid %s attribute: %s
 
 (F) The indicated attribute for a subroutine or variable was not recognized
@@ -3127,10 +3174,9 @@ an arbitrary reference was blessed into the "version" class.
 =item In '(*VERB...)', the '(' and '*' must be adjacent in regex;
 marked by S<<-- HERE> in m/%s/
 
-(F) The two-character sequence C<"(*"> in
-this context in a regular expression pattern should be an
-indivisible token, with nothing intervening between the C<"(">
-and the C<"*">, but you separated them.
+(F) The two-character sequence C<"(*"> in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the C<"("> and the C<"*">, but you separated them.
 
 =item ioctl is not implemented
 
@@ -3301,6 +3347,22 @@ 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 Literal vertical space in [] is illegal except under /x in regex;
+marked by S<<-- HERE> in m/%s/
+
+(F) (only under C<S<use re 'strict'>> or within C<(?[...])>)
+
+Likely you forgot the C</x> modifier or there was a typo in the pattern.
+For example, did you really mean to match a form-feed?  If so, all the
+ASCII vertical space control characters are representable by escape
+sequences which won't present such a jarring appearance as your pattern
+does when displayed.
+
+  \r    carriage return
+  \f    form feed
+  \n    line feed
+  \cK   vertical tab
+
 =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
@@ -3308,6 +3370,30 @@ 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' contains (at least) the following characters which
+have non-standard meanings: %s  The Perl program will use the standard
+meanings
+
+(W locale) You are using the named UTF-8 locale.  UTF-8 locales are
+expected to adhere to the Unicode standard.  This message arises when
+perl found some anomalies in the locale, and is notifying you that there
+are potential problems.
+
+The most common cause of this warning is that, contrary to the claims,
+Unicode is not completely locale insensitive.  Turkish and some related
+languages have two types of C<"I"> characters.  One is dotted in both
+upper- and lowercase, and the other is dotless in both cases.  Unicode
+allows a locale to use either these rules, or the rules used in all
+other instances, where there is only one type of C<"I">, which is
+dotless in the uppercase, and dotted in the lower.  The perl core does
+not (yet) handle the Turkish case, and this warns you of that.  Instead,
+the L<Unicode::Casing> module allows you to mostly implement the Turkish
+casing rules.
+
+But there are other locales which are defective in not following the
+Unicode standard, and this message is raised if one of these is
+detected.
+
 =item Locale '%s' may not work well.%s
 
 (W locale) You are using the named locale, which is a non-UTF-8 one, and
@@ -3505,7 +3591,7 @@ not be portable
 
 (S non_unicode) Perl allows strings to contain a superset of
 Unicode code points; each code point may be as large as what is storable
-in an unsigned integer on your system, but these may not be accepted by
+in a signed integer on your system, but these may not be accepted by
 other languages/systems.  This message occurs when you matched a string
 containing such a code point against a regular expression pattern, and
 the code point was matched against a Unicode property, C<\p{...}> or
@@ -4315,6 +4401,13 @@ C<sysread()>ing a file, or when seeking past the end of a scalar opened
 for I/O (in anticipation of future reads and to imitate the behavior
 with real files).
 
+=item Old package separator used in string
+
+(W syntax) You used the old package separator, "'", in a variable
+named inside a double-quoted string; e.g., C<"In $name's house">.  This
+is equivalent to C<"In $name::s house">.  If you meant the former, put
+a backslash before the apostrophe (C<"In $name\'s house">).
+
 =item %s() on unopened %s
 
 (W unopened) An I/O operation was attempted on a filehandle that was
@@ -4395,7 +4488,7 @@ have a specific default.  You probably want "$a = undef".
 
 =item "our" variable %s redeclared
 
-(W misc) You seem to have already declared the same global once before
+(W shadow) You seem to have already declared the same global once before
 in the current lexical scope.
 
 =item Out of memory!
@@ -5331,6 +5424,11 @@ terminates.  You might use ^# instead.  See L<perlform>.
 search list.  So the additional elements in the replacement list
 are meaningless.
 
+=item '(*%s' requires a terminating ':' in regex; marked by <-- HERE in m/%s/
+
+(F) You used a construct that needs a colon and pattern argument.
+Supply these or check that you are using the right construct.
+
 =item '%s' resolved to '\o{%s}%d'
 
 (W misc, regexp)  You wrote something like C<\08>, or C<\179> in a
@@ -5758,6 +5856,15 @@ model on-disk files and can only contain bytes.
 stubs.  Stubs should never be implicitly created, but explicit calls to
 C<can> may break this.
 
+=item Subroutine attributes must come before the signature
+
+(F) When subroutine signatures are enabled, any subroutine attributes must
+come before the signature. Note that this order was the opposite in
+versions 5.20..5.26. So:
+
+    sub foo :lvalue ($a, $b) { ... }  # 5.18 and 5.28 +
+    sub foo ($a, $b) :lvalue { ... }  # 5.20 .. 5.26
+
 =item Subroutine "&%s" is not available
 
 (W closure) During compilation, an inner named subroutine or eval is
@@ -5790,7 +5897,7 @@ being executed, so its &a is not available for capture.
 
 =item "%s" subroutine &%s masks earlier declaration in same %s
 
-(W misc) A "my" or "state" subroutine has been redeclared in the
+(W shadow) A "my" or "state" subroutine 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 subroutine will still exist until the end of
@@ -5938,7 +6045,7 @@ yourself.
 a perl4 interpreter, especially if the next 2 tokens are "use strict"
 or "my $var" or "our $var".
 
-=item Syntax error in (?[...]) in regex m/%s/
+=item Syntax error in (?[...]) in regex; marked by <-- HERE in m/%s/
 
 (F) Perl could not figure out what you meant inside this construct; this
 notifies you that it is giving up trying.
@@ -6002,17 +6109,11 @@ as a compiler directive.  You may say only one of
 This is to prevent the problem of one module changing the array base out
 from under another module inadvertently.  See L<perlvar/$[> and L<arybase>.
 
-=item The bitwise feature is experimental
+=item The alpha_assertions feature is experimental
 
-(S experimental::bitwise) This warning is emitted if you use bitwise
-operators (C<& | ^ ~ &. |. ^. ~.>) with the "bitwise" feature enabled.
-Simply suppress the warning if you want to use the feature, but know
-that in doing so you are taking the risk of using an experimental
-feature which may change or be removed in a future Perl version:
-
-    no warnings "experimental::bitwise";
-    use feature "bitwise";
-    $x |.= $y;
+(S experimental::alpha_assertions) This feature is experimental
+and its behavior may change in any future release of perl.  See
+L<perlre/Extended Patterns>.
 
 =item The crypt() function is unimplemented due to excessive paranoia.
 
@@ -6040,13 +6141,19 @@ according to the probings of Configure.
 (S experimental::regex_sets) This warning is emitted if you
 use the syntax S<C<(?[   ])>> in a regular expression.
 The details of this feature are subject to change.
-if you want to use it, but know that in doing so you
+If you want to use it, but know that in doing so you
 are taking the risk of using an experimental feature which may
 change in a future Perl version, you can do this to silence the
 warning:
 
     no warnings "experimental::regex_sets";
 
+=item The script_run feature is experimental
+
+(S experimental::script_run) This feature is experimental
+and its behavior may in any future release of perl.  See
+L<perlre/Script Runs>.
+
 =item The signatures feature is experimental
 
 (S experimental::signatures) This warning is emitted if you unwrap a
@@ -6299,6 +6406,8 @@ Check the #! line, or manually feed your script into Perl yourself.
 
 =item Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by S<<-- HERE> in m/%s/
 
+=item Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by S<<-- HERE> in m/%s/
+
 (D deprecated, regexp)  The simple rule to remember, if you want to
 match a literal C<{> character (U+007B C<LEFT CURLY BRACKET>) in a
 regular expression pattern, is to escape each literal instance of it in
@@ -6320,7 +6429,7 @@ still just deprecated.  This is because of an oversight:  some uses of a
 literal C<{> that should have raised a deprecation warning starting in
 v5.20 did not warn until v5.26.  By making the already-warned uses fatal
 now, some of the planned extensions can be made to the language sooner.
-The cases which are still allowed will be fatal in Perl 5.30.
+The cases which are still allowed will be fatal in Perl 5.30 or 5.32.
 
 The contexts where no warnings or errors are raised are:
 
@@ -6483,6 +6592,14 @@ The C<")"> is out-of-place.  Something apparently was supposed to
 be combined with the digits, or the C<"+"> shouldn't be there, or
 something like that.  Perl can't figure out what was intended.
 
+=item Unexpected ']' with no following ')' in (?[... in regex; marked by
+<-- HERE in m/%s/
+
+(F) While parsing an extended character class a ']' character was
+encountered at a point in the definition where the only legal use of
+']' is to close the character class definition as part of a '])', you
+may have forgotten the close paren, or otherwise confused the parser.
+
 =item Unexpected '(' with no preceding operator in regex; marked by
 S<<-- HERE> in m/%s/
 
@@ -6529,11 +6646,24 @@ 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 '(*...)' construct '%s' in regex; marked by <-- HERE in m/%s/
+
+(F) The C<(*> was followed by something that the regular expression
+compiler does not recognize.  Check your spelling.
+
 =item Unknown error
 
 (P) Perl was about to print an error message in C<$@>, but the C<$@> variable
 did not exist, even after an attempt to create it.
 
+=item Unknown locale category %d; can't set it to %s
+
+(W locale) You used a locale category that perl doesn't recognize, so it
+cannot carry out your request.  Check that you are using a valid
+category.  If so, see L<perllocale/Multi-threaded> for advice on
+reporting this as a bug, and for modifying perl locally to accommodate
+your needs.
+
 =item Unknown open() mode '%s'
 
 (F) The second argument of 3-argument open() is not among the list
@@ -6581,15 +6711,21 @@ m/%s/
 (F) The condition part of a (?(condition)if-clause|else-clause) construct
 is not known.  The condition must be one of the following:
 
- (1) (2) ...        true if 1st, 2nd, etc., capture matched
- (<NAME>) ('NAME')  true if named capture matched
- (?=...) (?<=...)   true if subpattern matches
- (?!...) (?<!...)   true if subpattern fails to match
- (?{ CODE })        true if code returns a true value
- (R)                true if evaluating inside recursion
- (R1) (R2) ...      true if directly inside capture group 1, 2, etc.
- (R&NAME)           true if directly inside named capture
- (DEFINE)           always false; for defining named subpatterns
+ (1) (2) ...            true if 1st, 2nd, etc., capture matched
+ (<NAME>) ('NAME')      true if named capture matched
+ (?=...) (?<=...)       true if subpattern matches
+ (*pla:...) (*plb:...)  true if subpattern matches; also
+                             (*positive_lookahead:...)
+                             (*positive_lookbehind:...)
+ (*nla:...) (*nlb:...)  true if subpattern fails to match; also
+                             (*negative_lookahead:...)
+                             (*negative_lookbehind:...)
+ (?{ CODE })            true if code returns a true value
+ (R)                    true if evaluating inside recursion
+ (R1) (R2) ...          true if directly inside capture group 1, 2,
+                             etc.
+ (R&NAME)               true if directly inside named capture
+ (DEFINE)               always false; for defining named subpatterns
 
 The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
@@ -6732,6 +6868,11 @@ declares it to be in a Unicode encoding that Perl cannot read.
 (F) Your machine doesn't support the Berkeley socket mechanism, or at
 least that's what Configure thought.
 
+=item Unterminated '(*...' argument in regex; marked by <-- HERE in m/%s/
+
+(F) You used a pattern of the form C<(*...:...)> but did not terminate
+the pattern with a C<)>.  Fix the pattern and retry.
+
 =item Unterminated attribute list
 
 (F) The lexer found something other than a simple identifier at the
@@ -6752,6 +6893,11 @@ character to get your parentheses to balance.  See L<attributes>.
 compressed integer format and could not be converted to an integer.
 See L<perlfunc/pack>.
 
+=item Unterminated '(*...' construct in regex; marked by <-- HERE in m/%s/
+
+(F) You used a pattern of the form C<(*...)> but did not terminate
+the pattern with a C<)>.  Fix the pattern and retry.
+
 =item Unterminated delimiter for here document
 
 (F) This message occurs when a here document label has an initial
@@ -6964,10 +7110,12 @@ 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
+=item Use of assignment to $[ is deprecated, and will be fatal in 5.30
 
 (D deprecated) The C<$[> variable (index of the first element in an array)
-is deprecated.  See L<perlvar/"$[">.
+is deprecated since Perl 5.12, and setting it to a non-zero value will be
+fatal as of Perl 5.30.
+See L<perlvar/"$[">.
 
 =item Use of bare << to mean <<"" is forbidden
 
@@ -7085,12 +7233,6 @@ C<$array[0+$ref]>.  This warning is not given for overloaded objects,
 however, because you can overload the numification and stringification
 operators and then you presumably know what you are doing.
 
-=item Use of state $_ is experimental
-
-(S experimental::lexical_topic) Lexical $_ is an experimental feature and
-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 not allowed
 
@@ -7323,7 +7465,7 @@ See L<re>.
 
 =item "%s" variable %s masks earlier declaration in same %s
 
-(W misc) A "my", "our" or "state" variable has been redeclared in the
+(W shadow) 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
@@ -7510,8 +7652,10 @@ the end of the string being unpacked.  See L<perlfunc/pack>.
 
 (F) And you probably never will, because you probably don't have the
 sources to your kernel, and your vendor probably doesn't give a rip
-about what you want.  Your best bet is to put a setuid C wrapper around
-your script.
+about what you want.  There is a vulnerability anywhere that you have a
+set-id script, and to close it you need to remove the set-id bit from
+the script that you're attempting to run.  To actually run the script
+set-id, your best bet is to put a set-id C wrapper around your script.
 
 =item You need to quote "%s"