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