[win32] merge change#904 from maintbranch
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index a138bc6..d46ff33 100644 (file)
@@ -23,7 +23,7 @@ L<perlfunc/eval>.
 
 Some of these messages are generic.  Spots that vary are denoted with a %s,
 just as in a printf format.  Note that some messages start with a %s!
-The symbols C<"%-?@> sort before the letters, while C<[> and C<\> sort after.
+The symbols C<"%(-?@> sort before the letters, while C<[> and C<\> sort after.
 
 =over 4
 
@@ -35,7 +35,7 @@ if you want to localize a package variable.
 
 =item "my" variable %s masks earlier declaration in same scope
 
-(S) A lexical variable has been redeclared in the same scope, effectively
+(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
 until the end of the scope or until all closure referents to it are
@@ -143,6 +143,12 @@ Perl yourself.
 instead of Perl.  Check the #! line, or manually feed your script
 into Perl yourself.
 
+=item         (Missing semicolon on previous line?)
+
+(S) This is an educated guess made in conjunction with the message "%s
+found where operator expected".  Don't automatically put a semicolon on
+the previous line just because you saw this message.
+
 =item B<-P> not allowed for setuid/setgid script
 
 (F) The script would have to be opened by the C preprocessor by name,
@@ -153,6 +159,12 @@ which provides a race condition that breaks security.
 (F) Perl can't peek at the stdio buffer of filehandles when it doesn't
 know about your kind of stdio.  You'll have to use a filename instead.
 
+=item C<-p> destination: %s
+
+(F) An error occurred during the implicit output invoked by the C<-p>
+command-line switch.  (This output goes to STDOUT unless you've
+redirected it with select().)
+
 =item 500 Server error
 
 See Server error.
@@ -182,7 +194,7 @@ the return value of your socket() call?  See L<perlfunc/accept>.
 
 =item Applying %s to %s will act on scalar(%s)
 
-(W) The pattern match (//), substitution (s///), and translation (tr///)
+(W) The pattern match (//), substitution (s///), and transliteration (tr///)
 operators work on scalar values.  If you apply one of them to an array
 or a hash, it will convert the array or hash to a scalar value -- the
 length of an array, or the population info of a hash -- and then work on
@@ -265,6 +277,15 @@ could indicate that SvREFCNT_dec() was called too many times, or that
 SvREFCNT_inc() was called too few times, or that the SV was mortalized
 when it shouldn't have been, or that memory has been corrupted.
 
+=item Attempt to pack pointer to temporary value
+
+(W) You tried to pass a temporary value (like the result of a
+function, or a computed expression) to the "p" pack() template.  This
+means the result contains a pointer to a location that could become
+invalid anytime, even before the end of the current statement.  Use
+literals or global values as arguments to the "p" pack() template to
+avoid this warning.
+
 =item Attempt to use reference as lvalue in substr
 
 (W) You supplied a reference as the first argument to substr() used
@@ -340,6 +361,12 @@ Perl yourself.
 subroutine identifier, in curly braces or to the left of the "=>" symbol.
 Perhaps you need to predeclare a subroutine?
 
+=item Bareword "%s" refers to nonexistent package
+
+(W) You used a qualified bareword of the form C<Foo::>, but
+the compiler saw no other uses of that namespace before that point.
+Perhaps you need to predeclare a package?
+
 =item BEGIN failed--compilation aborted
 
 (F) An untrapped exception was raised while executing a BEGIN subroutine.
@@ -374,6 +401,11 @@ like a block, except that it isn't a proper block.  This usually
 occurs if you tried to jump out of a sort() block or subroutine, which
 is a no-no.  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 loop.  You can't get there from here.  See L<perlfunc/goto>.
+
 =item Can't "last" outside a block
 
 (F) A "last" statement was executed to break out of the current block,
@@ -543,8 +575,19 @@ mention "perl" on the #! line somewhere.
 
 =item Can't execute %s
 
+(F) You used the B<-S> switch, but the copies of the script to execute found
+in the PATH did not have correct permissions.
+
+=item Can't find %s on PATH, '.' not in PATH
+
+(F) You used the B<-S> switch, but the script to execute could not be found
+in the PATH, or at least not with the correct permissions.  The script
+exists in the current directory, but PATH prohibits running it.
+
+=item Can't find %s on PATH
+
 (F) You used the B<-S> switch, but the script to execute could not be found
-in the PATH, or at least not with the correct permissions.
+in the PATH.
 
 =item Can't find label %s
 
@@ -557,7 +600,11 @@ for us to go to.  See L<perlfunc/goto>.
 the closing delimiter was omitted.  Because bracketed quotes count nesting
 levels, the following is missing its final parenthesis:
 
-    print q(The character '(' starts a side comment.)
+    print q(The character '(' starts a side comment.);
+
+If you're getting this error from a here-document, you may have 
+included unseen whitespace before or after your closing tag. A good 
+programmer's editor will have a way to help you find these characters.
 
 =item Can't fork
 
@@ -597,12 +644,17 @@ call for another.  It can't manufacture one out of whole cloth.  In general
 you should be calling it out of only an AUTOLOAD routine anyway.  See
 L<perlfunc/goto>.
 
-=item Can't localize a reference
+=item Can't goto subroutine from an eval-string
+
+(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 localize through a reference
 
-(F) You said something like C<local $$ref>, which is not allowed because
-the compiler can't determine whether $ref will end up pointing to anything
-with a symbol table entry, and a symbol table entry is necessary to
-do a local.
+(F) You said something like C<local $$ref>, which Perl can't currently
+handle, because when it goes to restore the old value of whatever $ref
+pointed to after the scope of the local() is finished, it can't be
+sure that $ref will still be a reference.  
 
 =item Can't localize lexical variable %s
 
@@ -611,9 +663,16 @@ 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 locate %s in @INC
+=item Can't locate auto/%s.al in @INC
 
-(F) You said to do (or require, or use) a file that couldn't be found in
+(F) A function (or method) was called in a package which allows autoload,
+but there is no function to autoload.  Most probable causes are a misprint
+in a function/method name or a failure to C<AutoSplit> the file, say, by
+doing C<make install>.
+
+=item Can't locate file '%s' in @INC
+
+(F) You said to do (or require, or use) a file that couldn't be found
 in any of the libraries mentioned in @INC.  Perhaps you need to set the
 PERL5LIB or PERL5OPT environment variable to say where the extra library
 is, or maybe the script needs to add the library name to @INC.  Or maybe
@@ -630,10 +689,9 @@ method, nor does any of its base classes.  See L<perlobj>.
 (W) The @ISA array contained the name of another package that doesn't seem
 to exist.
 
-=item Can't mktemp()
+=item Can't make list assignment to \%ENV on this system
 
-(F) The mktemp() routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
+(F) List assignment to %ENV is not supported on some systems, notably VMS.
 
 =item Can't modify %s in %s
 
@@ -652,8 +710,11 @@ buffer.
 
 =item Can't open %s: %s
 
-(S) An inplace edit couldn't open the original file for the indicated reason.
-Usually this is because you don't have read permission for the file.
+(S) The implicit opening of a file through use of the C<E<lt>E<gt>>
+filehandle, either implicitly under the C<-n> or C<-p> command-line
+switches, or explicitly, failed for the indicated reason.  Usually this
+is because you don't have read permission for a file which you named
+on the command line.
 
 =item Can't open bidirectional pipe
 
@@ -688,6 +749,13 @@ couldn't open the pipe into which to send data destined for stdout.
 
 (F) The script you specified can't be opened for the indicated reason.
 
+=item Can't redefine active sort subroutine %s
+
+(F) Perl optimizes the internal handling of sort subroutines and keeps
+pointers into them.  You tried to redefine one such sort subroutine when it
+was currently active, which is not allowed.  If you really want to do
+this, you should write C<sort { &func } @x> instead of C<sort func @x>.
+
 =item Can't rename %s to %s: %s, skipping file
 
 (S) The rename done by the B<-i> switch failed for some reason, probably because
@@ -720,13 +788,16 @@ of suidperl.
 
 =item Can't take log of %g
 
-(F) Logarithms are defined on only positive real numbers.
+(F) For ordinary real numbers, you can't take the logarithm of a
+negative number or zero. There's a Math::Complex package that comes
+standard with Perl, though, if you really want to do that for
+the negative numbers.
 
 =item Can't take sqrt of %g
 
 (F) For ordinary real numbers, you can't take the square root of a
-negative number.  There's a Complex package available for Perl, though,
-if you really want to do that.
+negative number.  There's a Math::Complex package that comes standard
+with Perl, though, if you really want to do that.
 
 =item Can't undef active subroutine
 
@@ -818,10 +889,22 @@ a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 an assignment operator, which implies modifying the value itself.
 Perhaps you need to copy the value to a temporary, and repeat that.
 
-=item Cannot open temporary file
+=item Cannot create temporary file "%s"
 
-(F) The create routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
+(F) A temporary file could not created for some reason while trying to
+process a B<-e> switch.  Maybe your temporary file partition is full,
+or over-protected, or clobbered.
+
+=item Cannot find an opnumber for "%s"
+
+(F) A string of a form C<CORE::word> was given to prototype(), but
+there is no builtin with the name C<word>.
+
+=item Cannot generate temporary filename
+
+(F) While trying to process a B<-e> switch, a filename for a temporary
+file could not be generated.  Maybe your temporary file partition is
+full, or over-protected, or clobbered.
 
 =item Cannot resolve method `%s' overloading `%s' in package `%s'
 
@@ -829,6 +912,30 @@ a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 opposed to a subroutine reference): no such method callable via the
 package. If method name is C<???>, this is an internal error.
 
+=item Character class syntax [. .] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[." and ending with ".]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[." and ".\]".
+
+=item Character class syntax [: :] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[:" and ":\]".
+
+=item Character class syntax [= =] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax
+beginning with "[=" and ending with "=]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[=" and "=\]".
+
 =item chmod: mode argument is missing initial 0
 
 (W) A novice will sometimes say
@@ -842,6 +949,12 @@ to 01411.  Octal constants are introduced with a leading 0 in Perl, as in C.
 
 (W) You tried to close a filehandle that was never opened.
 
+=item Compilation failed in require
+
+(F) Perl could not compile a file specified in a C<require> statement.
+Perl uses this generic message when none of the errors that it encountered
+were severe enough to halt compilation immediately.
+
 =item connect() on closed fd
 
 (W) You tried to do a connect on a closed socket.  Did you forget to check
@@ -880,10 +993,16 @@ a valid magic number.
 =item Deep recursion on subroutine "%s"
 
 (W) This subroutine has called itself (directly or indirectly) 100
-times than it has returned.  This probably indicates an infinite
+times more than it has returned.  This probably indicates an infinite
 recursion, unless you're writing strange benchmark programs, in which
 case it indicates something else.
 
+=item Delimiter for here document is too long
+
+(F) In a here document construct like C<E<lt>E<lt>FOO>, the label
+C<FOO> is too long for Perl to handle.  You have to be seriously
+twisted to write code that triggers this error.
+
 =item Did you mean &%s instead?
 
 (W) You probably referred to an imported subroutine &FOO as $FOO or some such.
@@ -943,6 +1062,13 @@ 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 Excessively long <> operator
+
+(F) The contents of a <> operator may not exceed the maximum size of a
+Perl identifier.  If you're just trying to glob a long list of
+filenames, try using the glob() operator, or put the filenames into a
+variable and glob that.
+
 =item Execution of %s aborted due to compilation errors
 
 (F) The final summary message when a Perl compilation fails.
@@ -968,6 +1094,13 @@ a goto, or a loop control statement.
 (W) You are exiting a substitution by unconventional means, such as
 a return, a goto, or a loop control statement.
 
+=item Explicit blessing to '' (assuming package main)
+
+(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');
+
 =item Fatal VMS error at %s, line %d
 
 (P) An error peculiar to VMS.  Something untoward happened in a VMS system
@@ -1092,6 +1225,13 @@ an emergency basis to prevent a core dump.
 (D) Really old Perl let you omit the % on hash names in some spots.  This
 is now heavily deprecated.
 
+=item Identifier too long
+
+(F) Perl limits identifiers (names for variables, functions, etc.) to
+about 250 characters for simple names, and somewhat more for compound
+names (like C<$A::B>).  You've exceeded Perl's limits.  Future
+versions of Perl are likely to eliminate these arbitrary limitations.
+
 =item Ill-formed logical name |%s| in prime_env_iter
 
 (W) A warning peculiar to VMS.  A logical name was encountered when preparing
@@ -1203,6 +1343,17 @@ and execute the specified command.
 
 (P) Something went badly wrong in the regular expression parser.
 
+=item internal error: glob failed
+
+(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.
+
 =item internal urp in regexp at /%s/
 
 (P) Something went badly awry in the regular expression parser.
@@ -1212,6 +1363,23 @@ and execute the specified command.
 (F) The range specified in a character class had a minimum character
 greater than the maximum character.  See L<perlre>.
 
+=item Invalid conversion in %s: "%s"
+
+(W) Perl does not understand the given format conversion.
+See L<perlfunc/sprintf>.
+
+=item Invalid type in pack: '%s'
+
+(F) The given character is not a valid pack type.  See L<perlfunc/pack>.
+(W) The given character is not a valid pack type but used to be silently
+ignored.
+
+=item Invalid type in unpack: '%s'
+
+(F) The given character is not a valid unpack type.  See L<perlfunc/unpack>.
+(W) The given character is not a valid unpack type but used to be silently
+ignored.
+
 =item ioctl is not implemented
 
 (F) Your machine apparently doesn't implement ioctl(), which is pretty
@@ -1281,12 +1449,6 @@ found where operator expected".  Often the missing operator is a comma.
 As a general rule, you'll find it's missing near the place you were last
 editing.
 
-=item Missing semicolon on previous line?
-
-(S) This is an educated guess made in conjunction with the message "%s
-found where operator expected".  Don't automatically put a semicolon on
-the previous line just because you saw this message.
-
 =item Modification of a read-only value attempted
 
 (F) You tried, directly or indirectly, to change the value of a
@@ -1549,10 +1711,17 @@ supplied it an uninitialized value.  See L<perlform>.
 
 (P) The internal pattern matching routines are out of their gourd.
 
-=item Odd number of elements in hash list
+=item Number too long
+
+(F) Perl limits the representation of decimal numbers in programs to about
+about 250 characters.  You've exceeded that length.  Future versions of
+Perl are likely to eliminate this arbitrary limitation.  In the meantime,
+try using scientific notation (e.g. "1e6" instead of "1_000_000").
+
+=item Odd number of elements in hash assignment
 
-(S) You specified an odd number of elements to a hash list, which is odd,
-because hash lists come in key/value pairs.
+(S) You specified an odd number of elements to initialize a hash, which
+is odd, because hashes come in key/value pairs.
 
 =item Offset outside string
 
@@ -1647,6 +1816,10 @@ it wasn't an eval context.
 
 (P) The internal do_trans() routine was called with invalid operational data.
 
+=item panic: frexp
+
+(P) The library function frexp() failed, making printf("%f") impossible.
+
 =item panic: goto
 
 (P) We popped the context stack to a context with the specified label,
@@ -1753,7 +1926,7 @@ was string.
 
 (P) The lexer got into a bad state while processing a case modifier.
 
-=item Pareneses missing around "%s" list
+=item Parentheses missing around "%s" list
 
 (W) You said something like
 
@@ -1791,8 +1964,7 @@ the BSD version, which takes a pid.
 (W) qw() lists contain items separated by whitespace; as with literal
 strings, comment characters are not ignored, but are instead treated
 as literal data.  (You may have used different delimiters than the
-exclamation marks parentheses shown here; braces are also frequently
-used.)
+parentheses shown here; braces are also frequently used.)
 
 You probably wrote something like this:
 
@@ -1897,11 +2069,40 @@ which is why it's currently left out of your copy.
 (F) More than 100 levels of inheritance were used.  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
+an even number of elements (for assignment to a hash). This
+usually means that you used the anon hash constructor when you meant 
+to use parens. In any case, a hash requires key/value B<pairs>.
+
+    %hash = { one => 1, two => 2, };   # WRONG
+    %hash = [ qw/ an anon array / ];   # WRONG
+    %hash = ( one => 1, two => 2, );   # right
+    %hash = qw( one 1 two 2 );                 # also fine
+
+=item Reference found where even-sized list expected
+
+(W) You gave a single reference where Perl was expecting a list with
+an even number of elements (for assignment to a hash). This
+usually means that you used the anon hash constructor when you meant 
+to use parens. In any case, a hash requires key/value B<pairs>.
+
+    %hash = { one => 1, two => 2, };   # WRONG
+    %hash = [ qw/ an anon array / ];   # WRONG
+    %hash = ( one => 1, two => 2, );   # right
+    %hash = qw( one 1 two 2 );                 # also fine
+
 =item Reference miscount in sv_replace()
 
 (W) The internal sv_replace() function was handed a new SV with a
 reference count of other than 1.
 
+=item regexp *+ operand could be empty
+
+(F) The part of the regexp subject to either the * or + quantifier
+could match an empty string.
+
 =item regexp memory corruption
 
 (P) The regular expression engine got confused by what the regular
@@ -1969,11 +2170,12 @@ or setgid bit set.  This doesn't make much sense.
 
 (F) The lexer couldn't find the final delimiter of a // or m{}
 construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading C<$> from a variable C<$m> may cause this error.
 
-=item seek() on unopened file
+=item %sseek() on unopened file
 
-(W) You tried to use the seek() function on a filehandle that was either
-never opened or has since been closed.
+(W) You tried to use the seek() or sysseek() function on a filehandle that
+was either never opened or has since been closed.
 
 =item select not implemented
 
@@ -1998,6 +2200,11 @@ or possibly some other missing operator, such as a comma.
 (W) The filehandle you're sending to got itself closed sometime before now.
 Check your logic flow.
 
+=item Sequence (? incomplete
+
+(F) A regular expression ended with an incomplete extension (?.
+See L<perlre>.
+
 =item Sequence (?#... not terminated
 
 (F) A regular expression comment must be terminated by a closing
@@ -2052,7 +2259,7 @@ think so.
 
 =item setruid() not implemented
 
-(F) You tried to assign to C<$<lt>>, and your operating system doesn't support
+(F) You tried to assign to C<$E<lt>>, and your operating system doesn't support
 the setruid() system call (or equivalent), or at least Configure didn't
 think so.
 
@@ -2135,17 +2342,21 @@ L<perlop/"Quote and Quote-like Operators">.
 
 (F) The lexer couldn't find the interior delimiter of a s/// or s{}{}
 construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading C<$> from variable C<$s> may cause this error.
 
 =item Substitution replacement not terminated
 
 (F) The lexer couldn't find the final delimiter of a s/// or s{}{}
 construct.  Remember that bracketing delimiters count nesting level.
+Missing the leading C<$> from variable C<$s> may cause this error.
 
 =item substr outside of string
 
-(W) You tried to reference a substr() that pointed outside of a string.
-That is, the absolute value of the offset was larger than the length of
-the string.  See L<perlfunc/substr>.
+(S),(W) You tried to reference a substr() that pointed outside of a
+string.  That is, the absolute value of the offset was larger than the
+length of the string.  See L<perlfunc/substr>.  This warning is
+mandatory if substr is used in an lvalue context (as the left hand side
+of an assignment or as a subroutine argument for example).
 
 =item suidperl is no longer needed since %s
 
@@ -2189,6 +2400,11 @@ or "msg".  See L<perlfunc/semctl>, for example.
 (W) The filehandle you're writing to got itself closed sometime before now.
 Check your logic flow.
 
+=item Target of goto is too deeply nested
+
+(F) You tried to use C<goto> to reach a label that was too deeply
+nested for Perl to reach.  Perl is doing you a favor by refusing.
+
 =item tell() on unopened file
 
 (W) You tried to use the tell() function on a filehandle that was either
@@ -2246,10 +2462,10 @@ system call to call, silly dilly.
 =item Too late for "B<-T>" option
 
 (X) The #! line (or local equivalent) in a Perl script contains the
-B<-T> option, but Perl was not invoked with B<-T> in its argument
-list.  This is an error because, by the time Perl discovers a B<-T> in
-a script, it's too late to properly taint everything from the
-environment.  So Perl gives up.
+B<-T> option, but Perl was not invoked with B<-T> in its command line.
+This is an error because, by the time Perl discovers a B<-T> in a
+script, it's too late to properly taint everything from the environment.
+So Perl gives up.
 
 If the Perl script is being executed as a command using the #!
 mechanism (or its local equivalent), this error can usually be fixed
@@ -2259,6 +2475,12 @@ first argument: e.g. change C<perl -n -T> to C<perl -T -n>.
 If the Perl script is being executed as C<perl scriptname>, then the
 B<-T> option must appear on the command line: C<perl -T scriptname>.
 
+=item Too late for "-%s" option
+
+(X) The #! line (or local equivalent) in a Perl script contains the
+B<-M> or B<-m> option.  This is an error because B<-M> and B<-m> options
+are not intended for use inside scripts.  Use the C<use> pragma instead.
+
 =item Too many ('s
 
 =item Too many )'s
@@ -2280,12 +2502,13 @@ Perl yourself.
 (F) The regular expression ends with an unbackslashed backslash.  Backslash
 it.   See L<perlre>.
 
-=item Translation pattern not terminated
+=item Transliteration pattern not terminated
 
 (F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
-construct.
+or y/// or y[][] construct.  Missing the leading C<$> from variables
+C<$tr> or C<$y> may cause this error.
 
-=item Translation replacement not terminated
+=item Transliteration replacement not terminated
 
 (F) The lexer couldn't find the final delimiter of a tr/// or tr[][]
 construct.
@@ -2361,6 +2584,11 @@ have been defined yet.  See L<perlfunc/sort>.
 (F) The format indicated doesn't seem to exist.  Perhaps it's really in
 another package?  See L<perlform>.
 
+=item Undefined value assigned to typeglob
+
+(W) An undefined value was assigned to a typeglob, a la C<*foo = undef>.
+This does nothing.  It's possible that you really mean C<undef *foo>.
+
 =item unexec of %s into %s failed!
 
 (F) The unexec() routine failed for some reason.  See your local FSF
@@ -2406,7 +2634,7 @@ script, a binary program, or a directory as a Perl program.
 (F) You specified a signal name to the kill() function that was not recognized.
 Say C<kill -l> in your shell to see the valid signal names on your system.
 
-=item Unrecognized switch: -%s
+=item Unrecognized switch: -%s  (-h will show valid options)
 
 (F) You specified an illegal option to Perl.  Don't do that.
 (If you think you didn't do that, check the #! line to see if it's
@@ -2432,7 +2660,7 @@ the name you call Perl by to C<perl_>, C<perl__>, and so on.
 
 =item Unsupported function %s
 
-(F) This machines doesn't implement the indicated function, apparently.
+(F) This machine doesn't implement the indicated function, apparently.
 At least, Configure doesn't think so.
 
 =item Unsupported socket function "%s" called
@@ -2447,6 +2675,18 @@ 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.
@@ -2454,7 +2694,7 @@ Use an explicit printf() or sprintf() instead.
 
 =item Use of $* is deprecated
 
-(D) This variable magically turned on multiline pattern matching, both for
+(D) This variable magically turned on multi-line pattern matching, both for
 you and for any luckless subroutine that you happen to call.  You should
 use the new C<//m> and C<//s> modifiers now to do that without the dangerous
 action-at-a-distance effects of C<$*>.
@@ -2464,12 +2704,6 @@ action-at-a-distance effects of C<$*>.
 (F) You attempted to use a feature of printf that is accessible from
 only C.  This usually means there's a better way to do it in Perl.
 
-=item Use of %s is deprecated
-
-(D) The construct indicated is no longer recommended for use, generally
-because there's a better way to do it, and also because the old way has
-bad side effects.
-
 =item Use of bare E<lt>E<lt> to mean E<lt>E<lt>"" is deprecated
 
 (D) You are now encouraged to use the explicitly quoted form if you
@@ -2481,6 +2715,34 @@ wish to use an empty line as the terminator of the here-document.
 subroutine's argument list, so it's better if you assign the results of
 a split() explicitly to an array (or list).
 
+=item Use of inherited AUTOLOAD for non-method %s() is deprecated
+
+(D) 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-E<gt>bar()> or C<$obj-E<gt>bar()>).
+
+This bug will be rectified in Perl 5.005, which will use 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 5.004 issues an optional warning when non-methods
+use inherited C<AUTOLOAD>s.
+
+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.
+
+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 %s is deprecated
+
+(D) The construct indicated is no longer recommended for use, generally
+because there's a better way to do it, and also because the old way has
+bad side effects.
+
 =item Use of uninitialized value
 
 (W) An undefined value was used as if it were already defined.  It was
@@ -2589,6 +2851,27 @@ variables.
 of Perl.  Check the #! line, or manually feed your script into
 Perl yourself.
 
+=item perl: warning: Setting locale failed.
+
+(S) The whole warning message will look something like:
+
+       perl: warning: Setting locale failed.
+       perl: warning: Please check that your locale settings:
+               LC_ALL = "En_US",
+               LANG = (unset)
+           are supported and installed on your system.
+       perl: warning: Falling back to the standard locale ("C").
+
+Exactly what were the failed locale settings varies.  In the above the
+settings were that the LC_ALL was "En_US" and the LANG had no value.
+This error means that Perl detected that you and/or your system
+administrator have set up the so-called variable system but Perl could
+not use those settings.  This was not dead serious, fortunately: there
+is a "default locale" called "C" that Perl can and will use, the
+script will be run.  Before you really fix the problem, however, you
+will get the same error message each time you run Perl.  How to really
+fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>.
+
 =item Warning: something's wrong
 
 (W) You passed warn() an empty string (the equivalent of C<warn "">) or
@@ -2703,7 +2986,7 @@ version of Perl, and this should not happen anyway.
 
 =item Malformed PERLLIB_PREFIX
 
-(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
+(F) An error peculiar to OS/2.  PERLLIB_PREFIX should be of the form
 
     prefix1;prefix2
 
@@ -2711,21 +2994,23 @@ or
 
     prefix1 prefix2
 
-with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix of
-a builtin library search path, prefix2 is substituted. The error may appear
-if components are not found, or are too long. See L<perlos2/"PERLLIB_PREFIX">.
+with nonempty prefix1 and prefix2.  If C<prefix1> is indeed a prefix
+of a builtin library search path, prefix2 is substituted.  The error
+may appear if components are not found, or are too long.  See
+"PERLLIB_PREFIX" in F<README.os2>.
 
 =item PERL_SH_DIR too long
 
 (F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
-C<sh>-shell in. See L<perlos2/"PERL_SH_DIR">.
+C<sh>-shell in.  See "PERL_SH_DIR" in F<README.os2>.
 
 =item Process terminated by SIG%s
 
 (W) This is a standard message issued by OS/2 applications, while *nix
-applications die in silence. It is considered a feature of the OS/2
-port. One can easily disable this by appropriate sighandlers, see
-L<perlipc/"Signals">.  See L<perlos2/"Process terminated by SIGTERM/SIGINT">.
+applications die in silence.  It is considered a feature of the OS/2
+port.  One can easily disable this by appropriate sighandlers, see
+L<perlipc/"Signals">.  See also "Process terminated by SIGTERM/SIGINT"
+in F<README.os2>.
 
 =back