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 d18baa8..c24be8a 100644 (file)
@@ -1031,6 +1031,20 @@ 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>
@@ -2276,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
@@ -2975,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
@@ -3132,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
 
@@ -3306,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
@@ -3313,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
@@ -3510,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
@@ -5343,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
@@ -5770,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
@@ -6014,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
-
-(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:
+=item The alpha_assertions feature is experimental
 
-    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.
 
@@ -6052,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
@@ -6311,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
@@ -6332,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:
 
@@ -6446,31 +6543,6 @@ to find out why that isn't happening.
 (F) The unexec() routine failed for some reason.  See your local FSF
 representative, who probably put it there in the first place.
 
-=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 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 Unexpected binary operator '%c' with no preceding operand in regex;
 marked by S<<-- HERE> in m/%s/
 
@@ -6520,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/
 
@@ -6566,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
@@ -6618,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>.
@@ -6769,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
@@ -6789,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
@@ -7543,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"