This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
support for C<exists &func> (from Spider Boardman)
[perl5.git] / pod / perldiag.pod
index 527f73b..752605d 100644 (file)
@@ -110,7 +110,12 @@ your signed integers.  See L<perlfunc/unpack>.
 
 (W) You used a backslash-character combination which is not recognized
 by Perl.  This combination appears in an interpolated variable or a 
-C<'>-delimited regular expression.
+C<'>-delimited regular expression.  The character was understood literally.
+
+=item /%s/: Unrecognized escape \\%c in character class passed through
+
+(W) You used a backslash-character combination which is not recognized
+by Perl inside character classes.  The character was understood literally.
 
 =item /%s/ should probably be written as "%s"
 
@@ -135,25 +140,30 @@ definition ahead of the call to get proper prototype checking.  Alternatively,
 if you are certain that you're calling the function correctly, you may put
 an ampersand before the name to avoid the warning.  See L<perlsub>.
 
-=item %s argument is not a HASH element
+=item %s argument is not a HASH or ARRAY element
 
-(F) The argument to exists() must be a hash element, such as
+(F) The argument to exists() must be a hash or array element, such as:
 
     $foo{$bar}
-    $ref->[12]->{"susie"}
+    $ref->[12]->["susie"]
 
-=item %s argument is not a HASH element or slice
+=item %s argument is not a HASH or ARRAY element or slice
 
-(F) The argument to delete() must be either a hash element, such as
+(F) The argument to delete() must be either a hash or array element, such as:
 
     $foo{$bar}
-    $ref->[12]->{"susie"}
+    $ref->[12]->["susie"]
 
-or a hash slice, such as
+or a hash or array slice, such as:
 
-    @foo{$bar, $baz, $xyzzy}
+    @foo[$bar, $baz, $xyzzy]
     @{$ref->[12]}{"susie", "queue"}
 
+=item %s argument is not a subroutine name
+
+(F) The argument to exists() for C<exists &sub> must be a subroutine
+name, and not a subroutine call.  C<exists &sub()> will generate this error.
+
 =item %s did not return a true value
 
 (F) A required (or used) file must return a true value to indicate that
@@ -275,7 +285,7 @@ the string being unpacked.  See L<perlfunc/pack>.
 (F) You wrote C<require E<lt>fileE<gt>> when you should have written
 C<require 'file'>.
 
-=item accept() on closed fd
+=item accept() on closed socket
 
 (W) You tried to do an accept on a closed socket.  Did you forget to check
 the return value of your socket() call?  See L<perlfunc/accept>.
@@ -513,7 +523,7 @@ likely depends on its correct operation, Perl just gave up.
 (4294967295) and therefore non-portable between systems.  See
 L<perlport> for more on portability concerns.
 
-=item bind() on closed fd
+=item bind() on closed socket
 
 (W) You tried to do a bind on a closed socket.  Did you forget to check
 the return value of your socket() call?  See L<perlfunc/bind>.
@@ -537,7 +547,7 @@ so it was truncated to the string shown.
 (F) A subroutine invoked from an external package via perl_call_sv()
 exited by calling exit.
 
-=item Can't "goto" outside a block
+=item Can't "goto" out of a pseudo block
 
 (F) A "goto" statement was executed to jump out of what might look
 like a block, except that it isn't a proper block.  This usually
@@ -549,22 +559,24 @@ is a no-no.  See L<perlfunc/goto>.
 (F) A "goto" statement was executed to jump into the middle of a
 foreach loop.  You can't get there from here.  See L<perlfunc/goto>.
 
-=item Can't "last" outside a block
+=item Can't "last" outside a loop block
 
 (F) A "last" statement was executed to break out of the current block,
 except that there's this itty bitty problem called there isn't a
 current block.  Note that an "if" or "else" block doesn't count as a
-"loopish" block, as doesn't a block given to sort().  You can usually double
-the curlies to get the same effect though, because the inner curlies
-will be considered a block that loops once.  See L<perlfunc/last>.
+"loopish" block, as doesn't a block given to sort(), map() or grep().
+You can usually double the curlies to get the same effect though,
+because the inner curlies will be considered a block that loops once.
+See L<perlfunc/last>.
 
-=item Can't "next" outside a block
+=item Can't "next" outside a loop block
 
 (F) A "next" statement was executed to reiterate the current block, but
 there isn't a current block.  Note that an "if" or "else" block doesn't
-count as a "loopish" block, as doesn't a block given to sort().  You can
-usually double the curlies to get the same effect though, because the inner
-curlies will be considered a block that loops once.  See L<perlfunc/next>.
+count as a "loopish" block, as doesn't a block given to sort(), map()
+or grep().  You can usually double the curlies to get the same effect
+though, because the inner curlies will be considered a block that
+loops once.  See L<perlfunc/next>.
 
 =item Can't read CRTL environ
 
@@ -573,13 +585,14 @@ from the CRTL's internal environment array and discovered the array was
 missing.  You need to figure out where your CRTL misplaced its environ
 or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched.
 
-=item Can't "redo" outside a block
+=item Can't "redo" outside a loop block
 
 (F) A "redo" statement was executed to restart the current block, but
 there isn't a current block.  Note that an "if" or "else" block doesn't
-count as a "loopish" block, as doesn't a block given to sort().  You can
-usually double the curlies to get the same effect though, because the inner
-curlies will be considered a block that loops once.  See L<perlfunc/redo>.
+count as a "loopish" block, as doesn't a block given to sort(), map()
+or grep().  You can usually double the curlies to get the same effect
+though, because the inner curlies will be considered a block that
+loops once.  See L<perlfunc/redo>.
 
 =item Can't bless non-reference value
 
@@ -631,7 +644,7 @@ Something like this will reproduce the error:
 (F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory
 that you can chdir to, possibly because it doesn't exist.
 
-=item Can't check filesystem of script "%s"
+=item Can't check filesystem of script "%s" for nosuid
 
 (P) For some reason you can't check the filesystem of the script for nosuid.
 
@@ -821,6 +834,15 @@ L<perlfunc/goto>.
 (F) The "goto subroutine" call can't be used to jump out of an eval "string".
 (You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)
 
+=item Can't ignore signal CHLD, forcing to default
+
+(W) Perl has detected that it is being run with the SIGCHLD signal
+(sometimes known as SIGCLD) disabled.  Since disabling this signal
+will interfere with proper determination of exit status of child
+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 localize through a reference
 
 (F) You said something like C<local $$ref>, which Perl can't currently
@@ -1051,7 +1073,7 @@ most likely an unexpected right brace '}'.
 reference of the type needed.  You can use the ref() function to
 test the type of the reference, if need be.
 
-=item Can't use \1 to mean $1 in expression
+=item Can't use \%c to mean $%c in expression
 
 (W) In an ordinary expression, backslash is a unary operator that creates
 a reference to its argument.  The use of backslash to indicate a backreference
@@ -1059,7 +1081,7 @@ to a matched substring is valid only as part of a regular 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 use bareword ("%s") as %s ref while \"strict refs\" in use
+=item Can't use bareword ("%s") as %s ref while "strict refs" in use
 
 (F) Only hard references are allowed by "strict refs".  Symbolic references
 are disallowed.  See L<perlref>.
@@ -1170,7 +1192,7 @@ than in the regular expression engine; or rewriting the regular
 expression so that it is simpler or backtracks less.  (See L<perlbook>
 for information on I<Mastering Regular Expressions>.)
 
-=item connect() on closed fd
+=item connect() on closed socket
 
 (W) You tried to do a connect on a closed socket.  Did you forget to check
 the return value of your socket() call?  See L<perlfunc/connect>.
@@ -1302,10 +1324,11 @@ ugly.  Your code will be interpreted as an attempt to call a method
 named "elseif" for the class returned by the following block.  This is
 unlikely to be what you want.
 
-=item END failed--cleanup aborted
+=item %s failed--call queue aborted
 
-(F) An untrapped exception was raised while executing an END subroutine.
-The interpreter is immediately exited.
+(F) An untrapped exception was raised while executing a STOP, INIT, or
+END subroutine.  Processing of the remainder of the queue of such
+routines has been prematurely ended.
 
 =item entering effective %s failed
 
@@ -1380,6 +1403,13 @@ the effect of blessing the reference into the package main.  This is
 usually not what you want.  Consider providing a default target
 package, e.g. bless($ref, $p || 'MyPackage');
 
+=item false [] range "%s" in regexp
+
+(W) A character class range must start and end at a literal character, not
+another character class like C<\d> or C<[:alpha:]>.  The "-" in your false
+range is interpreted as a literal "-".  Consider quoting the "-",  "\-".
+See L<perlre>.
+
 =item Fatal VMS error at %s, line %d
 
 (P) An error peculiar to VMS.  Something untoward happened in a VMS system
@@ -1464,7 +1494,7 @@ when you meant
 because if it did, it'd feel morally obligated to return every hostname
 on the Internet.
 
-=item get{sock,peer}name() on closed fd
+=item get%sname() on closed socket
 
 (W) You tried to get a socket or peer socket name on a closed socket.
 Did you forget to check the return value of your socket() call?
@@ -1680,11 +1710,10 @@ by Perl or by a user-supplied handler.  See L<attributes>.
 The indicated attributes for a subroutine or variable were not recognized
 by Perl or by a user-supplied handler.  See L<attributes>.
 
-=item invalid [] range in regexp
+=item invalid [] range "%s" in regexp
 
 (F) The range specified in a character class had a minimum character
-greater than the maximum character, or the range didn't start/end with
-a literal character.  See L<perlre>.
+greater than the maximum character.  See L<perlre>.
 
 =item Invalid conversion in %s: "%s"
 
@@ -1742,7 +1771,7 @@ L<perlfunc/last>.
 (F) While under the C<use filetest> pragma, switching the real and
 effective uids or gids failed.
 
-=item listen() on closed fd
+=item listen() on closed socket
 
 (W) 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>.
@@ -1880,6 +1909,11 @@ See L<perlsec>.
 
 (F) A setuid script can't be specified by the user.
 
+=item No %s specified for -%c
+
+(F) The indicated command line switch needs a mandatory argument, but
+you haven't specified one.
+
 =item No comma allowed after %s
 
 (F) A list operator that has a filehandle or "indirect object" is not
@@ -1964,10 +1998,10 @@ your system.
 (F) Configure didn't find anything resembling the setreuid() call for
 your system.
 
-=item No space allowed after B<-I>
+=item No space allowed after -%c
 
-(F) The argument to B<-I> must follow the B<-I> immediately with no
-intervening space.
+(F) The argument to the indicated command line switch must follow immediately
+after the switch, without intervening spaces.
 
 =item No such pseudo-hash field "%s"
 
@@ -2341,6 +2375,10 @@ was string.
 
 (P) The lexer got into a bad state while processing a case modifier.
 
+=item panic: %s
+
+(P) An internal error.
+
 =item Parentheses missing around "%s" list
 
 (W) You said something like
@@ -2450,12 +2488,12 @@ instead of "||".
 
 See Server error.
 
-=item print on closed filehandle %s
+=item print() on closed filehandle %s
 
 (W) The filehandle you're printing on got itself closed sometime before now.
 Check your logic flow.
 
-=item printf on closed filehandle %s
+=item printf() on closed filehandle %s
 
 (W) The filehandle you're writing to got itself closed sometime before now.
 Check your logic flow.
@@ -2480,7 +2518,7 @@ are outside the range which can be represented by integers internally.
 One possible workaround is to force Perl to use magical string
 increment by prepending "0" to your numbers.
 
-=item Read on closed filehandle %s
+=item readline() on closed filehandle %s
 
 (W) The filehandle you're reading from got itself closed sometime before now.
 Check your logic flow.
@@ -2621,9 +2659,9 @@ that had previously been marked as free.
 (W) A nearby syntax error was probably caused by a missing semicolon,
 or possibly some other missing operator, such as a comma.
 
-=item Send on closed socket
+=item send() on closed socket
 
-(W) The filehandle you're sending to got itself closed sometime before now.
+(W) The socket you're sending to got itself closed sometime before now.
 Check your logic flow.
 
 =item Sequence (? incomplete
@@ -2710,7 +2748,7 @@ because the world might have written on it already.
 
 (F) You don't have System V shared memory IPC on your system.
 
-=item shutdown() on closed fd
+=item shutdown() on closed socket
 
 (W) You tried to do a shutdown on a closed socket.  Seems a bit superfluous.
 
@@ -2848,7 +2886,7 @@ into Perl yourself.
 machine.  In some machines the functionality can exist but be
 unconfigured.  Consult your system support.
 
-=item Syswrite on closed filehandle
+=item syswrite() on closed filehandle
 
 (W) The filehandle you're writing to got itself closed sometime before now.
 Check your logic flow.
@@ -3241,7 +3279,7 @@ e.g. C<&our()>, or C<Foo::our()>.
 because there's a better way to do it, and also because the old way has
 bad side effects.
 
-=item Use of uninitialized value
+=item Use of uninitialized value%s
 
 (W) An undefined value was used as if it were already defined.  It was
 interpreted as a "" or a 0, but maybe it was a mistake.  To suppress this
@@ -3416,7 +3454,7 @@ but in actual fact, you got
 
 So put in parentheses to say what you really mean.
 
-=item Write on closed filehandle %s
+=item write() on closed filehandle %s
 
 (W) The filehandle you're writing to got itself closed sometime before now.
 Check your logic flow.
@@ -3459,11 +3497,11 @@ already have a subroutine of that name declared, which means that Perl 5
 will try to call the subroutine when the assignment is executed, which is
 probably not what you want.  (If it IS what you want, put an & in front.)
 
-=item [gs]etsockopt() on closed fd
+=item %cetsockopt() on closed fd
 
 (W) You tried to get or set a socket option on a closed socket.
 Did you forget to check the return value of your socket() call?
-See L<perlfunc/getsockopt>.
+See L<perlfunc/getsockopt> and L<perlfunc/setsockopt>.
 
 =item \1 better written as $1