This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
628ca22f27f4c66843678d5c788523c89aaa9272
[perl5.git] / pod / perldelta.pod
1 =head1 NAME
2
3 perldelta - 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, Plan9, LynxOS, VMS, OS/2,
14 QNX, and AmigaOS.
15
16 =head1 Core Changes
17
18 Most importantly, many bugs were fixed.  See the F<Changes>
19 file in the distribution for details.
20
21 =head2 Compilation Option: Binary Compatibility With 5.003
22
23 There is a new Configure question that asks if you want to maintain
24 binary compatibility with Perl 5.003.  If you choose binary
25 compatibility, you do not have to recompile your extensions, but you
26 might have symbol conflicts if you embed Perl in another application,
27 just as in the 5.003 release.  By default, binary compatibility
28 is preserved at the expense of symbol table pollution.
29
30 =head2 New Opcode Module and Revised Safe Module
31
32 A new Opcode module supports the creation, manipulation and
33 application of opcode masks.  The revised Safe module has a new API
34 and is implemented using the new Opcode module.  Please read the new
35 Opcode and Safe documentation.
36
37 =head2 Fixed Parsing of $$<digit>, &$<digit>, etc.
38
39 A bug in previous versions of Perl 5.0 prevented proper parsing of
40 numeric special variables as symbolic references.  That bug has been
41 fixed.  As a result, the string "$$0" is no longer equivalent to
42 C<$$."0">, but rather to C<${$0}>.  To get the old behavior, change
43 "$$" followed by a digit to "${$}".
44
45 =head2 Internal Change: FileHandle Deprecated
46
47 Filehandles are now stored internally as type IO::Handle.
48 Although C<use FileHandle> and C<*STDOUT{FILEHANDLE}>
49 are still supported for backwards compatibility,
50 C<use IO::Handle> (or C<IO::Seekable> or C<IO::File>) and
51 C<*STDOUT{IO}> are the way of the future.
52
53 =head2 Internal Change: PerlIO internal IO abstraction interface
54
55 It is now possible to build Perl with AT&T's sfio IO package
56 instead of stdio.  See L<perlapio> for more details, and
57 the F<INSTALL> file for how to use it.
58
59 =head2 New and Changed Built-in Variables
60
61 =over
62
63 =item $^E
64
65 Extended error message on some platforms.  (Also known as
66 $EXTENDED_OS_ERROR if you C<use English>).
67
68 =item $^H
69
70 The current set of syntax checks enabled by C<use strict>.  See the
71 documentation of C<strict> for more details.  Not actually new, but
72 newly documented.
73 Because it is intended for internal use by Perl core components,
74 there is no C<use English> long name for this variable.
75
76 =item $^M
77
78 By default, running out of memory it is not trappable.  However, if
79 compiled for this, Perl may use the contents of C<$^M> as an emergency
80 pool after die()ing with this message.  Suppose that your Perl were
81 compiled with -DEMERGENCY_SBRK and used Perl's malloc.  Then
82
83     $^M = 'a' x (1<<16);
84
85 would allocate a 64K buffer for use when in emergency.
86 See the F<INSTALL> file for information on how to enable this option.
87 As a disincentive to casual use of this advanced feature,
88 there is no C<use English> long name for this variable.
89
90 =back
91
92 =head2 New and Changed Built-in Functions
93
94 =over
95
96 =item delete on slices
97
98 This now works.  (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
99
100 =item flock
101
102 is now supported on more platforms, and prefers fcntl
103 to lockf when emulating.
104
105 =item printf and sprintf
106
107 now support "%i" as a synonym for "%d", and the "h" modifier.
108 So "%hi" means "short integer in decimal", and "%ho" means
109 "unsigned short integer as octal".
110
111 =item keys as an lvalue
112
113 As an lvalue, C<keys> allows you to increase the number of hash buckets
114 allocated for the given hash.  This can gain you a measure of efficiency if
115 you know the hash is going to get big.  (This is similar to pre-extending
116 an array by assigning a larger number to $#array.)  If you say
117
118     keys %hash = 200;
119
120 then C<%hash> will have at least 200 buckets allocated for it.  These
121 buckets will be retained even if you do C<%hash = ()>; use C<undef
122 %hash> if you want to free the storage while C<%hash> is still in scope.
123 You can't shrink the number of buckets allocated for the hash using
124 C<keys> in this way (but you needn't worry about doing this by accident,
125 as trying has no effect).
126
127 =item my() in Control Structures
128
129 You can now use my() (with or without the parentheses) in the control
130 expressions of control structures such as:
131
132     while (defined(my $line = <>)) {
133         $line = lc $line;
134     } continue {
135         print $line;
136     }
137
138     if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
139         user_agrees();
140     } elsif ($answer =~ /^n(o)?$/i) {
141         user_disagrees();
142     } else {
143         chomp $answer;
144         die "`$answer' is neither `yes' nor `no'";
145     }
146
147 Also, you can declare a foreach loop control variable as lexical by
148 preceding it with the word "my".  For example, in:
149
150     foreach my $i (1, 2, 3) {
151         some_function();
152     }
153
154 $i is a lexical variable, and the scope of $i extends to the end of
155 the loop, but not beyond it.
156
157 Note that you still cannot use my() on global punctuation variables
158 such as $_ and the like.
159
160 =item unpack() and pack()
161
162 A new format 'w' represents a BER compressed integer (as defined in
163 ASN.1).  Its format is a sequence of one or more bytes, each of which
164 provides seven bits of the total value, with the most significant
165 first.  Bit eight of each byte is set, except for the last byte, in
166 which bit eight is clear.
167
168 =item use VERSION
169
170 If the first argument to C<use> is a number, it is treated as a version
171 number instead of a module name.  If the version of the Perl interpreter
172 is less than VERSION, then an error message is printed and Perl exits
173 immediately.  Because C<use> occurs at compile time, this check happens
174 immediately during the compilation process, unlike C<require VERSION>,
175 which waits until run-time for the check.  This is often useful if you
176 need to check the current Perl version before C<use>ing library modules
177 which have changed in incompatible ways from older versions of Perl.
178 (We try not to do this more than we have to.)
179
180 =item use Module VERSION LIST
181
182 If the VERSION argument is present between Module and LIST, then the
183 C<use> will call the VERSION method in class Module with the given
184 version as an argument.  The default VERSION method, inherited from
185 the Universal class, croaks if the given version is larger than the
186 value of the variable $Module::VERSION.  (Note that there is not a
187 comma after VERSION!)
188
189 This version-checking mechanism is similar to the one currently used
190 in the Exporter module, but it is faster and can be used with modules
191 that don't use the Exporter.  It is the recommended method for new
192 code.
193
194 =item prototype(FUNCTION)
195
196 Returns the prototype of a function as a string (or C<undef> if the
197 function has no prototype).  FUNCTION is a reference to or the name of the
198 function whose prototype you want to retrieve.
199 (Not actually new; just never documented before.)
200
201 =item $_ as Default
202
203 Functions documented in the Camel to default to $_ now in
204 fact do, and all those that do are so documented in L<perlfunc>.
205
206 =item C<m//g> does not trigger a pos() reset on failure
207
208 The C<m//g> match iteration construct used to reset the iteration
209 when it failed to match (so that the next C<m//g> match would start at
210 the beginning of the string).  You now have to explicitly do a
211 C<pos $str = 0;> to reset the "last match" position, or modify the
212 string in some way.  This change makes it practical to chain C<m//g>
213 matches together in conjunction with ordinary matches using the C<\G>
214 zero-width assertion.  See L<perlop> and L<perlre>.
215
216 =item nested C<sub{}> closures work now
217
218 Prior to the 5.004 release, nested anonymous functions 
219 didn't work right.  They do now.
220
221 =item formats work right on changing lexicals
222
223 Just like anonymous functions that contain lexical variables
224 that change (like a lexical index variable for a C<foreach> loop),
225 formats now work properly.  For example, this silently failed
226 before, and is fine now:
227
228     my $i;
229     foreach $i ( 1 .. 10 ) {
230         format =
231         my i is @#
232         $i
233     .
234         write;
235     } 
236
237 =back
238
239 =head2 New Built-in Methods
240
241 The C<UNIVERSAL> package automatically contains the following methods that
242 are inherited by all other classes:
243
244 =over
245
246 =item isa(CLASS)
247
248 C<isa> returns I<true> if its object is blessed into a sub-class of C<CLASS>
249
250 C<isa> is also exportable and can be called as a sub with two arguments. This
251 allows the ability to check what a reference points to. Example:
252
253     use UNIVERSAL qw(isa);
254
255     if(isa($ref, 'ARRAY')) {
256        ...
257     }
258
259 =item can(METHOD)
260
261 C<can> checks to see if its object has a method called C<METHOD>,
262 if it does then a reference to the sub is returned; if it does not then
263 I<undef> is returned.
264
265 =item VERSION( [NEED] )
266
267 C<VERSION> returns the version number of the class (package).  If the
268 NEED argument is given then it will check that the current version (as
269 defined by the $VERSION variable in the given package) not less than
270 NEED; it will die if this is not the case.  This method is normally
271 called as a class method.  This method is called automatically by the
272 C<VERSION> form of C<use>.
273
274     use A 1.2 qw(some imported subs);
275     # implies:
276     A->VERSION(1.2);
277
278 =back
279
280 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
281 C<isa> uses a very similar method and caching strategy. This may cause
282 strange effects if the Perl code dynamically changes @ISA in any package.
283
284 You may add other methods to the UNIVERSAL class via Perl or XS code.
285 You do not need to C<use UNIVERSAL> in order to make these methods
286 available to your program.  This is necessary only if you wish to
287 have C<isa> available as a plain subroutine in the current package.
288
289 =head2 TIEHANDLE Now Supported
290
291 See L<perltie> for other kinds of tie()s.
292
293 =over
294
295 =item TIEHANDLE classname, LIST
296
297 This is the constructor for the class.  That means it is expected to
298 return an object of some sort. The reference can be used to
299 hold some internal information.
300
301     sub TIEHANDLE { 
302         print "<shout>\n"; 
303         my $i; 
304         return bless \$i, shift;
305     }
306
307 =item PRINT this, LIST
308
309 This method will be triggered every time the tied handle is printed to.
310 Beyond its self reference it also expects the list that was passed to
311 the print function.
312
313     sub PRINT { 
314         $r = shift; 
315         $$r++; 
316         return print join( $, => map {uc} @_), $\;
317     }
318
319 =item READLINE this
320
321 This method will be called when the handle is read from. The method
322 should return undef when there is no more data.
323
324     sub READLINE { 
325         $r = shift; 
326         return "PRINT called $$r times\n"; 
327     }
328
329 =item DESTROY this
330
331 As with the other types of ties, this method will be called when the
332 tied handle is about to be destroyed. This is useful for debugging and
333 possibly for cleaning up.
334
335     sub DESTROY { 
336         print "</shout>\n";
337     }
338
339 =back
340
341 =head2 Malloc Enhancements
342
343 If perl's malloc() is used, you can print memory statistics at runtime
344 by running Perl thusly:
345
346   env PERL_DEBUG_MSTATS=2 perl your_script_here
347
348 The value of 2 means to print statistics after compilation and on
349 exit; with a value of 1, the statistics ares printed only on exit.
350 (If you want the statistics at an arbitrary time, you'll need to
351 install the optional module Devel::Peek.)
352
353 In addition, three new compilation flags are recognized by malloc.c.
354 (They have no effect if perl is compiled with system malloc().)
355
356 =over
357
358 =item -DEMERGENCY_SBRK
359
360 If this macro is defined, running out of memory need not be a fatal
361 error: a memory pool can allocated by assigning to the special
362 variable C<$^M>.  See L<"$^M">.
363
364 =item -DPACK_MALLOC
365
366 Perl memory allocation is by bucket with sizes close to powers of two.
367 Because of these malloc overhead may be big, especially for data of
368 size exactly a power of two.  If C<PACK_MALLOC> is defined, perl uses
369 a slightly different algorithm for small allocations (up to 64 bytes
370 long), which makes it possible to have overhead down to 1 byte for
371 allocations which are powers of two (and appear quite often).
372
373 Expected memory savings (with 8-byte alignment in C<alignbytes>) is
374 about 20% for typical Perl usage.  Expected slowdown due to additional
375 malloc overhead is in fractions of a percent (hard to measure, because
376 of the effect of saved memory on speed).
377
378 =item -DTWO_POT_OPTIMIZE
379
380 Similarly to C<PACK_MALLOC>, this macro improves allocations of data
381 with size close to a power of two; but this works for big allocations
382 (starting with 16K by default).  Such allocations are typical for big
383 hashes and special-purpose scripts, especially image processing.
384
385 On recent systems, the fact that perl requires 2M from system for 1M
386 allocation will not affect speed of execution, since the tail of such
387 a chunk is not going to be touched (and thus will not require real
388 memory).  However, it may result in a premature out-of-memory error.
389 So if you will be manipulating very large blocks with sizes close to
390 powers of two, it would be wise to define this macro.
391
392 Expected saving of memory is 0-100% (100% in applications which
393 require most memory in such 2**n chunks); expected slowdown is
394 negligible.
395
396 =back
397
398 =head2 Miscellaneous Efficiency Enhancements
399
400 Functions that have an empty prototype and that do nothing but return
401 a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
402
403 Each unique hash key is only allocated once, no matter how many hashes
404 have an entry with that key.  So even if you have 100 copies of the
405 same hash, the hash keys never have to be re-allocated.
406
407 =head1 Pragmata
408
409 Four new pragmatic modules exist:
410
411 =over
412
413 =item use blib
414
415 =item use blib 'dir'
416
417 Looks for MakeMaker-like I<'blib'> directory structure starting in
418 I<dir> (or current directory) and working back up to five levels of
419 parent directories.
420
421 Intended for use on command line with B<-M> option as a way of testing
422 arbitrary scripts against an uninstalled version of a package.
423
424 =item use locale
425
426 Tells the compiler to enable (or disable) the use of POSIX locales for
427 built-in operations.
428
429 When C<use locale> is in effect, the current LC_CTYPE locale is used
430 for regular expressions and case mapping; LC_COLLATE for string
431 ordering; and LC_NUMERIC for numeric formating in printf and sprintf
432 (but B<not> in print).  LC_NUMERIC is always used in write, since
433 lexical scoping of formats is problematic at best.
434
435 Each C<use locale> or C<no locale> affects statements to the end of
436 the enclosing BLOCK or, if not inside a BLOCK, to the end of the
437 current file.  Locales can be switched and queried with
438 POSIX::setlocale().
439
440 See L<perllocale> for more information.
441
442 =item use ops
443
444 Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
445
446 =item use vmsish
447
448 Enable VMS-specific language features.  Currently, there are three
449 VMS-specific features available: 'status', which makes C<$?> and
450 C<system> return genuine VMS status values instead of emulating POSIX;
451 'exit', which makes C<exit> take a genuine VMS status value instead of
452 assuming that C<exit 1> is an error; and 'time', which makes all times
453 relative to the local time zone, in the VMS tradition.
454
455 =back
456
457 =head1 Modules
458
459 =head2 Installation Directories
460
461 The I<installperl> script now places the Perl source files for
462 extensions in the architecture-specific library directory, which is
463 where the shared libraries for extensions have always been.  This
464 change is intended to allow administrators to keep the Perl 5.004
465 library directory unchanged from a previous version, without running
466 the risk of binary incompatibility between extensions' Perl source and
467 shared libraries.
468
469 =head2 Fcntl
470
471 New constants in the existing Fcntl modules are now supported,
472 provided that your operating system happens to support them:
473
474     F_GETOWN F_SETOWN
475     O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC 
476     O_EXLOCK O_SHLOCK
477
478 These constants are intended for use with the Perl operators sysopen()
479 and fcntl() and the basic database modules like SDBM_File.  For the
480 exact meaning of these and other Fcntl constants please refer to your
481 operating system's documentation for fcntl() and open().
482
483 In addition, the Fcntl module now provides these constants for use
484 with the Perl operator flock():
485
486         LOCK_SH LOCK_EX LOCK_NB LOCK_UN
487
488 These constants are defined in all environments (because where there is
489 no flock() system call, Perl emulates it).  However, for historical
490 reasons, these constants are not exported unless they are explicitly
491 requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
492
493 =head2 Module Information Summary
494
495 Brand new modules, arranged by topic rather than strictly
496 alphabetically:
497
498     CPAN                 interface to Comprehensive Perl Archive Network
499     CPAN::FirstTime      create a CPAN configuration file
500     CPAN::Nox            run CPAN while avoiding compiled extensions
501
502     IO.pm                Top-level interface to IO::* classes
503     IO/File.pm           IO::File extension Perl module
504     IO/Handle.pm         IO::Handle extension Perl module
505     IO/Pipe.pm           IO::Pipe extension Perl module
506     IO/Seekable.pm       IO::Seekable extension Perl module
507     IO/Select.pm         IO::Select extension Perl module
508     IO/Socket.pm         IO::Socket extension Perl module
509
510     Opcode.pm            Disable named opcodes when compiling Perl code
511
512     ExtUtils/Embed.pm    Utilities for embedding Perl in C programs
513     ExtUtils/testlib.pm  Fixes up @INC to use just-built extension
514
515     FindBin.pm           Find path of currently executing program
516
517     Class/Template.pm    Structure/member template builder
518     File/stat.pm         Object-oriented wrapper around CORE::stat
519     Net/hostent.pm       Object-oriented wrapper around CORE::gethost*
520     Net/netent.pm        Object-oriented wrapper around CORE::getnet*
521     Net/protoent.pm      Object-oriented wrapper around CORE::getproto*
522     Net/servent.pm       Object-oriented wrapper around CORE::getserv*
523     Time/gmtime.pm       Object-oriented wrapper around CORE::gmtime
524     Time/localtime.pm    Object-oriented wrapper around CORE::localtime
525     Time/tm.pm           Perl implementation of "struct tm" for {gm,local}time
526     User/grent.pm        Object-oriented wrapper around CORE::getgr*
527     User/pwent.pm        Object-oriented wrapper around CORE::getpw*
528
529     Tie/RefHash.pm       Base class for tied hashes with references as keys
530
531     UNIVERSAL.pm         Base class for *ALL* classes
532
533 =head2 IO
534
535 The IO module provides a simple mechanism to load all of the IO modules at one
536 go.  Currently this includes:
537
538      IO::Handle
539      IO::Seekable
540      IO::File
541      IO::Pipe
542      IO::Socket
543
544 For more information on any of these modules, please see its
545 respective documentation.
546
547 =head2 Math::Complex
548
549 The Math::Complex module has been totally rewritten, and now supports
550 more operations.  These are overloaded:
551
552      + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
553
554 And these functions are now exported:
555
556     pi i Re Im arg
557     log10 logn cbrt root
558     tan cotan asin acos atan acotan
559     sinh cosh tanh cotanh asinh acosh atanh acotanh
560     cplx cplxe
561
562 =head2 DB_File
563
564 There have been quite a few changes made to DB_File. Here are a few of
565 the highlights:
566
567 =over
568
569 =item *
570
571 Fixed a handful of bugs.
572
573 =item *
574
575 By public demand, added support for the standard hash function exists().
576
577 =item *
578
579 Made it compatible with Berkeley DB 1.86.
580
581 =item *
582
583 Made negative subscripts work with RECNO interface.
584
585 =item *
586
587 Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
588 mode from 0640 to 0666.
589
590 =item *
591
592 Made DB_File automatically import the open() constants (O_RDWR,
593 O_CREAT etc.) from Fcntl, if available.
594
595 =item *
596
597 Updated documentation.
598
599 =back
600
601 Refer to the HISTORY section in DB_File.pm for a complete list of
602 changes. Everything after DB_File 1.01 has been added since 5.003.
603
604 =head2 Net::Ping
605
606 Major rewrite - support added for both udp echo and real icmp pings.
607
608 =head2 Overridden Built-ins
609
610 Many of the Perl built-ins returning lists now have
611 object-oriented overrides.  These are:
612
613     File::stat
614     Net::hostent
615     Net::netent
616     Net::protoent
617     Net::servent
618     Time::gmtime
619     Time::localtime
620     User::grent
621     User::pwent
622
623 For example, you can now say
624
625     use File::stat;
626     use User::pwent;
627     $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);
628
629 =head1 Utility Changes
630
631 =head2 xsubpp
632
633 =over
634
635 =item C<void> XSUBs now default to returning nothing
636
637 Due to a documentation/implementation bug in previous versions of
638 Perl, XSUBs with a return type of C<void> have actually been
639 returning one value.  Usually that value was the GV for the XSUB,
640 but sometimes it was some already freed or reused value, which would
641 sometimes lead to program failure.
642
643 In Perl 5.004, if an XSUB is declared as returning C<void>, it
644 actually returns no value, i.e. an empty list (though there is a
645 backward-compatibility exception; see below).  If your XSUB really
646 does return an SV, you should give it a return type of C<SV *>.
647
648 For backward compatibility, I<xsubpp> tries to guess whether a
649 C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
650 It does so by examining the text of the XSUB: if I<xsubpp> finds
651 what looks like an assignment to C<ST(0)>, it assumes that the
652 XSUB's return type is really C<SV *>.
653
654 =back
655
656 =head1 C Language API Changes
657
658 =over
659
660 =item C<gv_fetchmethod> and C<perl_call_sv>
661
662 The C<gv_fetchmethod> function finds a method for an object, just like
663 in Perl 5.003.  The GV it returns may be a method cache entry.
664 However, in Perl 5.004, method cache entries are not visible to users;
665 therefore, they can no longer be passed directly to C<perl_call_sv>.
666 Instead, you should use the C<GvCV> macro on the GV to extract its CV,
667 and pass the CV to C<perl_call_sv>.
668
669 The most likely symptom of passing the result of C<gv_fetchmethod> to
670 C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
671 error on the I<second> call to a given method (since there is no cache
672 on the first call).
673
674 =back
675
676 =head1 Documentation Changes
677
678 Many of the base and library pods were updated.  These
679 new pods are included in section 1:
680
681 =over
682
683 =item L<perldelta>
684
685 This document.
686
687 =item L<perllocale>
688
689 Locale support (internationalization and localization).
690
691 =item L<perltoot>
692
693 Tutorial on Perl OO programming.
694
695 =item L<perlapio>
696
697 Perl internal IO abstraction interface.
698
699 =item L<perldebug>
700
701 Although not new, this has been massively updated.
702
703 =item L<perlsec>
704
705 Although not new, this has been massively updated.
706
707 =back
708
709 =head1 New Diagnostics
710
711 Several new conditions will trigger warnings that were
712 silent before.  Some only affect certain platforms.
713 The following new warnings and errors outline these.  
714 These messages are classified as follows (listed in
715 increasing order of desperation):
716
717    (W) A warning (optional).
718    (D) A deprecation (optional).
719    (S) A severe warning (mandatory).
720    (F) A fatal error (trappable).
721    (P) An internal error you should never see (trappable).
722    (X) A very fatal error (non-trappable).
723    (A) An alien error message (not generated by Perl).
724
725 =over
726
727 =item "my" variable %s masks earlier declaration in same scope
728
729 (S) A lexical variable has been redeclared in the same scope, effectively
730 eliminating all access to the previous instance.  This is almost always
731 a typographical error.  Note that the earlier variable will still exist
732 until the end of the scope or until all closure referents to it are
733 destroyed.
734
735 =item %s argument is not a HASH element or slice
736
737 (F) The argument to delete() must be either a hash element, such as
738
739     $foo{$bar}
740     $ref->[12]->{"susie"}
741
742 or a hash slice, such as
743
744     @foo{$bar, $baz, $xyzzy}
745     @{$ref->[12]}{"susie", "queue"}
746
747 =item Allocation too large: %lx
748
749 (X) You can't allocate more than 64K on an MSDOS machine.
750
751 =item Allocation too large
752
753 (F) You can't allocate more than 2^31+"small amount" bytes.
754
755 =item Attempt to free non-existent shared string
756
757 (P) Perl maintains a reference counted internal table of strings to
758 optimize the storage and access of hash keys and other strings.  This
759 indicates someone tried to decrement the reference count of a string
760 that can no longer be found in the table.
761
762 =item Attempt to use reference as lvalue in substr
763
764 (W) You supplied a reference as the first argument to substr() used
765 as an lvalue, which is pretty strange.  Perhaps you forgot to
766 dereference it first.  See L<perlfunc/substr>.
767
768 =item Unsupported function fork
769
770 (F) Your version of executable does not support forking.
771
772 Note that under some systems, like OS/2, there may be different flavors of
773 Perl executables, some of which may support fork, some not. Try changing
774 the name you call Perl by to C<perl_>, C<perl__>, and so on.
775
776 =item Ill-formed logical name |%s| in prime_env_iter
777
778 (W) A warning peculiar to VMS.  A logical name was encountered when preparing
779 to iterate over %ENV which violates the syntactic rules governing logical
780 names.  Since it cannot be translated normally, it is skipped, and will not
781 appear in %ENV.  This may be a benign occurrence, as some software packages
782 might directly modify logical name tables and introduce non-standard names,
783 or it may indicate that a logical name table has been corrupted.
784
785 =item Can't use bareword ("%s") as %s ref while "strict refs" in use
786
787 (F) Only hard references are allowed by "strict refs".  Symbolic references
788 are disallowed.  See L<perlref>.
789
790 =item Constant subroutine %s redefined
791
792 (S) You redefined a subroutine which had previously been eligible for
793 inlining.  See L<perlsub/"Constant Functions"> for commentary and
794 workarounds.
795
796 =item Died
797
798 (F) You passed die() an empty string (the equivalent of C<die "">) or
799 you called it with no args and both C<$@> and C<$_> were empty.
800
801 =item Integer overflow in hex number
802
803 (S) The literal hex number you have specified is too big for your
804 architecture. On a 32-bit architecture the largest hex literal is
805 0xFFFFFFFF.
806
807 =item Integer overflow in octal number
808
809 (S) The literal octal number you have specified is too big for your
810 architecture. On a 32-bit architecture the largest octal literal is
811 037777777777.
812
813 =item Name "%s::%s" used only once: possible typo
814
815 (W) Typographical errors often show up as unique variable names.
816 If you had a good reason for having a unique name, then just mention
817 it again somehow to suppress the message (the C<use vars> pragma is
818 provided for just this purpose).
819
820 =item Null picture in formline
821
822 (F) The first argument to formline must be a valid format picture
823 specification.  It was found to be empty, which probably means you
824 supplied it an uninitialized value.  See L<perlform>.
825
826 =item Offset outside string
827
828 (F) You tried to do a read/write/send/recv operation with an offset
829 pointing outside the buffer.  This is difficult to imagine.
830 The sole exception to this is that C<sysread()>ing past the buffer
831 will extend the buffer and zero pad the new area.
832
833 =item Stub found while resolving method `%s' overloading `%s' in package `%s'
834
835 (P) Overloading resolution over @ISA tree may be broken by importing stubs.
836 Stubs should never be implicitely created, but explicit calls to C<can>
837 may break this.
838
839 =item Cannot resolve method `%s' overloading `%s' in package `s'
840
841 (P) Internal error trying to resolve overloading specified by a method
842 name (as opposed to a subroutine reference).
843
844 =item Out of memory!
845
846 (X|F) The malloc() function returned 0, indicating there was insufficient
847 remaining memory (or virtual memory) to satisfy the request.
848
849 The request was judged to be small, so the possibility to trap it
850 depends on the way Perl was compiled.  By default it is not trappable.
851 However, if compiled for this, Perl may use the contents of C<$^M> as
852 an emergency pool after die()ing with this message.  In this case the
853 error is trappable I<once>.
854
855 =item Out of memory during request for %s
856
857 (F) The malloc() function returned 0, indicating there was insufficient
858 remaining memory (or virtual memory) to satisfy the request. However,
859 the request was judged large enough (compile-time default is 64K), so
860 a possibility to shut down by trapping this error is granted.
861
862 =item Possible attempt to put comments in qw() list
863
864 (W) qw() lists contain items separated by whitespace; as with literal
865 strings, comment characters are not ignored, but are instead treated
866 as literal data.  (You may have used different delimiters than the
867 exclamation marks parentheses shown here; braces are also frequently
868 used.)
869
870 You probably wrote something like this:
871
872     @list = qw( 
873         a # a comment
874         b # another comment
875     );
876
877 when you should have written this:
878
879     @list = qw(
880         a 
881         b
882     );
883
884 If you really want comments, build your list the
885 old-fashioned way, with quotes and commas:
886
887     @list = (
888         'a',    # a comment
889         'b',    # another comment
890     );
891
892 =item Possible attempt to separate words with commas
893
894 (W) qw() lists contain items separated by whitespace; therefore commas
895 aren't needed to separate the items. (You may have used different
896 delimiters than the parentheses shown here; braces are also frequently
897 used.)
898
899 You probably wrote something like this: 
900
901     qw! a, b, c !;
902
903 which puts literal commas into some of the list items.  Write it without
904 commas if you don't want them to appear in your data:
905
906     qw! a b c !;
907
908 =item Scalar value @%s{%s} better written as $%s{%s}
909
910 (W) You've used a hash slice (indicated by @) to select a single element of
911 a hash.  Generally it's better to ask for a scalar value (indicated by $).
912 The difference is that C<$foo{&bar}> always behaves like a scalar, both when
913 assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
914 like a list when you assign to it, and provides a list context to its
915 subscript, which can do weird things if you're expecting only one subscript.
916
917 =item untie attempted while %d inner references still exist
918
919 (W) A copy of the object returned from C<tie> (or C<tied>) was still
920 valid when C<untie> was called.
921
922 =item Value of %s construct can be "0"; test with defined()
923
924 (W) In a conditional expression, you used <HANDLE>, <*> (glob), or
925 C<readdir> as a boolean value.  Each of these constructs can return a
926 value of "0"; that would make the conditional expression false, which
927 is probably not what you intended.  When using these constructs in
928 conditional expressions, test their values with the C<defined> operator.
929
930 =item Variable "%s" may be unavailable
931
932 (W) An inner (nested) I<anonymous> subroutine is inside a I<named>
933 subroutine, and outside that is another subroutine; and the anonymous
934 (innermost) subroutine is referencing a lexical variable defined in
935 the outermost subroutine.  For example:
936
937    sub outermost { my $a; sub middle { sub { $a } } }
938
939 If the anonymous subroutine is called or referenced (directly or
940 indirectly) from the outermost subroutine, it will share the variable
941 as you would expect.  But if the anonymous subroutine is called or
942 referenced when the outermost subroutine is not active, it will see
943 the value of the shared variable as it was before and during the
944 *first* call to the outermost subroutine, which is probably not what
945 you want.
946
947 In these circumstances, it is usually best to make the middle
948 subroutine anonymous, using the C<sub {}> syntax.  Perl has specific
949 support for shared variables in nested anonymous subroutines; a named
950 subroutine in between interferes with this feature.
951
952 =item Variable "%s" will not stay shared
953
954 (W) An inner (nested) I<named> subroutine is referencing a lexical
955 variable defined in an outer subroutine.
956
957 When the inner subroutine is called, it will probably see the value of
958 the outer subroutine's variable as it was before and during the
959 *first* call to the outer subroutine; in this case, after the first
960 call to the outer subroutine is complete, the inner and outer
961 subroutines will no longer share a common value for the variable.  In
962 other words, the variable will no longer be shared.
963
964 Furthermore, if the outer subroutine is anonymous and references a
965 lexical variable outside itself, then the outer and inner subroutines
966 will I<never> share the given variable.
967
968 This problem can usually be solved by making the inner subroutine
969 anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
970 reference variables in outer subroutines are called or referenced,
971 they are automatically re-bound to the current values of such
972 variables.
973
974 =item Warning: something's wrong
975
976 (W) You passed warn() an empty string (the equivalent of C<warn "">) or
977 you called it with no args and C<$_> was empty.
978
979 =item Got an error from DosAllocMem
980
981 (P) An error peculiar to OS/2.  Most probably you're using an obsolete
982 version of Perl, and this should not happen anyway.
983
984 =item Malformed PERLLIB_PREFIX
985
986 (F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
987
988     prefix1;prefix2
989
990 or
991
992     prefix1 prefix2
993
994 with non-empty prefix1 and prefix2. If C<prefix1> is indeed a prefix of
995 a builtin library search path, prefix2 is substituted. The error may appear
996 if components are not found, or are too long. See L<perlos2/"PERLLIB_PREFIX">.
997
998 =item PERL_SH_DIR too long
999
1000 (F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
1001 C<sh>-shell in. See L<perlos2/"PERL_SH_DIR">.
1002
1003 =item Process terminated by SIG%s
1004
1005 (W) This is a standard message issued by OS/2 applications, while *nix
1006 applications die in silence. It is considered a feature of the OS/2
1007 port. One can easily disable this by appropriate sighandlers, see
1008 L<perlipc/"Signals">.  See L<perlos2/"Process terminated by SIGTERM/SIGINT">.
1009
1010 =back
1011
1012 =head1 BUGS
1013
1014 If you find what you think is a bug, you might check the headers of
1015 recently posted articles in the comp.lang.perl.misc newsgroup.
1016 There may also be information at http://www.perl.com/perl/, the Perl
1017 Home Page.
1018
1019 If you believe you have an unreported bug, please run the B<perlbug>
1020 program included with your release.  Make sure you trim your bug
1021 down to a tiny but sufficient test case.  Your bug report, along
1022 with the output of C<perl -V>, will be sent off to perlbug@perl.com
1023 to be analysed by the Perl porting team.
1024
1025 =head1 SEE ALSO
1026
1027 The F<Changes> file for exhaustive details on what changed.
1028
1029 The F<INSTALL> file for how to build Perl.  This file has been
1030 significantly updated for 5.004, so even veteran users should
1031 look through it.
1032
1033 The F<README> file for general stuff.
1034
1035 The F<Copying> file for copyright information.
1036
1037 =head1 HISTORY
1038
1039 Constructed by Tom Christiansen, grabbing material with permission
1040 from innumerable contributors, with kibitzing by more than a few Perl
1041 porters.
1042
1043 Last update: Tue Jan 14 14:03:02 EST 1997