[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  perl5004delta - what's new for perl5.004
   4  
   5  =head1 DESCRIPTION
   6  
   7  This document describes differences between the 5.003 release (as
   8  documented in I<Programming Perl>, second edition--the Camel Book) and
   9  this one.
  10  
  11  =head1 Supported Environments
  12  
  13  Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2,
  14  QNX, AmigaOS, and Windows NT.  Perl runs on Windows 95 as well, but it
  15  cannot be built there, for lack of a reasonable command interpreter.
  16  
  17  =head1 Core Changes
  18  
  19  Most importantly, many bugs were fixed, including several security
  20  problems.  See the F<Changes> file in the distribution for details.
  21  
  22  =head2 List assignment to %ENV works
  23  
  24  C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS
  25  where it generates a fatal error).
  26  
  27  =head2 Change to "Can't locate Foo.pm in @INC" error
  28  
  29  The error "Can't locate Foo.pm in @INC" now lists the contents of @INC
  30  for easier debugging.
  31  
  32  =head2 Compilation option: Binary compatibility with 5.003
  33  
  34  There is a new Configure question that asks if you want to maintain
  35  binary compatibility with Perl 5.003.  If you choose binary
  36  compatibility, you do not have to recompile your extensions, but you
  37  might have symbol conflicts if you embed Perl in another application,
  38  just as in the 5.003 release.  By default, binary compatibility
  39  is preserved at the expense of symbol table pollution.
  40  
  41  =head2 $PERL5OPT environment variable
  42  
  43  You may now put Perl options in the $PERL5OPT environment variable.
  44  Unless Perl is running with taint checks, it will interpret this
  45  variable as if its contents had appeared on a "#!perl" line at the
  46  beginning of your script, except that hyphens are optional.  PERL5OPT
  47  may only be used to set the following switches: B<-[DIMUdmw]>.
  48  
  49  =head2 Limitations on B<-M>, B<-m>, and B<-T> options
  50  
  51  The C<-M> and C<-m> options are no longer allowed on the C<#!> line of
  52  a script.  If a script needs a module, it should invoke it with the
  53  C<use> pragma.
  54  
  55  The B<-T> option is also forbidden on the C<#!> line of a script,
  56  unless it was present on the Perl command line.  Due to the way C<#!>
  57  works, this usually means that B<-T> must be in the first argument.
  58  Thus:
  59  
  60      #!/usr/bin/perl -T -w
  61  
  62  will probably work for an executable script invoked as C<scriptname>,
  63  while:
  64  
  65      #!/usr/bin/perl -w -T
  66  
  67  will probably fail under the same conditions.  (Non-Unix systems will
  68  probably not follow this rule.)  But C<perl scriptname> is guaranteed
  69  to fail, since then there is no chance of B<-T> being found on the
  70  command line before it is found on the C<#!> line.
  71  
  72  =head2 More precise warnings
  73  
  74  If you removed the B<-w> option from your Perl 5.003 scripts because it
  75  made Perl too verbose, we recommend that you try putting it back when
  76  you upgrade to Perl 5.004.  Each new perl version tends to remove some
  77  undesirable warnings, while adding new warnings that may catch bugs in
  78  your scripts.
  79  
  80  =head2 Deprecated: Inherited C<AUTOLOAD> for non-methods
  81  
  82  Before Perl 5.004, C<AUTOLOAD> functions were looked up as methods
  83  (using the C<@ISA> hierarchy), even when the function to be autoloaded
  84  was called as a plain function (e.g. C<Foo::bar()>), not a method
  85  (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
  86  
  87  Perl 5.005 will use method lookup only for methods' C<AUTOLOAD>s.
  88  However, there is a significant base of existing code that may be using
  89  the old behavior.  So, as an interim step, Perl 5.004 issues an optional
  90  warning when a non-method uses an inherited C<AUTOLOAD>.
  91  
  92  The simple rule is:  Inheritance will not work when autoloading
  93  non-methods.  The simple fix for old code is:  In any module that used to
  94  depend on inheriting C<AUTOLOAD> for non-methods from a base class named
  95  C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup.
  96  
  97  =head2 Previously deprecated %OVERLOAD is no longer usable
  98  
  99  Using %OVERLOAD to define overloading was deprecated in 5.003.
 100  Overloading is now defined using the overload pragma. %OVERLOAD is
 101  still used internally but should not be used by Perl scripts. See
 102  L<overload> for more details.
 103  
 104  =head2 Subroutine arguments created only when they're modified
 105  
 106  In Perl 5.004, nonexistent array and hash elements used as subroutine
 107  parameters are brought into existence only if they are actually
 108  assigned to (via C<@_>).
 109  
 110  Earlier versions of Perl vary in their handling of such arguments.
 111  Perl versions 5.002 and 5.003 always brought them into existence.
 112  Perl versions 5.000 and 5.001 brought them into existence only if
 113  they were not the first argument (which was almost certainly a bug).
 114  Earlier versions of Perl never brought them into existence.
 115  
 116  For example, given this code:
 117  
 118       undef @a; undef %a;
 119       sub show { print $_[0] };
 120       sub change { $_[0]++ };
 121       show($a[2]);
 122       change($a{b});
 123  
 124  After this code executes in Perl 5.004, $a{b} exists but $a[2] does
 125  not.  In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed
 126  (but $a[2]'s value would have been undefined).
 127  
 128  =head2 Group vector changeable with C<$)>
 129  
 130  The C<$)> special variable has always (well, in Perl 5, at least)
 131  reflected not only the current effective group, but also the group list
 132  as returned by the C<getgroups()> C function (if there is one).
 133  However, until this release, there has not been a way to call the
 134  C<setgroups()> C function from Perl.
 135  
 136  In Perl 5.004, assigning to C<$)> is exactly symmetrical with examining
 137  it: The first number in its string value is used as the effective gid;
 138  if there are any numbers after the first one, they are passed to the
 139  C<setgroups()> C function (if there is one).
 140  
 141  =head2 Fixed parsing of $$<digit>, &$<digit>, etc.
 142  
 143  Perl versions before 5.004 misinterpreted any type marker followed by
 144  "$" and a digit.  For example, "$$0" was incorrectly taken to mean
 145  "${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
 146  
 147  However, the developers of Perl 5.004 could not fix this bug completely,
 148  because at least two widely-used modules depend on the old meaning of
 149  "$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
 150  old (broken) way inside strings; but it generates this message as a
 151  warning.  And in Perl 5.005, this special treatment will cease.
 152  
 153  =head2 Fixed localization of $<digit>, $&, etc.
 154  
 155  Perl versions before 5.004 did not always properly localize the
 156  regex-related special variables.  Perl 5.004 does localize them, as
 157  the documentation has always said it should.  This may result in $1,
 158  $2, etc. no longer being set where existing programs use them.
 159  
 160  =head2 No resetting of $. on implicit close
 161  
 162  The documentation for Perl 5.0 has always stated that C<$.> is I<not>
 163  reset when an already-open file handle is reopened with no intervening
 164  call to C<close>.  Due to a bug, perl versions 5.000 through 5.003
 165  I<did> reset C<$.> under that circumstance; Perl 5.004 does not.
 166  
 167  =head2 C<wantarray> may return undef
 168  
 169  The C<wantarray> operator returns true if a subroutine is expected to
 170  return a list, and false otherwise.  In Perl 5.004, C<wantarray> can
 171  also return the undefined value if a subroutine's return value will
 172  not be used at all, which allows subroutines to avoid a time-consuming
 173  calculation of a return value if it isn't going to be used.
 174  
 175  =head2 C<eval EXPR> determines value of EXPR in scalar context
 176  
 177  Perl (version 5) used to determine the value of EXPR inconsistently,
 178  sometimes incorrectly using the surrounding context for the determination.
 179  Now, the value of EXPR (before being parsed by eval) is always determined in
 180  a scalar context.  Once parsed, it is executed as before, by providing
 181  the context that the scope surrounding the eval provided.  This change
 182  makes the behavior Perl4 compatible, besides fixing bugs resulting from
 183  the inconsistent behavior.  This program:
 184  
 185      @a = qw(time now is time);
 186      print eval @a;
 187      print '|', scalar eval @a;
 188  
 189  used to print something like "timenowis881399109|4", but now (and in perl4)
 190  prints "4|4".
 191  
 192  =head2 Changes to tainting checks
 193  
 194  A bug in previous versions may have failed to detect some insecure
 195  conditions when taint checks are turned on.  (Taint checks are used
 196  in setuid or setgid scripts, or when explicitly turned on with the
 197  C<-T> invocation option.)  Although it's unlikely, this may cause a
 198  previously-working script to now fail -- which should be construed
 199  as a blessing, since that indicates a potentially-serious security
 200  hole was just plugged.
 201  
 202  The new restrictions when tainting include:
 203  
 204  =over 4
 205  
 206  =item No glob() or <*>
 207  
 208  These operators may spawn the C shell (csh), which cannot be made
 209  safe.  This restriction will be lifted in a future version of Perl
 210  when globbing is implemented without the use of an external program.
 211  
 212  =item No spawning if tainted $CDPATH, $ENV, $BASH_ENV
 213  
 214  These environment variables may alter the behavior of spawned programs
 215  (especially shells) in ways that subvert security.  So now they are
 216  treated as dangerous, in the manner of $IFS and $PATH.
 217  
 218  =item No spawning if tainted $TERM doesn't look like a terminal name
 219  
 220  Some termcap libraries do unsafe things with $TERM.  However, it would be
 221  unnecessarily harsh to treat all $TERM values as unsafe, since only shell
 222  metacharacters can cause trouble in $TERM.  So a tainted $TERM is
 223  considered to be safe if it contains only alphanumerics, underscores,
 224  dashes, and colons, and unsafe if it contains other characters (including
 225  whitespace).
 226  
 227  =back
 228  
 229  =head2 New Opcode module and revised Safe module
 230  
 231  A new Opcode module supports the creation, manipulation and
 232  application of opcode masks.  The revised Safe module has a new API
 233  and is implemented using the new Opcode module.  Please read the new
 234  Opcode and Safe documentation.
 235  
 236  =head2 Embedding improvements
 237  
 238  In older versions of Perl it was not possible to create more than one
 239  Perl interpreter instance inside a single process without leaking like a
 240  sieve and/or crashing.  The bugs that caused this behavior have all been
 241  fixed.  However, you still must take care when embedding Perl in a C
 242  program.  See the updated perlembed manpage for tips on how to manage
 243  your interpreters.
 244  
 245  =head2 Internal change: FileHandle class based on IO::* classes
 246  
 247  File handles are now stored internally as type IO::Handle.  The
 248  FileHandle module is still supported for backwards compatibility, but
 249  it is now merely a front end to the IO::* modules -- specifically,
 250  IO::Handle, IO::Seekable, and IO::File.  We suggest, but do not
 251  require, that you use the IO::* modules in new code.
 252  
 253  In harmony with this change, C<*GLOB{FILEHANDLE}> is now just a
 254  backward-compatible synonym for C<*GLOB{IO}>.
 255  
 256  =head2 Internal change: PerlIO abstraction interface
 257  
 258  It is now possible to build Perl with AT&T's sfio IO package
 259  instead of stdio.  See L<perlapio> for more details, and
 260  the F<INSTALL> file for how to use it.
 261  
 262  =head2 New and changed syntax
 263  
 264  =over 4
 265  
 266  =item $coderef->(PARAMS)
 267  
 268  A subroutine reference may now be suffixed with an arrow and a
 269  (possibly empty) parameter list.  This syntax denotes a call of the
 270  referenced subroutine, with the given parameters (if any).
 271  
 272  This new syntax follows the pattern of S<C<< $hashref->{FOO} >>> and
 273  S<C<< $aryref->[$foo] >>>: You may now write S<C<&$subref($foo)>> as
 274  S<C<< $subref->($foo) >>>.  All these arrow terms may be chained;
 275  thus, S<C<< &{$table->{FOO}}($bar) >>> may now be written
 276  S<C<< $table->{FOO}->($bar) >>>.
 277  
 278  =back
 279  
 280  =head2 New and changed builtin constants
 281  
 282  =over 4
 283  
 284  =item __PACKAGE__
 285  
 286  The current package name at compile time, or the undefined value if
 287  there is no current package (due to a C<package;> directive).  Like
 288  C<__FILE__> and C<__LINE__>, C<__PACKAGE__> does I<not> interpolate
 289  into strings.
 290  
 291  =back
 292  
 293  =head2 New and changed builtin variables
 294  
 295  =over 4
 296  
 297  =item $^E
 298  
 299  Extended error message on some platforms.  (Also known as
 300  $EXTENDED_OS_ERROR if you C<use English>).
 301  
 302  =item $^H
 303  
 304  The current set of syntax checks enabled by C<use strict>.  See the
 305  documentation of C<strict> for more details.  Not actually new, but
 306  newly documented.
 307  Because it is intended for internal use by Perl core components,
 308  there is no C<use English> long name for this variable.
 309  
 310  =item $^M
 311  
 312  By default, running out of memory it is not trappable.  However, if
 313  compiled for this, Perl may use the contents of C<$^M> as an emergency
 314  pool after die()ing with this message.  Suppose that your Perl were
 315  compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
 316  
 317      $^M = 'a' x (1<<16);
 318  
 319  would allocate a 64K buffer for use when in emergency.
 320  See the F<INSTALL> file for information on how to enable this option.
 321  As a disincentive to casual use of this advanced feature,
 322  there is no C<use English> long name for this variable.
 323  
 324  =back
 325  
 326  =head2 New and changed builtin functions
 327  
 328  =over 4
 329  
 330  =item delete on slices
 331  
 332  This now works.  (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
 333  
 334  =item flock
 335  
 336  is now supported on more platforms, prefers fcntl to lockf when
 337  emulating, and always flushes before (un)locking.
 338  
 339  =item printf and sprintf
 340  
 341  Perl now implements these functions itself; it doesn't use the C
 342  library function sprintf() any more, except for floating-point
 343  numbers, and even then only known flags are allowed.  As a result, it
 344  is now possible to know which conversions and flags will work, and
 345  what they will do.
 346  
 347  The new conversions in Perl's sprintf() are:
 348  
 349     %i    a synonym for %d
 350     %p    a pointer (the address of the Perl value, in hexadecimal)
 351     %n    special: *stores* the number of characters output so far
 352          into the next variable in the parameter list 
 353  
 354  The new flags that go between the C<%> and the conversion are:
 355  
 356     #    prefix octal with "0", hex with "0x"
 357     h    interpret integer as C type "short" or "unsigned short"
 358     V    interpret integer as Perl's standard integer type
 359  
 360  Also, where a number would appear in the flags, an asterisk ("*") may
 361  be used instead, in which case Perl uses the next item in the
 362  parameter list as the given number (that is, as the field width or
 363  precision).  If a field width obtained through "*" is negative, it has
 364  the same effect as the '-' flag: left-justification.
 365  
 366  See L<perlfunc/sprintf> for a complete list of conversion and flags.
 367  
 368  =item keys as an lvalue
 369  
 370  As an lvalue, C<keys> allows you to increase the number of hash buckets
 371  allocated for the given hash.  This can gain you a measure of efficiency if
 372  you know the hash is going to get big.  (This is similar to pre-extending
 373  an array by assigning a larger number to $#array.)  If you say
 374  
 375      keys %hash = 200;
 376  
 377  then C<%hash> will have at least 200 buckets allocated for it.  These
 378  buckets will be retained even if you do C<%hash = ()>; use C<undef
 379  %hash> if you want to free the storage while C<%hash> is still in scope.
 380  You can't shrink the number of buckets allocated for the hash using
 381  C<keys> in this way (but you needn't worry about doing this by accident,
 382  as trying has no effect).
 383  
 384  =item my() in Control Structures
 385  
 386  You can now use my() (with or without the parentheses) in the control
 387  expressions of control structures such as:
 388  
 389      while (defined(my $line = <>)) {
 390          $line = lc $line;
 391      } continue {
 392          print $line;
 393      }
 394  
 395      if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
 396          user_agrees();
 397      } elsif ($answer =~ /^n(o)?$/i) {
 398          user_disagrees();
 399      } else {
 400          chomp $answer;
 401          die "`$answer' is neither `yes' nor `no'";
 402      }
 403  
 404  Also, you can declare a foreach loop control variable as lexical by
 405  preceding it with the word "my".  For example, in:
 406  
 407      foreach my $i (1, 2, 3) {
 408          some_function();
 409      }
 410  
 411  $i is a lexical variable, and the scope of $i extends to the end of
 412  the loop, but not beyond it.
 413  
 414  Note that you still cannot use my() on global punctuation variables
 415  such as $_ and the like.
 416  
 417  =item pack() and unpack()
 418  
 419  A new format 'w' represents a BER compressed integer (as defined in
 420  ASN.1).  Its format is a sequence of one or more bytes, each of which
 421  provides seven bits of the total value, with the most significant
 422  first.  Bit eight of each byte is set, except for the last byte, in
 423  which bit eight is clear.
 424  
 425  If 'p' or 'P' are given undef as values, they now generate a NULL
 426  pointer.
 427  
 428  Both pack() and unpack() now fail when their templates contain invalid
 429  types.  (Invalid types used to be ignored.)
 430  
 431  =item sysseek()
 432  
 433  The new sysseek() operator is a variant of seek() that sets and gets the
 434  file's system read/write position, using the lseek(2) system call.  It is
 435  the only reliable way to seek before using sysread() or syswrite().  Its
 436  return value is the new position, or the undefined value on failure.
 437  
 438  =item use VERSION
 439  
 440  If the first argument to C<use> is a number, it is treated as a version
 441  number instead of a module name.  If the version of the Perl interpreter
 442  is less than VERSION, then an error message is printed and Perl exits
 443  immediately.  Because C<use> occurs at compile time, this check happens
 444  immediately during the compilation process, unlike C<require VERSION>,
 445  which waits until runtime for the check.  This is often useful if you
 446  need to check the current Perl version before C<use>ing library modules
 447  which have changed in incompatible ways from older versions of Perl.
 448  (We try not to do this more than we have to.)
 449  
 450  =item use Module VERSION LIST
 451  
 452  If the VERSION argument is present between Module and LIST, then the
 453  C<use> will call the VERSION method in class Module with the given
 454  version as an argument.  The default VERSION method, inherited from
 455  the UNIVERSAL class, croaks if the given version is larger than the
 456  value of the variable $Module::VERSION.  (Note that there is not a
 457  comma after VERSION!)
 458  
 459  This version-checking mechanism is similar to the one currently used
 460  in the Exporter module, but it is faster and can be used with modules
 461  that don't use the Exporter.  It is the recommended method for new
 462  code.
 463  
 464  =item prototype(FUNCTION)
 465  
 466  Returns the prototype of a function as a string (or C<undef> if the
 467  function has no prototype).  FUNCTION is a reference to or the name of the
 468  function whose prototype you want to retrieve.
 469  (Not actually new; just never documented before.)
 470  
 471  =item srand
 472  
 473  The default seed for C<srand>, which used to be C<time>, has been changed.
 474  Now it's a heady mix of difficult-to-predict system-dependent values,
 475  which should be sufficient for most everyday purposes.
 476  
 477  Previous to version 5.004, calling C<rand> without first calling C<srand>
 478  would yield the same sequence of random numbers on most or all machines.
 479  Now, when perl sees that you're calling C<rand> and haven't yet called
 480  C<srand>, it calls C<srand> with the default seed. You should still call
 481  C<srand> manually if your code might ever be run on a pre-5.004 system,
 482  of course, or if you want a seed other than the default.
 483  
 484  =item $_ as Default
 485  
 486  Functions documented in the Camel to default to $_ now in
 487  fact do, and all those that do are so documented in L<perlfunc>.
 488  
 489  =item C<m//gc> does not reset search position on failure
 490  
 491  The C<m//g> match iteration construct has always reset its target
 492  string's search position (which is visible through the C<pos> operator)
 493  when a match fails; as a result, the next C<m//g> match after a failure
 494  starts again at the beginning of the string.  With Perl 5.004, this
 495  reset may be disabled by adding the "c" (for "continue") modifier,
 496  i.e. C<m//gc>.  This feature, in conjunction with the C<\G> zero-width
 497  assertion, makes it possible to chain matches together.  See L<perlop>
 498  and L<perlre>.
 499  
 500  =item C<m//x> ignores whitespace before ?*+{}
 501  
 502  The C<m//x> construct has always been intended to ignore all unescaped
 503  whitespace.  However, before Perl 5.004, whitespace had the effect of
 504  escaping repeat modifiers like "*" or "?"; for example, C</a *b/x> was
 505  (mis)interpreted as C</a\*b/x>.  This bug has been fixed in 5.004.
 506  
 507  =item nested C<sub{}> closures work now
 508  
 509  Prior to the 5.004 release, nested anonymous functions didn't work
 510  right.  They do now.
 511  
 512  =item formats work right on changing lexicals
 513  
 514  Just like anonymous functions that contain lexical variables
 515  that change (like a lexical index variable for a C<foreach> loop),
 516  formats now work properly.  For example, this silently failed
 517  before (printed only zeros), but is fine now:
 518  
 519      my $i;
 520      foreach $i ( 1 .. 10 ) {
 521      write;
 522      }
 523      format =
 524      my i is @#
 525      $i
 526      .
 527  
 528  However, it still fails (without a warning) if the foreach is within a
 529  subroutine:
 530  
 531      my $i;
 532      sub foo {
 533        foreach $i ( 1 .. 10 ) {
 534      write;
 535        }
 536      }
 537      foo;
 538      format =
 539      my i is @#
 540      $i
 541      .
 542  
 543  =back
 544  
 545  =head2 New builtin methods
 546  
 547  The C<UNIVERSAL> package automatically contains the following methods that
 548  are inherited by all other classes:
 549  
 550  =over 4
 551  
 552  =item isa(CLASS)
 553  
 554  C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
 555  
 556  C<isa> is also exportable and can be called as a sub with two arguments. This
 557  allows the ability to check what a reference points to. Example:
 558  
 559      use UNIVERSAL qw(isa);
 560  
 561      if(isa($ref, 'ARRAY')) {
 562         ...
 563      }
 564  
 565  =item can(METHOD)
 566  
 567  C<can> checks to see if its object has a method called C<METHOD>,
 568  if it does then a reference to the sub is returned; if it does not then
 569  I<undef> is returned.
 570  
 571  =item VERSION( [NEED] )
 572  
 573  C<VERSION> returns the version number of the class (package).  If the
 574  NEED argument is given then it will check that the current version (as
 575  defined by the $VERSION variable in the given package) not less than
 576  NEED; it will die if this is not the case.  This method is normally
 577  called as a class method.  This method is called automatically by the
 578  C<VERSION> form of C<use>.
 579  
 580      use A 1.2 qw(some imported subs);
 581      # implies:
 582      A->VERSION(1.2);
 583  
 584  =back
 585  
 586  B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
 587  C<isa> uses a very similar method and caching strategy. This may cause
 588  strange effects if the Perl code dynamically changes @ISA in any package.
 589  
 590  You may add other methods to the UNIVERSAL class via Perl or XS code.
 591  You do not need to C<use UNIVERSAL> in order to make these methods
 592  available to your program.  This is necessary only if you wish to
 593  have C<isa> available as a plain subroutine in the current package.
 594  
 595  =head2 TIEHANDLE now supported
 596  
 597  See L<perltie> for other kinds of tie()s.
 598  
 599  =over 4
 600  
 601  =item TIEHANDLE classname, LIST
 602  
 603  This is the constructor for the class.  That means it is expected to
 604  return an object of some sort. The reference can be used to
 605  hold some internal information.
 606  
 607      sub TIEHANDLE {
 608      print "<shout>\n";
 609      my $i;
 610      return bless \$i, shift;
 611      }
 612  
 613  =item PRINT this, LIST
 614  
 615  This method will be triggered every time the tied handle is printed to.
 616  Beyond its self reference it also expects the list that was passed to
 617  the print function.
 618  
 619      sub PRINT {
 620      $r = shift;
 621      $$r++;
 622      return print join( $, => map {uc} @_), $\;
 623      }
 624  
 625  =item PRINTF this, LIST
 626  
 627  This method will be triggered every time the tied handle is printed to
 628  with the C<printf()> function.
 629  Beyond its self reference it also expects the format and list that was
 630  passed to the printf function.
 631  
 632      sub PRINTF {
 633          shift;
 634        my $fmt = shift;
 635          print sprintf($fmt, @_)."\n";
 636      }
 637  
 638  =item READ this LIST
 639  
 640  This method will be called when the handle is read from via the C<read>
 641  or C<sysread> functions.
 642  
 643      sub READ {
 644      $r = shift;
 645      my($buf,$len,$offset) = @_;
 646      print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset";
 647      }
 648  
 649  =item READLINE this
 650  
 651  This method will be called when the handle is read from. The method
 652  should return undef when there is no more data.
 653  
 654      sub READLINE {
 655      $r = shift;
 656      return "PRINT called $$r times\n"
 657      }
 658  
 659  =item GETC this
 660  
 661  This method will be called when the C<getc> function is called.
 662  
 663      sub GETC { print "Don't GETC, Get Perl"; return "a"; }
 664  
 665  =item DESTROY this
 666  
 667  As with the other types of ties, this method will be called when the
 668  tied handle is about to be destroyed. This is useful for debugging and
 669  possibly for cleaning up.
 670  
 671      sub DESTROY {
 672      print "</shout>\n";
 673      }
 674  
 675  =back
 676  
 677  =head2 Malloc enhancements
 678  
 679  If perl is compiled with the malloc included with the perl distribution
 680  (that is, if C<perl -V:d_mymalloc> is 'define') then you can print
 681  memory statistics at runtime by running Perl thusly:
 682  
 683    env PERL_DEBUG_MSTATS=2 perl your_script_here
 684  
 685  The value of 2 means to print statistics after compilation and on
 686  exit; with a value of 1, the statistics are printed only on exit.
 687  (If you want the statistics at an arbitrary time, you'll need to
 688  install the optional module Devel::Peek.)
 689  
 690  Three new compilation flags are recognized by malloc.c.  (They have no
 691  effect if perl is compiled with system malloc().)
 692  
 693  =over 4
 694  
 695  =item -DPERL_EMERGENCY_SBRK
 696  
 697  If this macro is defined, running out of memory need not be a fatal
 698  error: a memory pool can allocated by assigning to the special
 699  variable C<$^M>.  See L<"$^M">.
 700  
 701  =item -DPACK_MALLOC
 702  
 703  Perl memory allocation is by bucket with sizes close to powers of two.
 704  Because of these malloc overhead may be big, especially for data of
 705  size exactly a power of two.  If C<PACK_MALLOC> is defined, perl uses
 706  a slightly different algorithm for small allocations (up to 64 bytes
 707  long), which makes it possible to have overhead down to 1 byte for
 708  allocations which are powers of two (and appear quite often).
 709  
 710  Expected memory savings (with 8-byte alignment in C<alignbytes>) is
 711  about 20% for typical Perl usage.  Expected slowdown due to additional
 712  malloc overhead is in fractions of a percent (hard to measure, because
 713  of the effect of saved memory on speed).
 714  
 715  =item -DTWO_POT_OPTIMIZE
 716  
 717  Similarly to C<PACK_MALLOC>, this macro improves allocations of data
 718  with size close to a power of two; but this works for big allocations
 719  (starting with 16K by default).  Such allocations are typical for big
 720  hashes and special-purpose scripts, especially image processing.
 721  
 722  On recent systems, the fact that perl requires 2M from system for 1M
 723  allocation will not affect speed of execution, since the tail of such
 724  a chunk is not going to be touched (and thus will not require real
 725  memory).  However, it may result in a premature out-of-memory error.
 726  So if you will be manipulating very large blocks with sizes close to
 727  powers of two, it would be wise to define this macro.
 728  
 729  Expected saving of memory is 0-100% (100% in applications which
 730  require most memory in such 2**n chunks); expected slowdown is
 731  negligible.
 732  
 733  =back
 734  
 735  =head2 Miscellaneous efficiency enhancements
 736  
 737  Functions that have an empty prototype and that do nothing but return
 738  a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
 739  
 740  Each unique hash key is only allocated once, no matter how many hashes
 741  have an entry with that key.  So even if you have 100 copies of the
 742  same hash, the hash keys never have to be reallocated.
 743  
 744  =head1 Support for More Operating Systems
 745  
 746  Support for the following operating systems is new in Perl 5.004.
 747  
 748  =head2 Win32
 749  
 750  Perl 5.004 now includes support for building a "native" perl under
 751  Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
 752  and above) or the Borland C++ compiler (versions 5.02 and above).
 753  The resulting perl can be used under Windows 95 (if it
 754  is installed in the same directory locations as it got installed
 755  in Windows NT).  This port includes support for perl extension
 756  building tools like L<MakeMaker> and L<h2xs>, so that many extensions
 757  available on the Comprehensive Perl Archive Network (CPAN) can now be
 758  readily built under Windows NT.  See http://www.perl.com/ for more
 759  information on CPAN and F<README.win32> in the perl distribution for more
 760  details on how to get started with building this port.
 761  
 762  There is also support for building perl under the Cygwin32 environment.
 763  Cygwin32 is a set of GNU tools that make it possible to compile and run
 764  many Unix programs under Windows NT by providing a mostly Unix-like 
 765  interface for compilation and execution.  See F<README.cygwin32> in the
 766  perl distribution for more details on this port and how to obtain the
 767  Cygwin32 toolkit.
 768  
 769  =head2 Plan 9
 770  
 771  See F<README.plan9> in the perl distribution.
 772  
 773  =head2 QNX
 774  
 775  See F<README.qnx> in the perl distribution.
 776  
 777  =head2 AmigaOS
 778  
 779  See F<README.amigaos> in the perl distribution.
 780  
 781  =head1 Pragmata
 782  
 783  Six new pragmatic modules exist:
 784  
 785  =over 4
 786  
 787  =item use autouse MODULE => qw(sub1 sub2 sub3)
 788  
 789  Defers C<require MODULE> until someone calls one of the specified
 790  subroutines (which must be exported by MODULE).  This pragma should be
 791  used with caution, and only when necessary.
 792  
 793  =item use blib
 794  
 795  =item use blib 'dir'
 796  
 797  Looks for MakeMaker-like I<'blib'> directory structure starting in
 798  I<dir> (or current directory) and working back up to five levels of
 799  parent directories.
 800  
 801  Intended for use on command line with B<-M> option as a way of testing
 802  arbitrary scripts against an uninstalled version of a package.
 803  
 804  =item use constant NAME => VALUE
 805  
 806  Provides a convenient interface for creating compile-time constants,
 807  See L<perlsub/"Constant Functions">.
 808  
 809  =item use locale
 810  
 811  Tells the compiler to enable (or disable) the use of POSIX locales for
 812  builtin operations.
 813  
 814  When C<use locale> is in effect, the current LC_CTYPE locale is used
 815  for regular expressions and case mapping; LC_COLLATE for string
 816  ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
 817  (but B<not> in print).  LC_NUMERIC is always used in write, since
 818  lexical scoping of formats is problematic at best.
 819  
 820  Each C<use locale> or C<no locale> affects statements to the end of
 821  the enclosing BLOCK or, if not inside a BLOCK, to the end of the
 822  current file.  Locales can be switched and queried with
 823  POSIX::setlocale().
 824  
 825  See L<perllocale> for more information.
 826  
 827  =item use ops
 828  
 829  Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
 830  
 831  =item use vmsish
 832  
 833  Enable VMS-specific language features.  Currently, there are three
 834  VMS-specific features available: 'status', which makes C<$?> and
 835  C<system> return genuine VMS status values instead of emulating POSIX;
 836  'exit', which makes C<exit> take a genuine VMS status value instead of
 837  assuming that C<exit 1> is an error; and 'time', which makes all times
 838  relative to the local time zone, in the VMS tradition.
 839  
 840  =back
 841  
 842  =head1 Modules
 843  
 844  =head2 Required Updates
 845  
 846  Though Perl 5.004 is compatible with almost all modules that work
 847  with Perl 5.003, there are a few exceptions:
 848  
 849      Module   Required Version for Perl 5.004
 850      ------   -------------------------------
 851      Filter   Filter-1.12
 852      LWP      libwww-perl-5.08
 853      Tk       Tk400.202 (-w makes noise)
 854  
 855  Also, the majordomo mailing list program, version 1.94.1, doesn't work
 856  with Perl 5.004 (nor with perl 4), because it executes an invalid
 857  regular expression.  This bug is fixed in majordomo version 1.94.2.
 858  
 859  =head2 Installation directories
 860  
 861  The I<installperl> script now places the Perl source files for
 862  extensions in the architecture-specific library directory, which is
 863  where the shared libraries for extensions have always been.  This
 864  change is intended to allow administrators to keep the Perl 5.004
 865  library directory unchanged from a previous version, without running
 866  the risk of binary incompatibility between extensions' Perl source and
 867  shared libraries.
 868  
 869  =head2 Module information summary
 870  
 871  Brand new modules, arranged by topic rather than strictly
 872  alphabetically:
 873  
 874      CGI.pm               Web server interface ("Common Gateway Interface")
 875      CGI/Apache.pm        Support for Apache's Perl module
 876      CGI/Carp.pm          Log server errors with helpful context
 877      CGI/Fast.pm          Support for FastCGI (persistent server process)
 878      CGI/Push.pm          Support for server push
 879      CGI/Switch.pm        Simple interface for multiple server types
 880  
 881      CPAN                 Interface to Comprehensive Perl Archive Network
 882      CPAN::FirstTime      Utility for creating CPAN configuration file
 883      CPAN::Nox            Runs CPAN while avoiding compiled extensions
 884  
 885      IO.pm                Top-level interface to IO::* classes
 886      IO/File.pm           IO::File extension Perl module
 887      IO/Handle.pm         IO::Handle extension Perl module
 888      IO/Pipe.pm           IO::Pipe extension Perl module
 889      IO/Seekable.pm       IO::Seekable extension Perl module
 890      IO/Select.pm         IO::Select extension Perl module
 891      IO/Socket.pm         IO::Socket extension Perl module
 892  
 893      Opcode.pm            Disable named opcodes when compiling Perl code
 894  
 895      ExtUtils/Embed.pm    Utilities for embedding Perl in C programs
 896      ExtUtils/testlib.pm  Fixes up @INC to use just-built extension
 897  
 898      FindBin.pm           Find path of currently executing program
 899  
 900      Class/Struct.pm      Declare struct-like datatypes as Perl classes
 901      File/stat.pm         By-name interface to Perl's builtin stat
 902      Net/hostent.pm       By-name interface to Perl's builtin gethost*
 903      Net/netent.pm        By-name interface to Perl's builtin getnet*
 904      Net/protoent.pm      By-name interface to Perl's builtin getproto*
 905      Net/servent.pm       By-name interface to Perl's builtin getserv*
 906      Time/gmtime.pm       By-name interface to Perl's builtin gmtime
 907      Time/localtime.pm    By-name interface to Perl's builtin localtime
 908      Time/tm.pm           Internal object for Time::{gm,local}time
 909      User/grent.pm        By-name interface to Perl's builtin getgr*
 910      User/pwent.pm        By-name interface to Perl's builtin getpw*
 911  
 912      Tie/RefHash.pm       Base class for tied hashes with references as keys
 913  
 914      UNIVERSAL.pm         Base class for *ALL* classes
 915  
 916  =head2 Fcntl
 917  
 918  New constants in the existing Fcntl modules are now supported,
 919  provided that your operating system happens to support them:
 920  
 921      F_GETOWN F_SETOWN
 922      O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
 923      O_EXLOCK O_SHLOCK
 924  
 925  These constants are intended for use with the Perl operators sysopen()
 926  and fcntl() and the basic database modules like SDBM_File.  For the
 927  exact meaning of these and other Fcntl constants please refer to your
 928  operating system's documentation for fcntl() and open().
 929  
 930  In addition, the Fcntl module now provides these constants for use
 931  with the Perl operator flock():
 932  
 933      LOCK_SH LOCK_EX LOCK_NB LOCK_UN
 934  
 935  These constants are defined in all environments (because where there is
 936  no flock() system call, Perl emulates it).  However, for historical
 937  reasons, these constants are not exported unless they are explicitly
 938  requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
 939  
 940  =head2 IO
 941  
 942  The IO module provides a simple mechanism to load all the IO modules at one
 943  go.  Currently this includes:
 944  
 945       IO::Handle
 946       IO::Seekable
 947       IO::File
 948       IO::Pipe
 949       IO::Socket
 950  
 951  For more information on any of these modules, please see its
 952  respective documentation.
 953  
 954  =head2 Math::Complex
 955  
 956  The Math::Complex module has been totally rewritten, and now supports
 957  more operations.  These are overloaded:
 958  
 959       + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
 960  
 961  And these functions are now exported:
 962  
 963      pi i Re Im arg
 964      log10 logn ln cbrt root
 965      tan
 966      csc sec cot
 967      asin acos atan
 968      acsc asec acot
 969      sinh cosh tanh
 970      csch sech coth
 971      asinh acosh atanh
 972      acsch asech acoth
 973      cplx cplxe
 974  
 975  =head2 Math::Trig
 976  
 977  This new module provides a simpler interface to parts of Math::Complex for
 978  those who need trigonometric functions only for real numbers.
 979  
 980  =head2 DB_File
 981  
 982  There have been quite a few changes made to DB_File. Here are a few of
 983  the highlights:
 984  
 985  =over 4
 986  
 987  =item *
 988  
 989  Fixed a handful of bugs.
 990  
 991  =item *
 992  
 993  By public demand, added support for the standard hash function exists().
 994  
 995  =item *
 996  
 997  Made it compatible with Berkeley DB 1.86.
 998  
 999  =item *
1000  
1001  Made negative subscripts work with RECNO interface.
1002  
1003  =item *
1004  
1005  Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
1006  mode from 0640 to 0666.
1007  
1008  =item *
1009  
1010  Made DB_File automatically import the open() constants (O_RDWR,
1011  O_CREAT etc.) from Fcntl, if available.
1012  
1013  =item *
1014  
1015  Updated documentation.
1016  
1017  =back
1018  
1019  Refer to the HISTORY section in DB_File.pm for a complete list of
1020  changes. Everything after DB_File 1.01 has been added since 5.003.
1021  
1022  =head2 Net::Ping
1023  
1024  Major rewrite - support added for both udp echo and real icmp pings.
1025  
1026  =head2 Object-oriented overrides for builtin operators
1027  
1028  Many of the Perl builtins returning lists now have
1029  object-oriented overrides.  These are:
1030  
1031      File::stat
1032      Net::hostent
1033      Net::netent
1034      Net::protoent
1035      Net::servent
1036      Time::gmtime
1037      Time::localtime
1038      User::grent
1039      User::pwent
1040  
1041  For example, you can now say
1042  
1043      use File::stat;
1044      use User::pwent;
1045      $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);
1046  
1047  =head1 Utility Changes
1048  
1049  =head2 pod2html
1050  
1051  =over 4
1052  
1053  =item Sends converted HTML to standard output
1054  
1055  The I<pod2html> utility included with Perl 5.004 is entirely new.
1056  By default, it sends the converted HTML to its standard output,
1057  instead of writing it to a file like Perl 5.003's I<pod2html> did.
1058  Use the B<--outfile=FILENAME> option to write to a file.
1059  
1060  =back
1061  
1062  =head2 xsubpp
1063  
1064  =over 4
1065  
1066  =item C<void> XSUBs now default to returning nothing
1067  
1068  Due to a documentation/implementation bug in previous versions of
1069  Perl, XSUBs with a return type of C<void> have actually been
1070  returning one value.  Usually that value was the GV for the XSUB,
1071  but sometimes it was some already freed or reused value, which would
1072  sometimes lead to program failure.
1073  
1074  In Perl 5.004, if an XSUB is declared as returning C<void>, it
1075  actually returns no value, i.e. an empty list (though there is a
1076  backward-compatibility exception; see below).  If your XSUB really
1077  does return an SV, you should give it a return type of C<SV *>.
1078  
1079  For backward compatibility, I<xsubpp> tries to guess whether a
1080  C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
1081  It does so by examining the text of the XSUB: if I<xsubpp> finds
1082  what looks like an assignment to C<ST(0)>, it assumes that the
1083  XSUB's return type is really C<SV *>.
1084  
1085  =back
1086  
1087  =head1 C Language API Changes
1088  
1089  =over 4
1090  
1091  =item C<gv_fetchmethod> and C<perl_call_sv>
1092  
1093  The C<gv_fetchmethod> function finds a method for an object, just like
1094  in Perl 5.003.  The GV it returns may be a method cache entry.
1095  However, in Perl 5.004, method cache entries are not visible to users;
1096  therefore, they can no longer be passed directly to C<perl_call_sv>.
1097  Instead, you should use the C<GvCV> macro on the GV to extract its CV,
1098  and pass the CV to C<perl_call_sv>.
1099  
1100  The most likely symptom of passing the result of C<gv_fetchmethod> to
1101  C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
1102  error on the I<second> call to a given method (since there is no cache
1103  on the first call).
1104  
1105  =item C<perl_eval_pv>
1106  
1107  A new function handy for eval'ing strings of Perl code inside C code.
1108  This function returns the value from the eval statement, which can
1109  be used instead of fetching globals from the symbol table.  See
1110  L<perlguts>, L<perlembed> and L<perlcall> for details and examples.
1111  
1112  =item Extended API for manipulating hashes
1113  
1114  Internal handling of hash keys has changed.  The old hashtable API is
1115  still fully supported, and will likely remain so.  The additions to the
1116  API allow passing keys as C<SV*>s, so that C<tied> hashes can be given
1117  real scalars as keys rather than plain strings (nontied hashes still
1118  can only use strings as keys).  New extensions must use the new hash
1119  access functions and macros if they wish to use C<SV*> keys.  These
1120  additions also make it feasible to manipulate C<HE*>s (hash entries),
1121  which can be more efficient.  See L<perlguts> for details.
1122  
1123  =back
1124  
1125  =head1 Documentation Changes
1126  
1127  Many of the base and library pods were updated.  These
1128  new pods are included in section 1:
1129  
1130  =over 4
1131  
1132  =item L<perldelta>
1133  
1134  This document.
1135  
1136  =item L<perlfaq>
1137  
1138  Frequently asked questions.
1139  
1140  =item L<perllocale>
1141  
1142  Locale support (internationalization and localization).
1143  
1144  =item L<perltoot>
1145  
1146  Tutorial on Perl OO programming.
1147  
1148  =item L<perlapio>
1149  
1150  Perl internal IO abstraction interface.
1151  
1152  =item L<perlmodlib>
1153  
1154  Perl module library and recommended practice for module creation.
1155  Extracted from L<perlmod> (which is much smaller as a result).
1156  
1157  =item L<perldebug>
1158  
1159  Although not new, this has been massively updated.
1160  
1161  =item L<perlsec>
1162  
1163  Although not new, this has been massively updated.
1164  
1165  =back
1166  
1167  =head1 New Diagnostics
1168  
1169  Several new conditions will trigger warnings that were
1170  silent before.  Some only affect certain platforms.
1171  The following new warnings and errors outline these.
1172  These messages are classified as follows (listed in
1173  increasing order of desperation):
1174  
1175     (W) A warning (optional).
1176     (D) A deprecation (optional).
1177     (S) A severe warning (mandatory).
1178     (F) A fatal error (trappable).
1179     (P) An internal error you should never see (trappable).
1180     (X) A very fatal error (nontrappable).
1181     (A) An alien error message (not generated by Perl).
1182  
1183  =over 4
1184  
1185  =item "my" variable %s masks earlier declaration in same scope
1186  
1187  (W) A lexical variable has been redeclared in the same scope, effectively
1188  eliminating all access to the previous instance.  This is almost always
1189  a typographical error.  Note that the earlier variable will still exist
1190  until the end of the scope or until all closure referents to it are
1191  destroyed.
1192  
1193  =item %s argument is not a HASH element or slice
1194  
1195  (F) The argument to delete() must be either a hash element, such as
1196  
1197      $foo{$bar}
1198      $ref->[12]->{"susie"}
1199  
1200  or a hash slice, such as
1201  
1202      @foo{$bar, $baz, $xyzzy}
1203      @{$ref->[12]}{"susie", "queue"}
1204  
1205  =item Allocation too large: %lx
1206  
1207  (X) You can't allocate more than 64K on an MS-DOS machine.
1208  
1209  =item Allocation too large
1210  
1211  (F) You can't allocate more than 2^31+"small amount" bytes.
1212  
1213  =item Applying %s to %s will act on scalar(%s)
1214  
1215  (W) The pattern match (//), substitution (s///), and transliteration (tr///)
1216  operators work on scalar values.  If you apply one of them to an array
1217  or a hash, it will convert the array or hash to a scalar value -- the
1218  length of an array, or the population info of a hash -- and then work on
1219  that scalar value.  This is probably not what you meant to do.  See
1220  L<perlfunc/grep> and L<perlfunc/map> for alternatives.
1221  
1222  =item Attempt to free nonexistent shared string
1223  
1224  (P) Perl maintains a reference counted internal table of strings to
1225  optimize the storage and access of hash keys and other strings.  This
1226  indicates someone tried to decrement the reference count of a string
1227  that can no longer be found in the table.
1228  
1229  =item Attempt to use reference as lvalue in substr
1230  
1231  (W) You supplied a reference as the first argument to substr() used
1232  as an lvalue, which is pretty strange.  Perhaps you forgot to
1233  dereference it first.  See L<perlfunc/substr>.
1234  
1235  =item Bareword "%s" refers to nonexistent package
1236  
1237  (W) You used a qualified bareword of the form C<Foo::>, but
1238  the compiler saw no other uses of that namespace before that point.
1239  Perhaps you need to predeclare a package?
1240  
1241  =item Can't redefine active sort subroutine %s
1242  
1243  (F) Perl optimizes the internal handling of sort subroutines and keeps
1244  pointers into them.  You tried to redefine one such sort subroutine when it
1245  was currently active, which is not allowed.  If you really want to do
1246  this, you should write C<sort { &func } @x> instead of C<sort func @x>.
1247  
1248  =item Can't use bareword ("%s") as %s ref while "strict refs" in use
1249  
1250  (F) Only hard references are allowed by "strict refs".  Symbolic references
1251  are disallowed.  See L<perlref>.
1252  
1253  =item Cannot resolve method `%s' overloading `%s' in package `%s'
1254  
1255  (P) Internal error trying to resolve overloading specified by a method
1256  name (as opposed to a subroutine reference).
1257  
1258  =item Constant subroutine %s redefined
1259  
1260  (S) You redefined a subroutine which had previously been eligible for
1261  inlining.  See L<perlsub/"Constant Functions"> for commentary and
1262  workarounds.
1263  
1264  =item Constant subroutine %s undefined
1265  
1266  (S) You undefined a subroutine which had previously been eligible for
1267  inlining.  See L<perlsub/"Constant Functions"> for commentary and
1268  workarounds.
1269  
1270  =item Copy method did not return a reference
1271  
1272  (F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
1273  
1274  =item Died
1275  
1276  (F) You passed die() an empty string (the equivalent of C<die "">) or
1277  you called it with no args and both C<$@> and C<$_> were empty.
1278  
1279  =item Exiting pseudo-block via %s
1280  
1281  (W) You are exiting a rather special block construct (like a sort block or
1282  subroutine) by unconventional means, such as a goto, or a loop control
1283  statement.  See L<perlfunc/sort>.
1284  
1285  =item Identifier too long
1286  
1287  (F) Perl limits identifiers (names for variables, functions, etc.) to
1288  252 characters for simple names, somewhat more for compound names (like
1289  C<$A::B>).  You've exceeded Perl's limits.  Future versions of Perl are
1290  likely to eliminate these arbitrary limitations.
1291  
1292  =item Illegal character %s (carriage return)
1293  
1294  (F) A carriage return character was found in the input.  This is an
1295  error, and not a warning, because carriage return characters can break
1296  multi-line strings, including here documents (e.g., C<print <<EOF;>).
1297  
1298  =item Illegal switch in PERL5OPT: %s
1299  
1300  (X) The PERL5OPT environment variable may only be used to set the
1301  following switches: B<-[DIMUdmw]>.
1302  
1303  =item Integer overflow in hex number
1304  
1305  (S) The literal hex number you have specified is too big for your
1306  architecture. On a 32-bit architecture the largest hex literal is
1307  0xFFFFFFFF.
1308  
1309  =item Integer overflow in octal number
1310  
1311  (S) The literal octal number you have specified is too big for your
1312  architecture. On a 32-bit architecture the largest octal literal is
1313  037777777777.
1314  
1315  =item internal error: glob failed
1316  
1317  (P) Something went wrong with the external program(s) used for C<glob>
1318  and C<< <*.c> >>.  This may mean that your csh (C shell) is
1319  broken.  If so, you should change all of the csh-related variables in
1320  config.sh:  If you have tcsh, make the variables refer to it as if it
1321  were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
1322  empty (except that C<d_csh> should be C<'undef'>) so that Perl will
1323  think csh is missing.  In either case, after editing config.sh, run
1324  C<./Configure -S> and rebuild Perl.
1325  
1326  =item Invalid conversion in %s: "%s"
1327  
1328  (W) Perl does not understand the given format conversion.
1329  See L<perlfunc/sprintf>.
1330  
1331  =item Invalid type in pack: '%s'
1332  
1333  (F) The given character is not a valid pack type.  See L<perlfunc/pack>.
1334  
1335  =item Invalid type in unpack: '%s'
1336  
1337  (F) The given character is not a valid unpack type.  See L<perlfunc/unpack>.
1338  
1339  =item Name "%s::%s" used only once: possible typo
1340  
1341  (W) Typographical errors often show up as unique variable names.
1342  If you had a good reason for having a unique name, then just mention
1343  it again somehow to suppress the message (the C<use vars> pragma is
1344  provided for just this purpose).
1345  
1346  =item Null picture in formline
1347  
1348  (F) The first argument to formline must be a valid format picture
1349  specification.  It was found to be empty, which probably means you
1350  supplied it an uninitialized value.  See L<perlform>.
1351  
1352  =item Offset outside string
1353  
1354  (F) You tried to do a read/write/send/recv operation with an offset
1355  pointing outside the buffer.  This is difficult to imagine.
1356  The sole exception to this is that C<sysread()>ing past the buffer
1357  will extend the buffer and zero pad the new area.
1358  
1359  =item Out of memory!
1360  
1361  (X|F) The malloc() function returned 0, indicating there was insufficient
1362  remaining memory (or virtual memory) to satisfy the request.
1363  
1364  The request was judged to be small, so the possibility to trap it
1365  depends on the way Perl was compiled.  By default it is not trappable.
1366  However, if compiled for this, Perl may use the contents of C<$^M> as
1367  an emergency pool after die()ing with this message.  In this case the
1368  error is trappable I<once>.
1369  
1370  =item Out of memory during request for %s
1371  
1372  (F) The malloc() function returned 0, indicating there was insufficient
1373  remaining memory (or virtual memory) to satisfy the request. However,
1374  the request was judged large enough (compile-time default is 64K), so
1375  a possibility to shut down by trapping this error is granted.
1376  
1377  =item panic: frexp
1378  
1379  (P) The library function frexp() failed, making printf("%f") impossible.
1380  
1381  =item Possible attempt to put comments in qw() list
1382  
1383  (W) qw() lists contain items separated by whitespace; as with literal
1384  strings, comment characters are not ignored, but are instead treated
1385  as literal data.  (You may have used different delimiters than the
1386  parentheses shown here; braces are also frequently used.)
1387  
1388  You probably wrote something like this:
1389  
1390      @list = qw(
1391          a # a comment
1392          b # another comment
1393      );
1394  
1395  when you should have written this:
1396  
1397      @list = qw(
1398          a
1399          b
1400      );
1401  
1402  If you really want comments, build your list the
1403  old-fashioned way, with quotes and commas:
1404  
1405      @list = (
1406          'a',    # a comment
1407          'b',    # another comment
1408      );
1409  
1410  =item Possible attempt to separate words with commas
1411  
1412  (W) qw() lists contain items separated by whitespace; therefore commas
1413  aren't needed to separate the items. (You may have used different
1414  delimiters than the parentheses shown here; braces are also frequently
1415  used.)
1416  
1417  You probably wrote something like this:
1418  
1419      qw! a, b, c !;
1420  
1421  which puts literal commas into some of the list items.  Write it without
1422  commas if you don't want them to appear in your data:
1423  
1424      qw! a b c !;
1425  
1426  =item Scalar value @%s{%s} better written as $%s{%s}
1427  
1428  (W) You've used a hash slice (indicated by @) to select a single element of
1429  a hash.  Generally it's better to ask for a scalar value (indicated by $).
1430  The difference is that C<$foo{&bar}> always behaves like a scalar, both when
1431  assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
1432  like a list when you assign to it, and provides a list context to its
1433  subscript, which can do weird things if you're expecting only one subscript.
1434  
1435  =item Stub found while resolving method `%s' overloading `%s' in %s
1436  
1437  (P) Overloading resolution over @ISA tree may be broken by importing stubs.
1438  Stubs should never be implicitly created, but explicit calls to C<can>
1439  may break this.
1440  
1441  =item Too late for "B<-T>" option
1442  
1443  (X) The #! line (or local equivalent) in a Perl script contains the
1444  B<-T> option, but Perl was not invoked with B<-T> in its argument
1445  list.  This is an error because, by the time Perl discovers a B<-T> in
1446  a script, it's too late to properly taint everything from the
1447  environment.  So Perl gives up.
1448  
1449  =item untie attempted while %d inner references still exist
1450  
1451  (W) A copy of the object returned from C<tie> (or C<tied>) was still
1452  valid when C<untie> was called.
1453  
1454  =item Unrecognized character %s
1455  
1456  (F) The Perl parser has no idea what to do with the specified character
1457  in your Perl script (or eval).  Perhaps you tried to run a compressed
1458  script, a binary program, or a directory as a Perl program.
1459  
1460  =item Unsupported function fork
1461  
1462  (F) Your version of executable does not support forking.
1463  
1464  Note that under some systems, like OS/2, there may be different flavors of
1465  Perl executables, some of which may support fork, some not. Try changing
1466  the name you call Perl by to C<perl_>, C<perl__>, and so on.
1467  
1468  =item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
1469  
1470  (D) Perl versions before 5.004 misinterpreted any type marker followed
1471  by "$" and a digit.  For example, "$$0" was incorrectly taken to mean
1472  "${$}0" instead of "${$0}".  This bug is (mostly) fixed in Perl 5.004.
1473  
1474  However, the developers of Perl 5.004 could not fix this bug completely,
1475  because at least two widely-used modules depend on the old meaning of
1476  "$$0" in a string.  So Perl 5.004 still interprets "$$<digit>" in the
1477  old (broken) way inside strings; but it generates this message as a
1478  warning.  And in Perl 5.005, this special treatment will cease.
1479  
1480  =item Value of %s can be "0"; test with defined()
1481  
1482  (W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>,
1483  or C<readdir()> as a boolean value.  Each of these constructs can return a
1484  value of "0"; that would make the conditional expression false, which is
1485  probably not what you intended.  When using these constructs in conditional
1486  expressions, test their values with the C<defined> operator.
1487  
1488  =item Variable "%s" may be unavailable
1489  
1490  (W) An inner (nested) I<anonymous> subroutine is inside a I<named>
1491  subroutine, and outside that is another subroutine; and the anonymous
1492  (innermost) subroutine is referencing a lexical variable defined in
1493  the outermost subroutine.  For example:
1494  
1495     sub outermost { my $a; sub middle { sub { $a } } }
1496  
1497  If the anonymous subroutine is called or referenced (directly or
1498  indirectly) from the outermost subroutine, it will share the variable
1499  as you would expect.  But if the anonymous subroutine is called or
1500  referenced when the outermost subroutine is not active, it will see
1501  the value of the shared variable as it was before and during the
1502  *first* call to the outermost subroutine, which is probably not what
1503  you want.
1504  
1505  In these circumstances, it is usually best to make the middle
1506  subroutine anonymous, using the C<sub {}> syntax.  Perl has specific
1507  support for shared variables in nested anonymous subroutines; a named
1508  subroutine in between interferes with this feature.
1509  
1510  =item Variable "%s" will not stay shared
1511  
1512  (W) An inner (nested) I<named> subroutine is referencing a lexical
1513  variable defined in an outer subroutine.
1514  
1515  When the inner subroutine is called, it will probably see the value of
1516  the outer subroutine's variable as it was before and during the
1517  *first* call to the outer subroutine; in this case, after the first
1518  call to the outer subroutine is complete, the inner and outer
1519  subroutines will no longer share a common value for the variable.  In
1520  other words, the variable will no longer be shared.
1521  
1522  Furthermore, if the outer subroutine is anonymous and references a
1523  lexical variable outside itself, then the outer and inner subroutines
1524  will I<never> share the given variable.
1525  
1526  This problem can usually be solved by making the inner subroutine
1527  anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
1528  reference variables in outer subroutines are called or referenced,
1529  they are automatically rebound to the current values of such
1530  variables.
1531  
1532  =item Warning: something's wrong
1533  
1534  (W) You passed warn() an empty string (the equivalent of C<warn "">) or
1535  you called it with no args and C<$_> was empty.
1536  
1537  =item Ill-formed logical name |%s| in prime_env_iter
1538  
1539  (W) A warning peculiar to VMS.  A logical name was encountered when preparing
1540  to iterate over %ENV which violates the syntactic rules governing logical
1541  names.  Since it cannot be translated normally, it is skipped, and will not
1542  appear in %ENV.  This may be a benign occurrence, as some software packages
1543  might directly modify logical name tables and introduce nonstandard names,
1544  or it may indicate that a logical name table has been corrupted.
1545  
1546  =item Got an error from DosAllocMem
1547  
1548  (P) An error peculiar to OS/2.  Most probably you're using an obsolete
1549  version of Perl, and this should not happen anyway.
1550  
1551  =item Malformed PERLLIB_PREFIX
1552  
1553  (F) An error peculiar to OS/2.  PERLLIB_PREFIX should be of the form
1554  
1555      prefix1;prefix2
1556  
1557  or
1558  
1559      prefix1 prefix2
1560  
1561  with nonempty prefix1 and prefix2.  If C<prefix1> is indeed a prefix
1562  of a builtin library search path, prefix2 is substituted.  The error
1563  may appear if components are not found, or are too long.  See
1564  "PERLLIB_PREFIX" in F<README.os2>.
1565  
1566  =item PERL_SH_DIR too long
1567  
1568  (F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
1569  C<sh>-shell in.  See "PERL_SH_DIR" in F<README.os2>.
1570  
1571  =item Process terminated by SIG%s
1572  
1573  (W) This is a standard message issued by OS/2 applications, while *nix
1574  applications die in silence.  It is considered a feature of the OS/2
1575  port.  One can easily disable this by appropriate sighandlers, see
1576  L<perlipc/"Signals">.  See also "Process terminated by SIGTERM/SIGINT"
1577  in F<README.os2>.
1578  
1579  =back
1580  
1581  =head1 BUGS
1582  
1583  If you find what you think is a bug, you might check the headers of
1584  recently posted articles in the comp.lang.perl.misc newsgroup.
1585  There may also be information at http://www.perl.com/perl/ , the Perl
1586  Home Page.
1587  
1588  If you believe you have an unreported bug, please run the B<perlbug>
1589  program included with your release.  Make sure you trim your bug down
1590  to a tiny but sufficient test case.  Your bug report, along with the
1591  output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
1592  analysed by the Perl porting team.
1593  
1594  =head1 SEE ALSO
1595  
1596  The F<Changes> file for exhaustive details on what changed.
1597  
1598  The F<INSTALL> file for how to build Perl.  This file has been
1599  significantly updated for 5.004, so even veteran users should
1600  look through it.
1601  
1602  The F<README> file for general stuff.
1603  
1604  The F<Copying> file for copyright information.
1605  
1606  =head1 HISTORY
1607  
1608  Constructed by Tom Christiansen, grabbing material with permission
1609  from innumerable contributors, with kibitzing by more than a few Perl
1610  porters.
1611  
1612  Last update: Wed May 14 11:14:09 EDT 1997