sanity check piped opens (tweaked version of patch suggested
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index b23dcc5..211262c 100644 (file)
@@ -33,11 +33,11 @@ The symbols C<"%(-?@> sort before the letters, while C<[> and C<\> sort after.
 to try to declare one with a package qualifier on the front.  Use local()
 if you want to localize a package variable.
 
-=item "my" variable %s masks earlier declaration in same scope
+=item "my" variable %s masks earlier declaration in same %s
 
-(W) A lexical variable has been redeclared in the same scope, effectively
-eliminating all access to the previous instance.  This is almost always
-a typographical error.  Note that the earlier variable will still exist
+(W) A lexical 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 or until all closure referents to it are
 destroyed.
 
@@ -57,6 +57,12 @@ no useful value.  See L<perlmod>.
 checksumming process loses information, and you can't go the other
 way.  See L<perlfunc/unpack>.
 
+=item /%s/: Unrecognized escape \\%c passed through
+
+(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.
+
 =item %s (...) interpreted as function
 
 (W) You've run afoul of the rule that says that any list operator followed
@@ -143,6 +149,18 @@ Perl yourself.
 instead of Perl.  Check the #! line, or manually feed your script
 into Perl yourself.
 
+=item         (in cleanup) %s
+
+(W) This prefix usually indicates that a DESTROY() method raised
+the indicated exception.  Since destructors are usually called by
+the system at arbitrary points during execution, and often a vast
+number of times, the warning is issued only once for any number
+of failures that would otherwise result in the same message being
+repeated.
+
+Failure of user callbacks dispatched using the C<G_KEEPERR> flag
+could also result in this warning.  See L<perlcall/G_KEEPERR>.
+
 =item         (Missing semicolon on previous line?)
 
 (S) This is an educated guess made in conjunction with the message "%s
@@ -188,10 +206,6 @@ the return value of your socket() call?  See L<perlfunc/accept>.
 
 (X) You can't allocate more than 64K on an MS-DOS machine.
 
-=item Allocation too large
-
-(F) You can't allocate more than 2^31+"small amount" bytes.
-
 =item Applying %s to %s will act on scalar(%s)
 
 (W) The pattern match (//), substitution (s///), and transliteration (tr///)
@@ -211,6 +225,22 @@ L<perlfunc/grep> and L<perlfunc/map> for alternatives.
 you thought.  Normally it's pretty easy to disambiguate it by supplying
 a missing quote, operator, parenthesis pair or declaration.
 
+=item Ambiguous call resolved as CORE::%s(), qualify as such or use &
+
+(W) A subroutine you have declared has the same name as a Perl keyword,
+and you have used the name without qualification for calling one or the
+other.  Perl decided to call the builtin because the subroutine is
+not imported.
+
+To force interpretation as a subroutine call, either put an ampersand
+before the subroutine name, or qualify the name with its package.
+Alternatively, you can import the subroutine (or pretend that it's
+imported with the C<use subs> pragma).
+
+To silently interpret it as the Perl operator, use the C<CORE::> prefix
+on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
+to be an object method (see L<attrs>).
+
 =item Args must match #! line
 
 (F) The setuid emulator requires that the arguments Perl was invoked
@@ -320,6 +350,12 @@ system malloc().
 
 (P) One of the internal hash routines was passed a null HV pointer.
 
+=item Bad index while coercing array into hash
+
+(F) The index looked up in the hash found as the 0'th element of a
+pseudo-hash is not legal.  Index values must be at 1 or greater.
+See L<perlref>.
+
 =item Bad name after %s::
 
 (F) You started to name a symbol by using a package prefix, and then didn't
@@ -459,7 +495,17 @@ an object reference until it has been blessed.  See L<perlobj>.
 
 (F) You used the syntax of a method call, but the slot filled by the
 object reference or package name contains an expression that returns
-neither an object reference nor a package name.  (Perhaps it's null?)
+a defined value which is neither an object reference nor a package name.
+Something like this will reproduce the error:
+
+    $BADREF = 42;
+    process $BADREF 1,2,3;
+    $BADREF->process(1,2,3);
+
+=item Can't call method "%s" on an undefined value
+
+(F) You used the syntax of a method call, but the slot filled by the
+object reference or package name contains an undefined value.
 Something like this will reproduce the error:
 
     $BADREF = undef;
@@ -496,6 +542,12 @@ but then $foo no longer contains a glob.
 (F) Certain types of SVs, in particular real symbol table entries
 (typeglobs), can't be forced to stop being what they are.
 
+=item Can't coerce array into hash
+
+(F) You used an array where a hash was expected, but the array has no
+information on how to map from keys to array indices.  You can do that
+only with arrays that have a hash reference at index 0.
+
 =item Can't create pipe mailbox
 
 (P) An error peculiar to VMS.  The process is suffering from exhausted quotas
@@ -663,6 +715,13 @@ lexical variable using "my".  This is not allowed.  If you want to
 localize a package variable of the same name, qualify it with the
 package name.
 
+=item Can't localize pseudo-hash element
+
+(F) You said something like C<local $ar-E<gt>{'key'}>, where $ar is
+a reference to a pseudo-hash.  That hasn't been implemented yet, but
+you can get a similar effect by localizing the corresponding array
+element directly -- C<local $ar-E<gt>[$ar-E<gt>[0]{'key'}]>.
+
 =item Can't locate auto/%s.al in @INC
 
 (F) A function (or method) was called in a package which allows autoload,
@@ -823,6 +882,12 @@ message indicates that such a conversion was attempted.
 of upgradability.  Upgrading to undef indicates an error in the
 code calling sv_upgrade.
 
+=item Can't use %%! because Errno.pm is not available
+
+(F) The first time the %! hash is used, perl automatically loads the
+Errno.pm module. The Errno module is expected to tie the %! hash to
+provide symbolic names for C<$!> errno values.
+
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
@@ -938,11 +1003,31 @@ to 01411.  Octal constants are introduced with a leading 0 in Perl, as in C.
 Perl uses this generic message when none of the errors that it encountered
 were severe enough to halt compilation immediately.
 
+=item Complex regular subexpression recursion limit (%d) exceeded
+
+(W) The regular expression engine uses recursion in complex situations
+where back-tracking is required.  Recursion depth is limited to 32766,
+or perhaps less in architectures where the stack cannot grow
+arbitrarily.  ("Simple" and "medium" situations are handled without
+recursion and are not subject to a limit.)  Try shortening the string
+under examination; looping in Perl code (e.g. with C<while>) rather
+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
 
 (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>.
 
+=item Constant is not %s reference
+
+(F) A constant value (perhaps declared using the C<use constant> pragma)
+is being dereferenced, but it amounts to the wrong type of reference.  The
+message indicates the type of reference that was expected. This usually
+indicates a syntax error in dereferencing the constant value.
+See L<perlsub/"Constant Functions"> and L<constant>.
+
 =item Constant subroutine %s redefined
 
 (S) You redefined a subroutine which had previously been eligible for
@@ -1037,6 +1122,11 @@ unlikely to be what you want.
 (F) An untrapped exception was raised while executing an END subroutine.
 The interpreter is immediately exited.
 
+=item entering effective %s failed
+
+(F) While under the C<use filetest> pragma, switching the real and
+effective uids or gids failed.
+
 =item Error converting file specification %s
 
 (F) An error peculiar to VMS.  Because Perl may have to deal with file
@@ -1045,6 +1135,27 @@ single form when it must operate on them directly.  Either you've
 passed an invalid file specification to Perl, or you've found a
 case the conversion routines don't handle.  Drat.
 
+=item %s: Eval-group in insecure regular expression
+
+(F) Perl detected tainted data when trying to compile a regular expression
+that contains the C<(?{ ... })> zero-width assertion, which is unsafe.
+See L<perlre/(?{ code })>, and L<perlsec>.
+
+=item %s: Eval-group not allowed, use re 'eval'
+
+(F) A regular expression contained the C<(?{ ... })> zero-width assertion,
+but that construct is only allowed when the C<use re 'eval'> pragma is
+in effect.  See L<perlre/(?{ code })>.
+
+=item %s: Eval-group not allowed at run time
+
+(F) Perl tried to compile a regular expression containing the C<(?{ ... })>
+zero-width assertion at run time, as it would when the pattern contains
+interpolated values.  Since that is a security risk, it is not allowed.
+If you insist, you may still do this by explicitly building the pattern
+from an interpolated string at run time and using that in an eval().
+See L<perlre/(?{ code })>.
+
 =item Excessively long <> operator
 
 (F) The contents of a <> operator may not exceed the maximum size of a
@@ -1082,7 +1193,7 @@ a return, a goto, or a loop control statement.
 (W) You are blessing a reference to a zero length string.  This has
 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 or 'MyPackage');
+package, e.g. bless($ref, $p || 'MyPackage');
 
 =item Fatal VMS error at %s, line %d
 
@@ -1178,7 +1289,6 @@ Did you forget to check the return value of your socket() call?
 (S) A warning peculiar to VMS.  The call to C<sys$getuai> underlying the
 C<getpwnam> operator returned an invalid UIC.
 
-
 =item Glob not terminated
 
 (F) The lexer saw a left angle bracket in a place where it was expecting
@@ -1299,10 +1409,11 @@ for more information.
 script if C<$ENV{PATH}> contains a directory that is writable by the world.
 See L<perlsec>.
 
-=item Insecure PATH
+=item Insecure $ENV{%s} while running %s
 
 (F) You can't use system(), exec(), or a piped open in a setuid or
-setgid script if C<$ENV{PATH}> is derived from data supplied (or
+setgid script if any of C<$ENV{PATH}>, C<$ENV{IFS}>, C<$ENV{CDPATH}>,
+C<$ENV{ENV}> or C<$ENV{BASH_ENV}> are derived from data supplied (or
 potentially supplied) by the user.  The script must set the path to a
 known value, using trustworthy data.  See L<perlsec>.
 
@@ -1323,7 +1434,7 @@ architecture. On a 32-bit architecture the largest octal literal is
 (S) A warning peculiar to VMS.  Perl keeps track of the number
 of times you've called C<fork> and C<exec>, to determine
 whether the current call to C<exec> should affect the current
-script or a subprocess (see L<perlvms/exec>).  Somehow, this count
+script or a subprocess (see L<perlvms/"exec LIST">).  Somehow, this count
 has become scrambled, so Perl is making a guess and treating
 this C<exec> as a request to terminate the Perl script
 and execute the specified command.
@@ -1332,16 +1443,19 @@ and execute the specified command.
 
 (P) Something went badly wrong in the regular expression parser.
 
-=item internal error: glob failed
+=item glob failed (%s)
 
-(P) Something went wrong with the external program(s) used for C<glob>
-and C<E<lt>*.cE<gt>>.  This may mean that your csh (C shell) is
-broken.  If so, you should change all of the csh-related variables in
-config.sh:  If you have tcsh, make the variables refer to it as if it
-were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
-empty (except that C<d_csh> should be C<'undef'>) so that Perl will
-think csh is missing.  In either case, after editing config.sh, run
-C<./Configure -S> and rebuild Perl.
+(W) Something went wrong with the external program(s) used for C<glob>
+and C<E<lt>*.cE<gt>>.  Usually, this means that you supplied a C<glob>
+pattern that caused the external program to fail and exit with a nonzero
+status.  If the message indicates that the abnormal exit resulted in a
+coredump, this may also mean that your csh (C shell) is broken.  If so,
+you should change all of the csh-related variables in config.sh:  If you
+have tcsh, make the variables refer to it as if it were csh (e.g.
+C<full_csh='/usr/bin/tcsh'>); otherwise, make them all empty (except that
+C<d_csh> should be C<'undef'>) so that Perl will think csh is missing.
+In either case, after editing config.sh, run C<./Configure -S> and
+rebuild Perl.
 
 =item internal urp in regexp at /%s/
 
@@ -1396,6 +1510,11 @@ L<perlfunc/last>.
 that name, not even if you count where you were called from.  See
 L<perlfunc/last>.
 
+=item leaving effective %s failed
+
+(F) While under the C<use filetest> pragma, switching the real and
+effective uids or gids failed.
+
 =item listen() on closed fd
 
 (W) You tried to do a listen on a closed socket.  Did you forget to check
@@ -1427,6 +1546,11 @@ one line to the next.
 (F) While certain functions allow you to specify a filehandle or an
 "indirect object" before the argument list, this ain't one of them.
 
+=item Missing command in piped open
+
+(W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
+construction, but the command was missing or blank.
+
 =item Missing operator before %s?
 
 (S) This is an educated guess made in conjunction with the message "%s
@@ -1449,15 +1573,15 @@ catches that.  But an easy way to do the same thing is:
 
 Another way is to assign to a substr() that's off the end of the string.
 
-=item Modification of noncreatable array value attempted, subscript %d
+=item Modification of non-creatable array value attempted, subscript %d
 
 (F) You tried to make an array value spring into existence, and the
 subscript was probably negative, even counting from end of the array
 backwards.
 
-=item Modification of noncreatable hash value attempted, subscript "%s"
+=item Modification of non-creatable hash value attempted, subscript "%s"
 
-(F) You tried to make a hash value spring into existence, and it couldn't
+(P) You tried to make a hash value spring into existence, and it couldn't
 be created for some peculiar reason.
 
 =item Module name must be constant
@@ -1598,6 +1722,19 @@ your system.
 (F) The argument to B<-I> must follow the B<-I> immediately with no
 intervening space.
 
+=item No such array field
+
+(F) You tried to access an array as a hash, but the field name used is
+not defined.  The hash at index 0 should map all valid field names to
+array indices for that to work.
+
+=item No such field "%s" in variable %s of type %s
+
+(F) You tried to access a field of a typed variable where the type
+does not know about the field name.  The field names are looked up in
+the %FIELDS hash in the type package at compile time.  The %FIELDS hash
+is usually set up with the 'fields' pragma.
+
 =item No such pipe open
 
 (P) An error peculiar to VMS.  The internal routine my_pclose() tried to
@@ -1609,6 +1746,14 @@ an attempt to close an unopened filehandle.
 (W) You specified a signal name as a subscript to %SIG that was not recognized.
 Say C<kill -l> in your shell to see the valid signal names on your system.
 
+=item no UTC offset information; assuming local time is UTC
+
+(S) A warning peculiar to VMS.  Per was unable to find the local
+timezone offset, so it's assuming that local system time is equivalent
+to UTC.  If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL>
+to translate to the number of seconds which need to be added to UTC to
+get local time.
+
 =item Not a CODE reference
 
 (F) Perl was trying to evaluate a reference to a code value (that is, a
@@ -1727,7 +1872,7 @@ will extend the buffer and zero pad the new area.
 
 (S) An internal warning that the grammar is screwed up.
 
-=item Operation `%s': no method found,%s
+=item Operation `%s': no method found, %s
 
 (F) An attempt was made to perform an overloaded operation for which
 no handler was defined.  While some handlers can be autogenerated in
@@ -1748,7 +1893,7 @@ if you said "*foo * 'foo'".
 (F) The yacc parser wanted to grow its stack so it could continue parsing,
 but realloc() wouldn't give it more memory, virtual or otherwise.
 
-=item Out of memory!
+=item Out of memory during request for %s
 
 (X|F) The malloc() function returned 0, indicating there was insufficient
 remaining memory (or virtual memory) to satisfy the request.
@@ -1759,13 +1904,19 @@ However, if compiled for this, Perl may use the contents of C<$^M> as
 an emergency pool after die()ing with this message.  In this case the
 error is trappable I<once>.
 
-=item Out of memory during request for %s
+=item Out of memory during "large" request for %s
 
 (F) The malloc() function returned 0, indicating there was insufficient
 remaining memory (or virtual memory) to satisfy the request. However,
 the request was judged large enough (compile-time default is 64K), so
 a possibility to shut down by trapping this error is granted.
 
+=item Out of memory during ridiculously large request
+
+(F) You can't allocate more than 2^31+"small amount" bytes.  This error
+is most likely to be caused by a typo in the Perl program. e.g., C<$arr[time]>
+instead of C<$arr[$time]>.
+
 =item page overflow
 
 (W) A single call to write() produced more lines than can fit on a page.
@@ -1937,7 +2088,7 @@ anyway?  See L<perlfunc/require>.
 
 (F) The setuid emulator in suidperl decided you were up to no good.
 
-=item pid %d not a child
+=item pid %x not a child
 
 (W) A warning peculiar to VMS.  Waitpid() was asked to wait for a process which
 isn't a subprocess of the current process.  While this is fine from VMS'
@@ -2038,6 +2189,13 @@ last argument of the previous construct, for example:
 (S) The subroutine being declared or defined had previously been declared
 or defined with a different function prototype.
 
+=item Range iterator outside integer range
+
+(F) One (or both) of the numeric arguments to the range operator ".."
+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 E<lt>%sE<gt>
 
 (W) The filehandle you're reading from got itself closed sometime before now.
@@ -2053,11 +2211,16 @@ Check your logic flow.
 desired output is compiled into Perl, which entails some overhead,
 which is why it's currently left out of your copy.
 
-=item Recursive inheritance detected
+=item Recursive inheritance detected in package '%s'
 
 (F) More than 100 levels of inheritance were used.  Probably indicates
 an unintended loop in your inheritance hierarchy.
 
+=item Recursive inheritance detected while looking for method '%s' in package '%s'
+
+(F) More than 100 levels of inheritance were encountered while invoking a
+method.  Probably indicates an unintended loop in your inheritance hierarchy.
+
 =item Reference found where even-sized list expected
 
 (W) You gave a single reference where Perl was expecting a list with
@@ -2089,14 +2252,6 @@ expression compiler gave it.
 
 (P) A "can't happen" error, because safemalloc() should have caught it earlier.
 
-=item regexp too big
-
-(F) The current implementation of regular expressions uses shorts as
-address offsets within a string.  Unfortunately this means that if
-the regular expression compiles to longer than 32767, it'll blow up.
-Usually when you want a regular expression this big, there is a better
-way to do it with multiple statements.  See L<perlre>.
-
 =item Reversed %s= operator
 
 (W) You wrote your assignment operator backwards.  The = must always
@@ -2293,6 +2448,14 @@ there was a failure.  You probably wanted to use system() instead,
 which does return.  To suppress this warning, put the exec() in a block
 by itself.
 
+=item Strange *+?{} on zero-length expression
+
+(W) You applied a regular expression quantifier in a place where it
+makes no sense, such as on a zero-width assertion.
+Try putting the quantifier inside the assertion instead.  For example,
+the way to match "abc" provided that it is followed by three
+repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
+
 =item Stub found while resolving method `%s' overloading `%s' in package `%s'
 
 (P) Overloading resolution over @ISA tree may be broken by importation stubs.
@@ -2340,6 +2503,11 @@ of an assignment or as a subroutine argument for example).
 (F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but a
 version of the setuid emulator somehow got run anyway.
 
+=item switching effective %s is not implemented
+
+(F) While under the C<use filetest> pragma, we cannot switch the
+real and effective uids or gids.
+
 =item syntax error
 
 (F) Probably means you had a syntax error.  Common reasons include:
@@ -2367,10 +2535,12 @@ if the error went away.  Sort of the cybernetic version of S<20 questions>.
 instead of Perl.  Check the #! line, or manually feed your script
 into Perl yourself.
 
-=item System V IPC is not implemented on this machine
+=item System V %s is not implemented on this machine
 
-(F) You tried to do something with a function beginning with "sem", "shm",
-or "msg".  See L<perlfunc/semctl>, for example.
+(F) You tried to do something with a function beginning with "sem",
+"shm", or "msg" but that System V IPC is not implemented in your
+machine.  In some machines the functionality can exist but be
+unconfigured.  Consult your system support.
 
 =item Syswrite on closed filehandle
 
@@ -2504,8 +2674,13 @@ certain type.  Arrays must be @NAME or C<@{EXPR}>.  Hashes must be
 
 =item umask: argument is missing initial 0
 
-(W) A umask of 222 is incorrect.  It should be 0222, because octal literals
-always start with 0 in Perl, as in C.
+(W) A umask of 222 is incorrect.  It should be 0222, because octal
+literals always start with 0 in Perl, as in C.
+
+=item umask not implemented
+
+(F) Your machine doesn't implement the umask function and you tried
+to use it to restrict permissions for yourself (EXPR & 0700).
 
 =item Unable to create sub named "%s"
 
@@ -2606,6 +2781,11 @@ an underbar into it.  You might also declare it as a subroutine.
 in your Perl script (or eval).  Perhaps you tried to run a compressed
 script, a binary program, or a directory as a Perl program.
 
+=item Unrecognized escape \\%c passed through
+
+(W) You used a backslash-character combination which is not recognized
+by Perl.
+
 =item Unrecognized signal name "%s"
 
 (F) You specified a signal name to the kill() function that was not recognized.
@@ -2652,18 +2832,6 @@ 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 Use of "$$<digit>" to mean "${$}<digit>" is deprecated
-
-(D) Perl versions before 5.004 misinterpreted any type marker followed
-by "$" and a digit.  For example, "$$0" was incorrectly taken to mean
-"${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
-
-However, the developers of Perl 5.004 could not fix this bug completely,
-because at least two widely-used modules depend on the old meaning of
-"$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
-old (broken) way inside strings; but it generates this message as a
-warning.  And in Perl 5.005, this special treatment will cease.
-
 =item Use of $# is deprecated
 
 (D) This was an ill-advised attempt to emulate a poorly defined B<awk> feature.
@@ -2714,6 +2882,15 @@ 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';>.
 
+=item Use of reserved word "%s" is deprecated
+
+(D) The indicated bareword is a reserved word.  Future versions of perl
+may use it as a keyword, so you're better off either explicitly quoting
+the word in a manner appropriate for its context of use, or using a
+different name altogether.  The warning can be suppressed for subroutine
+names by either adding a C<&> prefix, or using a package qualifier,
+e.g. C<&our()>, or C<Foo::our()>.
+
 =item Use of %s is deprecated
 
 (D) The construct indicated is no longer recommended for use, generally
@@ -2726,6 +2903,10 @@ bad side effects.
 interpreted as a "" or a 0, but maybe it was a mistake.  To suppress this
 warning assign an initial value to your variables.
 
+=item Useless use of "re" pragma
+
+(W) You did C<use re;> without any arguments.   That isn't very useful.
+
 =item Useless use of %s in void context
 
 (W) You did something without a side effect in a context that does nothing