Add in perldelta changes about unpack A and trailing whitespace, trie
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 0d5abdc..0f71025 100644 (file)
@@ -790,7 +790,7 @@ L<perlfunc/last>.
 may either mean that you upgraded your version of perl to one that is
 incompatible with your old dynamic extensions (which is known to happen
 between major versions of perl), or (more likely) that your dynamic
-extension was build against an older version of the library that is
+extension was built against an older version of the library that is
 installed on your system. You may need to rebuild your old dynamic
 extensions.
 
@@ -934,6 +934,10 @@ for stdout.
 
 (F) The script you specified can't be opened for the indicated reason.
 
+If you're debugging a script that uses #!, and normally relies on the
+shell's $PATH search, the -S option causes perl to do that search, so
+you don't have to type the path or C<`which $scriptname`>.
+
 =item Can't read CRTL environ
 
 (S) A warning peculiar to VMS.  Perl tried to read an element of %ENV
@@ -1051,13 +1055,6 @@ indicates that such a conversion was attempted.
 upgradability.  Upgrading to undef indicates an error in the code
 calling sv_upgrade.
 
-=item Can't use '%c' in a group with different byte-order in %s
-
-(F) You attempted to force a different byte-order on a type
-that is already inside a group with a byte-order modifier.
-For example you cannot force little-endianness on a type that
-is inside a big-endian group.
-
 =item Can't use anonymous symbol table for method lookup
 
 (F) The internal routine that does method lookup was handed a symbol
@@ -1099,6 +1096,13 @@ is not allowed, because the magic can be tied to only one location
 have variables in your program that looked like magical variables but
 weren't.
 
+=item Can't use '%c' in a group with different byte-order in %s
+
+(F) You attempted to force a different byte-order on a type
+that is already inside a group with a byte-order modifier.
+For example you cannot force little-endianness on a type that
+is inside a big-endian group.
+
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
@@ -1144,7 +1148,7 @@ references can be weakened.
 with an assignment operator, which implies modifying the value itself.
 Perhaps you need to copy the value to a temporary, and repeat that.
 
-=item Character in "C" format wrapped in pack
+=item Character in 'C' format wrapped in pack
 
 (W pack) You said
 
@@ -1159,7 +1163,19 @@ and so on) and not for Unicode characters, so Perl behaved as if you meant
 If you actually want to pack Unicode codepoints, use the C<"U"> format
 instead.
 
-=item Character in "c" format wrapped in pack
+=item Character in 'W' format wrapped in pack
+
+(W pack) You said
+
+    pack("U0W", $x)
+
+where $x is either less than 0 or more than 255. However, C<U0>-mode expects
+all values to fall in the interval [0, 255], so Perl behaved as if you
+meant:
+
+    pack("U0W", $x & 255)
+
+=item Character in 'c' format wrapped in pack
 
 (W pack) You said
 
@@ -1174,6 +1190,42 @@ and so on) and not for Unicode characters, so Perl behaved as if you meant
 If you actually want to pack Unicode codepoints, use the C<"U"> format
 instead.
 
+=item Character in '%c' format wrapped in unpack
+
+(W unpack) You tried something like
+
+   unpack("H", "\x{2a1}")
+
+where the format expects to process a byte (a character with a value 
+below 256), but a higher value was provided instead. Perl uses the value
+modulus 256 instead, as if you had provided:
+
+   unpack("H", "\x{a1}")
+
+=item Character(s) in '%c' format wrapped in pack
+
+(W pack) You tried something like
+
+   pack("u", "\x{1f3}b")
+
+where the format expects to process a sequence of bytes (character with a 
+value below 256), but some of the characters had a higher value. Perl 
+uses the character values modulus 256 instead, as if you had provided:
+
+   pack("u", "\x{f3}b")
+
+=item Character(s) in '%c' format wrapped in unpack
+
+(W unpack) You tried something like
+
+   unpack("s", "\x{1f3}b")
+
+where the format expects to process a sequence of bytes (character with a 
+value below 256), but some of the characters had a higher value. Perl 
+uses the character values modulus 256 instead, as if you had provided:
+
+   unpack("s", "\x{f3}b")
+
 =item close() on unopened filehandle %s
 
 (W unopened) You tried to close a filehandle that was never opened.
@@ -1321,6 +1373,22 @@ there are neither package declarations nor a C<$VERSION>.
 long for Perl to handle.  You have to be seriously twisted to write code
 that triggers this error.
 
+=item Deprecated use of my() in false conditional
+
+(D deprecated) You used a declaration similar to C<my $x if 0>.
+There has been a long-standing bug in Perl that causes a lexical variable
+not to be cleared at scope exit when its declaration includes a false
+conditional. Some people have exploited this bug to achieve a kind of
+static variable. Since we intend to fix this bug, we don't want people
+relying on this behavior. You can achieve a similar static effect by
+declaring the variable in a separate block outside the function, eg
+    
+    sub f { my $x if 0; return $x++ }
+
+becomes
+
+    { my $x; sub f { return $x++ } }
+
 =item DESTROY created new reference to dead object '%s'
 
 (F) A DESTROY() method created a new reference to the object which is
@@ -1540,6 +1608,13 @@ you which section of the Perl source code is distressed.
 (F) Your machine apparently doesn't implement fcntl().  What is this, a
 PDP-11 or something?
 
+=item Field too wide in 'u' format in pack
+
+(W pack) Each line in an uuencoded string start with a length indicator
+which can't encode values above 63. So there is no point in asking for
+a line length bigger than that. Perl will behave as if you specified
+C<u63> as format.
+
 =item Filehandle %s opened only for input
 
 (W io) You tried to write on a read-only filehandle.  If you intended
@@ -1834,7 +1909,8 @@ L<perlsec> for more information.
 
 (F) You can't use system(), exec(), or a piped open in a setuid or
 setgid script if C<$ENV{PATH}> contains a directory that is writable by
-the world.  See L<perlsec>.
+the world.  Also, the PATH must not contain any relative directory.
+See L<perlsec>.
 
 =item Insecure $ENV{%s} while running %s
 
@@ -2081,7 +2157,7 @@ when the function is called.
 
 =item Malformed UTF-8 character (%s)
 
-Perl detected something that didn't comply with UTF-8 encoding rules.
+(W utf8) Perl detected something that didn't comply with UTF-8 encoding rules.
 
 One possible cause is that you read in data that you thought to be in
 UTF-8 but it wasn't (it was for example legacy 8-bit data).  Another
@@ -2092,6 +2168,21 @@ possibility is careless use of utf8::upgrade().
 Perl thought it was reading UTF-16 encoded character data but while
 doing it Perl met a malformed Unicode surrogate.
 
+=item Malformed UTF-8 string in pack
+
+(F) You tried to pack something that didn't comply with UTF-8 encoding
+rules and perl was unable to guess how to make more progress.
+
+=item Malformed UTF-8 string in unpack
+
+(F) You tried to unpack something that didn't comply with UTF-8 encoding
+rules and perl was unable to guess how to make more progress.
+
+=item Malformed UTF-8 string in '%c' format in unpack
+
+(F) You tried to unpack something that didn't comply with UTF-8 encoding
+rules and perl was unable to guess how to make more progress.
+
 =item %s matches null string many times in regex; marked by <-- HERE in m/%s/
 
 (W regexp) The pattern you've specified would be an infinite loop if the
@@ -2131,6 +2222,11 @@ ended earlier on the current line.
 (W syntax) An underscore (underbar) in a numeric constant did not
 separate two digits.
 
+=item Missing argument to -%c
+
+(F) The argument to the indicated command line switch must follow
+immediately after the switch, without intervening spaces.
+
 =item Missing %sbrace%s on \N{}
 
 (F) Wrong syntax of character name literal C<\N{charname}> within
@@ -2240,12 +2336,6 @@ See L<perlfunc/open> for details.
 (W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>.
 They're written like C<$foo[1][2][3]>, as in C.
 
-=item '/' must be followed by 'a*', 'A*' or 'Z*'
-
-(F) You had a pack template indicating a counted-length string,
-Currently the only things that can have their length counted are a*, A*
-or Z*.  See L<perlfunc/pack>.
-
 =item '/' must follow a numeric type in unpack
 
 (F) You had an unpack template that contained a '/', but this did not
@@ -2304,15 +2394,6 @@ C<??> appear to be nested quantifiers, but aren't.  See L<perlre>.
 (S internal) The symbol in question was declared but somehow went out of
 scope before it could possibly have been used.
 
-=item Newline in left-justified string for %s
-
-(W printf) There is a newline in a string to be left justified by 
-C<printf> or C<sprintf>.
-
-The padding spaces will appear after the newline, which is probably not
-what you wanted.  Usually you should remove the newline from the string 
-and put formatting characters in the C<sprintf> format.
-
 =item No %s allowed while running setuid
 
 (F) Certain operations are deemed to be too insecure for a setuid or
@@ -2428,16 +2509,17 @@ your system.
 (F) Configure didn't find anything resembling the setreuid() call for
 your system.
 
-=item No space allowed after -%c
-
-(F) The argument to the indicated command line switch must follow
-immediately after the switch, without intervening spaces.
-
 =item No %s specified for -%c
 
 (F) The indicated command line switch needs a mandatory argument, but
 you haven't specified one.
 
+=item No such class field "%s" in variable %s of type %s
+
+(F) You tried to access a key from a hash through the indicated typed variable
+but that key is not allowed by the package of the same type.  The indicated
+package has restricted the set of allowed keys using the L<fields> pragma.
+
 =item No such class %s
 
 (F) You provided a class qualifier in a "my" or "our" declaration, but
@@ -2656,6 +2738,11 @@ C<limit datasize n> (where C<n> is the number of kilobytes) to check
 the current limits and change them, and in ksh/bash/zsh use C<ulimit -a>
 and C<ulimit -d n>, respectively.
 
+=item Out of memory during %s extend
+
+(X) An attempt was made to extend an array, a list, or a string beyond
+the largest possible memory allocation.
+
 =item Out of memory during "large" request for %s
 
 (F) The malloc() function returned 0, indicating there was insufficient
@@ -2663,11 +2750,6 @@ 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 %s extend
-
-(X) An attempt was made to extend an array, a list, or a string beyond
-the largest possible memory allocation.
-
 =item Out of memory during request for %s
 
 (X|F) The malloc() function returned 0, indicating there was
@@ -2698,6 +2780,12 @@ otherwise.
 (F) You had a template that specified an absolute position outside
 the string being unpacked.  See L<perlfunc/pack>.
 
+=item '@' outside of string with malformed UTF-8 in unpack
+
+(F) You had a template that specified an absolute position outside
+the string being unpacked. The string being unpacked was also invalid
+UTF-8. See L<perlfunc/pack>.
+
 =item %s package attribute may clash with future reserved word: %s
 
 (W reserved) A lowercase attribute name was used that had a
@@ -2921,12 +3009,6 @@ redirected it with select().)
 "Can't locate object method \"%s\" via package \"%s\"".  It often means
 that a method requires a package that has not been loaded.
 
-=item Perl %s required--this is only version %s, stopped
-
-(F) The module in question uses features of a version of Perl more
-recent than the currently running version.  How long has it been since
-you upgraded, anyway?  See L<perlfunc/require>.
-
 =item Perl_my_%s() not available
 
 (F) Your platform has very uncommon byte-order and integer size,
@@ -2934,6 +3016,12 @@ so it was not possible to set up some or all fixed-width byte-order
 conversion functions.  This is only a problem when you're using the
 '<' or '>' modifiers in (un)pack templates.  See L<perlfunc/pack>.
 
+=item Perl %s required--this is only version %s, stopped
+
+(F) The module in question uses features of a version of Perl more
+recent than the currently running version.  How long has it been since
+you upgraded, anyway?  See L<perlfunc/require>.
+
 =item PERL_SH_DIR too long
 
 (F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
@@ -3482,6 +3570,11 @@ L<perlfunc/setsockopt>.
 (F) The setuid emulator won't run a script that is writable by the
 world, because the world might have written on it already.
 
+=item Setuid script not plain file
+
+(F) The setuid emulator won't run a script that isn't read from a file,
+but from a socket, a pipe or another device.
+
 =item shm%s not implemented
 
 (F) You don't have System V shared memory IPC on your system.
@@ -3761,6 +3854,22 @@ target of the change to
 (F) Your version of the C library apparently doesn't do times().  I
 suspect you're not running on Unix.
 
+=item "-T" is on the #! line, it must also be used on the command line
+
+(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 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 by
+editing the #! line so that the B<-T> option is a part of Perl's 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 To%s: illegal mapping '%s'
 
 (F) You tried to define a customized To-mapping for lc(), lcfirst,
@@ -3783,22 +3892,6 @@ system call to call, silly dilly.
 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 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 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 by
-editing the #! line so that the B<-T> option is a part of Perl's 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 to run %s block
 
 (W void) A CHECK or INIT block is being defined during run time proper,
@@ -4343,22 +4436,6 @@ old way has bad side effects.
 it already went past any symlink you are presumably trying to look for.
 The operation returned C<undef>.  Use a filename instead.
 
-=item Deprecated use of my() in false conditional
-
-(D deprecated) You used a declaration similar to C<my $x if 0>.
-There has been a long-standing bug in Perl that causes a lexical variable
-not to be cleared at scope exit when its declaration includes a false
-conditional. Some people have exploited this bug to achieve a kind of
-static variable. Since we intend to fix this bug, we don't want people
-relying on this behavior. You can achieve a similar static effect by
-declaring the variable in a separate block outside the function, eg
-    
-    sub f { my $x if 0; return $x++ }
-
-becomes
-
-    { my $x; sub f { return $x++ } }
-
 =item Use of "package" with no arguments is deprecated
 
 (D deprecated) You used the C<package> keyword without specifying a package