add ck_sysread() for better sysread/read/recv sanity
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 0152662..7c8ab3d 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.
@@ -176,13 +188,9 @@ 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 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 +273,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
@@ -299,6 +316,16 @@ system malloc().
 
 (P) One of the internal hash routines was passed a null HV pointer.
 
+=item Bad index while coercing array into hash
+
+(F) A field name of a typed variable was looked up in the %FIELDS
+hash, but the index found was not legal, i.e. less than 1.
+
+=item Bad index while coercing array into hash
+
+(F) The index looked up in the hash found as 0'th element of the array
+is not legal.  Index values must be at 1 or greater.
+
 =item Bad name after %s::
 
 (F) You started to name a symbol by using a package prefix, and then didn't
@@ -340,6 +367,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 +407,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,
@@ -464,6 +502,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
@@ -543,8 +587,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 +612,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 +656,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.)
 
-(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.
+=item Can't localize through a reference
+
+(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,6 +675,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 locate auto/%s.al in @INC
+
+(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 %s in @INC
 
 (F) You said to do (or require, or use) a file that couldn't be found
@@ -630,10 +701,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 +722,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 +761,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 +800,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
 
@@ -752,6 +835,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.
@@ -807,21 +896,16 @@ weren't.
 subscript.  But to the left of the brackets was an expression that
 didn't look like an array reference, or anything else subscriptable.
 
-=item Can't write to temp file for B<-e>: %s
-
-(F) The write routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
-
 =item Can't x= to read-only value
 
 (F) You tried to repeat a constant value (often the undefined value) with
 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 find an opnumber for "%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 string of a form C<CORE::word> was given to prototype(), but
+there is no builtin with the name C<word>.
 
 =item Cannot resolve method `%s' overloading `%s' in package `%s'
 
@@ -829,6 +913,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
@@ -886,10 +994,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.
@@ -949,6 +1063,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.
@@ -974,6 +1095,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
@@ -1098,6 +1226,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
@@ -1145,6 +1280,12 @@ don't take to this kindly.
 (W) You may have tried to use an 8 or 9 in a octal number.  Interpretation
 of the octal number stopped before the 8 or 9.
 
+=item Illegal hex digit ignored
+
+(W) You may have tried to use a character other than 0 - 9 or A - F in a
+hexadecimal number.  Interpretation of the hexadecimal number stopped
+before the illegal character.
+
 =item Illegal switch in PERL5OPT: %s
 
 (X) The PERL5OPT environment variable may only be used to set the
@@ -1176,10 +1317,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>.
 
@@ -1229,6 +1371,23 @@ C<./Configure -S> and rebuild Perl.
 (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
@@ -1298,12 +1457,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
@@ -1464,6 +1617,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
@@ -1566,10 +1732,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").
 
-(S) You specified an odd number of elements to a hash list, which is odd,
-because hash lists come in key/value pairs.
+=item Odd number of elements in hash assignment
+
+(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
 
@@ -1586,7 +1759,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
@@ -1607,7 +1780,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.
@@ -1618,13 +1791,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.
@@ -1664,6 +1843,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,
@@ -1770,7 +1953,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
 
@@ -1808,8 +1991,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:
 
@@ -1894,6 +2076,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.
@@ -1909,16 +2098,38 @@ 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
+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
@@ -1986,11 +2197,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
 
@@ -2015,6 +2227,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
@@ -2069,7 +2286,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.
 
@@ -2141,6 +2358,21 @@ may break this.
        eval "sub name { ... }";
     }
 
+=item Subroutine %s hidden by keyword; use ampersand
+
+(W) You are trying to call a subroutine that has the same name as a
+keyword.  However, because the subroutine is not imported and
+you're not using an ampersand, Perl won't call the subroutine.
+
+To force 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).
+
+If the Perl operator is what you want, then eliminate this warning by
+using the CORE:: prefix on the operator (e.g. CORE::log($x)) or by
+declaring the subroutine to be an object method (see L<attrs>).
+
 =item Substitution loop
 
 (P) The substitution was looping infinitely.  (Obviously, a
@@ -2152,17 +2384,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
 
@@ -2206,6 +2442,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
@@ -2303,12 +2544,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.
@@ -2384,6 +2626,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
@@ -2429,7 +2676,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
@@ -2455,7 +2702,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
@@ -2515,7 +2762,7 @@ a split() explicitly to an array (or list).
 (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->bar()> or C<$obj->bar()>).
+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
@@ -2528,6 +2775,19 @@ 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 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
@@ -2642,6 +2902,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