3 perldelta - what's new for perl5.004
7 This document describes differences between the 5.003 release (as
8 documented in I<Programming Perl>, second edition--the Camel Book) and
11 =head1 Supported Environments
13 Perl5.004 builds out of the box on Unix, Plan9, LynxOS, VMS, OS/2,
18 Most importantly, many bugs were fixed. See the F<Changes>
19 file in the distribution for details.
21 =head2 Compilation Option: Binary Compatibility With 5.003
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.
30 =head2 New Opcode Module and Revised Safe Module
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.
37 =head2 Fixed Parsing of $$<digit>, &$<digit>, etc.
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 "${$}".
45 =head2 Changes to Tainting Checks
47 A bug in previous versions may have failed to detect some insecure
48 conditions when taint checks are turned on. (Taint checks are used
49 in setuid or setgid scripts, or when explicitly turned on with the
50 C<-T> invocation option.) Although it's unlikely, this may cause a
51 previously-working script to now fail -- which should be construed
52 as a blessing, since that indicates a potentially-serious security
53 hole was just plugged.
55 =head2 Internal Change: FileHandle Class Based on IO::* Classes
57 File handles are now stored internally as type IO::Handle. The
58 FileHandle module is still supported for backwards compatibility, but
59 it is now merely a front end to the IO::* modules -- specifically,
60 IO::Handle, IO::Seekable, and IO::File. We suggest, but do not
61 require, that you use the IO::* modules in new code.
63 In harmony with this change, C<*GLOB{FILEHANDLE}> is now a
64 backward-compatible synonym for C<*STDOUT{IO}>.
66 =head2 Internal Change: PerlIO internal IO abstraction interface
68 It is now possible to build Perl with AT&T's sfio IO package
69 instead of stdio. See L<perlapio> for more details, and
70 the F<INSTALL> file for how to use it.
72 =head2 New and Changed Built-in Variables
78 Extended error message on some platforms. (Also known as
79 $EXTENDED_OS_ERROR if you C<use English>).
83 The current set of syntax checks enabled by C<use strict>. See the
84 documentation of C<strict> for more details. Not actually new, but
86 Because it is intended for internal use by Perl core components,
87 there is no C<use English> long name for this variable.
91 By default, running out of memory it is not trappable. However, if
92 compiled for this, Perl may use the contents of C<$^M> as an emergency
93 pool after die()ing with this message. Suppose that your Perl were
94 compiled with -DEMERGENCY_SBRK and used Perl's malloc. Then
98 would allocate a 64K buffer for use when in emergency.
99 See the F<INSTALL> file for information on how to enable this option.
100 As a disincentive to casual use of this advanced feature,
101 there is no C<use English> long name for this variable.
105 =head2 New and Changed Built-in Functions
109 =item delete on slices
111 This now works. (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
115 is now supported on more platforms, and prefers fcntl
116 to lockf when emulating.
118 =item printf and sprintf
120 now support "%i" as a synonym for "%d", and the "h" modifier.
121 So "%hi" means "short integer in decimal", and "%ho" means
122 "unsigned short integer as octal".
124 =item keys as an lvalue
126 As an lvalue, C<keys> allows you to increase the number of hash buckets
127 allocated for the given hash. This can gain you a measure of efficiency if
128 you know the hash is going to get big. (This is similar to pre-extending
129 an array by assigning a larger number to $#array.) If you say
133 then C<%hash> will have at least 200 buckets allocated for it. These
134 buckets will be retained even if you do C<%hash = ()>; use C<undef
135 %hash> if you want to free the storage while C<%hash> is still in scope.
136 You can't shrink the number of buckets allocated for the hash using
137 C<keys> in this way (but you needn't worry about doing this by accident,
138 as trying has no effect).
140 =item my() in Control Structures
142 You can now use my() (with or without the parentheses) in the control
143 expressions of control structures such as:
145 while (defined(my $line = <>)) {
151 if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
153 } elsif ($answer =~ /^n(o)?$/i) {
157 die "`$answer' is neither `yes' nor `no'";
160 Also, you can declare a foreach loop control variable as lexical by
161 preceding it with the word "my". For example, in:
163 foreach my $i (1, 2, 3) {
167 $i is a lexical variable, and the scope of $i extends to the end of
168 the loop, but not beyond it.
170 Note that you still cannot use my() on global punctuation variables
171 such as $_ and the like.
173 =item unpack() and pack()
175 A new format 'w' represents a BER compressed integer (as defined in
176 ASN.1). Its format is a sequence of one or more bytes, each of which
177 provides seven bits of the total value, with the most significant
178 first. Bit eight of each byte is set, except for the last byte, in
179 which bit eight is clear.
183 If the first argument to C<use> is a number, it is treated as a version
184 number instead of a module name. If the version of the Perl interpreter
185 is less than VERSION, then an error message is printed and Perl exits
186 immediately. Because C<use> occurs at compile time, this check happens
187 immediately during the compilation process, unlike C<require VERSION>,
188 which waits until run-time for the check. This is often useful if you
189 need to check the current Perl version before C<use>ing library modules
190 which have changed in incompatible ways from older versions of Perl.
191 (We try not to do this more than we have to.)
193 =item use Module VERSION LIST
195 If the VERSION argument is present between Module and LIST, then the
196 C<use> will call the VERSION method in class Module with the given
197 version as an argument. The default VERSION method, inherited from
198 the Universal class, croaks if the given version is larger than the
199 value of the variable $Module::VERSION. (Note that there is not a
200 comma after VERSION!)
202 This version-checking mechanism is similar to the one currently used
203 in the Exporter module, but it is faster and can be used with modules
204 that don't use the Exporter. It is the recommended method for new
207 =item prototype(FUNCTION)
209 Returns the prototype of a function as a string (or C<undef> if the
210 function has no prototype). FUNCTION is a reference to or the name of the
211 function whose prototype you want to retrieve.
212 (Not actually new; just never documented before.)
216 The default seed for C<srand>, which used to be C<time>, has been changed.
217 Now it's a heady mix of difficult-to-predict system-dependent values,
218 which should be sufficient for most everyday purposes.
220 Previous to version 5.004, calling C<rand> without first calling C<srand>
221 would yield the same sequence of random numbers on most or all machines.
222 Now, when perl sees that you're calling C<rand> and haven't yet called
223 C<srand>, it calls C<srand> with the default seed. You should still call
224 C<srand> manually if your code might ever be run on a pre-5.004 system,
225 of course, or if you want a seed other than the default.
229 Functions documented in the Camel to default to $_ now in
230 fact do, and all those that do are so documented in L<perlfunc>.
232 =item C<m//g> does not trigger a pos() reset on failure
234 The C<m//g> match iteration construct used to reset the iteration
235 when it failed to match (so that the next C<m//g> match would start at
236 the beginning of the string). You now have to explicitly do a
237 C<pos $str = 0;> to reset the "last match" position, or modify the
238 string in some way. This change makes it practical to chain C<m//g>
239 matches together in conjunction with ordinary matches using the C<\G>
240 zero-width assertion. See L<perlop> and L<perlre>.
242 =item nested C<sub{}> closures work now
244 Prior to the 5.004 release, nested anonymous functions
245 didn't work right. They do now.
247 =item formats work right on changing lexicals
249 Just like anonymous functions that contain lexical variables
250 that change (like a lexical index variable for a C<foreach> loop),
251 formats now work properly. For example, this silently failed
252 before, and is fine now:
255 foreach $i ( 1 .. 10 ) {
265 =head2 New Built-in Methods
267 The C<UNIVERSAL> package automatically contains the following methods that
268 are inherited by all other classes:
274 C<isa> returns I<true> if its object is blessed into a sub-class of C<CLASS>
276 C<isa> is also exportable and can be called as a sub with two arguments. This
277 allows the ability to check what a reference points to. Example:
279 use UNIVERSAL qw(isa);
281 if(isa($ref, 'ARRAY')) {
287 C<can> checks to see if its object has a method called C<METHOD>,
288 if it does then a reference to the sub is returned; if it does not then
289 I<undef> is returned.
291 =item VERSION( [NEED] )
293 C<VERSION> returns the version number of the class (package). If the
294 NEED argument is given then it will check that the current version (as
295 defined by the $VERSION variable in the given package) not less than
296 NEED; it will die if this is not the case. This method is normally
297 called as a class method. This method is called automatically by the
298 C<VERSION> form of C<use>.
300 use A 1.2 qw(some imported subs);
306 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
307 C<isa> uses a very similar method and caching strategy. This may cause
308 strange effects if the Perl code dynamically changes @ISA in any package.
310 You may add other methods to the UNIVERSAL class via Perl or XS code.
311 You do not need to C<use UNIVERSAL> in order to make these methods
312 available to your program. This is necessary only if you wish to
313 have C<isa> available as a plain subroutine in the current package.
315 =head2 TIEHANDLE Now Supported
317 See L<perltie> for other kinds of tie()s.
321 =item TIEHANDLE classname, LIST
323 This is the constructor for the class. That means it is expected to
324 return an object of some sort. The reference can be used to
325 hold some internal information.
330 return bless \$i, shift;
333 =item PRINT this, LIST
335 This method will be triggered every time the tied handle is printed to.
336 Beyond its self reference it also expects the list that was passed to
342 return print join( $, => map {uc} @_), $\;
347 This method will be called when the handle is read from. The method
348 should return undef when there is no more data.
352 return "PRINT called $$r times\n";
357 As with the other types of ties, this method will be called when the
358 tied handle is about to be destroyed. This is useful for debugging and
359 possibly for cleaning up.
367 =head2 Malloc Enhancements
369 If perl's malloc() is used, you can print memory statistics at runtime
370 by running Perl thusly:
372 env PERL_DEBUG_MSTATS=2 perl your_script_here
374 The value of 2 means to print statistics after compilation and on
375 exit; with a value of 1, the statistics ares printed only on exit.
376 (If you want the statistics at an arbitrary time, you'll need to
377 install the optional module Devel::Peek.)
379 In addition, three new compilation flags are recognized by malloc.c.
380 (They have no effect if perl is compiled with system malloc().)
384 =item -DEMERGENCY_SBRK
386 If this macro is defined, running out of memory need not be a fatal
387 error: a memory pool can allocated by assigning to the special
388 variable C<$^M>. See L<"$^M">.
392 Perl memory allocation is by bucket with sizes close to powers of two.
393 Because of these malloc overhead may be big, especially for data of
394 size exactly a power of two. If C<PACK_MALLOC> is defined, perl uses
395 a slightly different algorithm for small allocations (up to 64 bytes
396 long), which makes it possible to have overhead down to 1 byte for
397 allocations which are powers of two (and appear quite often).
399 Expected memory savings (with 8-byte alignment in C<alignbytes>) is
400 about 20% for typical Perl usage. Expected slowdown due to additional
401 malloc overhead is in fractions of a percent (hard to measure, because
402 of the effect of saved memory on speed).
404 =item -DTWO_POT_OPTIMIZE
406 Similarly to C<PACK_MALLOC>, this macro improves allocations of data
407 with size close to a power of two; but this works for big allocations
408 (starting with 16K by default). Such allocations are typical for big
409 hashes and special-purpose scripts, especially image processing.
411 On recent systems, the fact that perl requires 2M from system for 1M
412 allocation will not affect speed of execution, since the tail of such
413 a chunk is not going to be touched (and thus will not require real
414 memory). However, it may result in a premature out-of-memory error.
415 So if you will be manipulating very large blocks with sizes close to
416 powers of two, it would be wise to define this macro.
418 Expected saving of memory is 0-100% (100% in applications which
419 require most memory in such 2**n chunks); expected slowdown is
424 =head2 Miscellaneous Efficiency Enhancements
426 Functions that have an empty prototype and that do nothing but return
427 a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
429 Each unique hash key is only allocated once, no matter how many hashes
430 have an entry with that key. So even if you have 100 copies of the
431 same hash, the hash keys never have to be re-allocated.
435 Four new pragmatic modules exist:
443 Looks for MakeMaker-like I<'blib'> directory structure starting in
444 I<dir> (or current directory) and working back up to five levels of
447 Intended for use on command line with B<-M> option as a way of testing
448 arbitrary scripts against an uninstalled version of a package.
452 Tells the compiler to enable (or disable) the use of POSIX locales for
455 When C<use locale> is in effect, the current LC_CTYPE locale is used
456 for regular expressions and case mapping; LC_COLLATE for string
457 ordering; and LC_NUMERIC for numeric formating in printf and sprintf
458 (but B<not> in print). LC_NUMERIC is always used in write, since
459 lexical scoping of formats is problematic at best.
461 Each C<use locale> or C<no locale> affects statements to the end of
462 the enclosing BLOCK or, if not inside a BLOCK, to the end of the
463 current file. Locales can be switched and queried with
466 See L<perllocale> for more information.
470 Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
474 Enable VMS-specific language features. Currently, there are three
475 VMS-specific features available: 'status', which makes C<$?> and
476 C<system> return genuine VMS status values instead of emulating POSIX;
477 'exit', which makes C<exit> take a genuine VMS status value instead of
478 assuming that C<exit 1> is an error; and 'time', which makes all times
479 relative to the local time zone, in the VMS tradition.
485 =head2 Installation Directories
487 The I<installperl> script now places the Perl source files for
488 extensions in the architecture-specific library directory, which is
489 where the shared libraries for extensions have always been. This
490 change is intended to allow administrators to keep the Perl 5.004
491 library directory unchanged from a previous version, without running
492 the risk of binary incompatibility between extensions' Perl source and
497 New constants in the existing Fcntl modules are now supported,
498 provided that your operating system happens to support them:
501 O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
504 These constants are intended for use with the Perl operators sysopen()
505 and fcntl() and the basic database modules like SDBM_File. For the
506 exact meaning of these and other Fcntl constants please refer to your
507 operating system's documentation for fcntl() and open().
509 In addition, the Fcntl module now provides these constants for use
510 with the Perl operator flock():
512 LOCK_SH LOCK_EX LOCK_NB LOCK_UN
514 These constants are defined in all environments (because where there is
515 no flock() system call, Perl emulates it). However, for historical
516 reasons, these constants are not exported unless they are explicitly
517 requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
519 =head2 Module Information Summary
521 Brand new modules, arranged by topic rather than strictly
524 CPAN interface to Comprehensive Perl Archive Network
525 CPAN::FirstTime create a CPAN configuration file
526 CPAN::Nox run CPAN while avoiding compiled extensions
528 IO.pm Top-level interface to IO::* classes
529 IO/File.pm IO::File extension Perl module
530 IO/Handle.pm IO::Handle extension Perl module
531 IO/Pipe.pm IO::Pipe extension Perl module
532 IO/Seekable.pm IO::Seekable extension Perl module
533 IO/Select.pm IO::Select extension Perl module
534 IO/Socket.pm IO::Socket extension Perl module
536 Opcode.pm Disable named opcodes when compiling Perl code
538 ExtUtils/Embed.pm Utilities for embedding Perl in C programs
539 ExtUtils/testlib.pm Fixes up @INC to use just-built extension
541 FindBin.pm Find path of currently executing program
543 Class/Template.pm Structure/member template builder
544 File/stat.pm Object-oriented wrapper around CORE::stat
545 Net/hostent.pm Object-oriented wrapper around CORE::gethost*
546 Net/netent.pm Object-oriented wrapper around CORE::getnet*
547 Net/protoent.pm Object-oriented wrapper around CORE::getproto*
548 Net/servent.pm Object-oriented wrapper around CORE::getserv*
549 Time/gmtime.pm Object-oriented wrapper around CORE::gmtime
550 Time/localtime.pm Object-oriented wrapper around CORE::localtime
551 Time/tm.pm Perl implementation of "struct tm" for {gm,local}time
552 User/grent.pm Object-oriented wrapper around CORE::getgr*
553 User/pwent.pm Object-oriented wrapper around CORE::getpw*
555 Tie/RefHash.pm Base class for tied hashes with references as keys
557 UNIVERSAL.pm Base class for *ALL* classes
561 The IO module provides a simple mechanism to load all of the IO modules at one
562 go. Currently this includes:
570 For more information on any of these modules, please see its
571 respective documentation.
575 The Math::Complex module has been totally rewritten, and now supports
576 more operations. These are overloaded:
578 + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
580 And these functions are now exported:
584 tan cotan asin acos atan acotan
585 sinh cosh tanh cotanh asinh acosh atanh acotanh
590 There have been quite a few changes made to DB_File. Here are a few of
597 Fixed a handful of bugs.
601 By public demand, added support for the standard hash function exists().
605 Made it compatible with Berkeley DB 1.86.
609 Made negative subscripts work with RECNO interface.
613 Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
614 mode from 0640 to 0666.
618 Made DB_File automatically import the open() constants (O_RDWR,
619 O_CREAT etc.) from Fcntl, if available.
623 Updated documentation.
627 Refer to the HISTORY section in DB_File.pm for a complete list of
628 changes. Everything after DB_File 1.01 has been added since 5.003.
632 Major rewrite - support added for both udp echo and real icmp pings.
634 =head2 Overridden Built-ins
636 Many of the Perl built-ins returning lists now have
637 object-oriented overrides. These are:
649 For example, you can now say
653 $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);
655 =head1 Utility Changes
661 =item C<void> XSUBs now default to returning nothing
663 Due to a documentation/implementation bug in previous versions of
664 Perl, XSUBs with a return type of C<void> have actually been
665 returning one value. Usually that value was the GV for the XSUB,
666 but sometimes it was some already freed or reused value, which would
667 sometimes lead to program failure.
669 In Perl 5.004, if an XSUB is declared as returning C<void>, it
670 actually returns no value, i.e. an empty list (though there is a
671 backward-compatibility exception; see below). If your XSUB really
672 does return an SV, you should give it a return type of C<SV *>.
674 For backward compatibility, I<xsubpp> tries to guess whether a
675 C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
676 It does so by examining the text of the XSUB: if I<xsubpp> finds
677 what looks like an assignment to C<ST(0)>, it assumes that the
678 XSUB's return type is really C<SV *>.
682 =head1 C Language API Changes
686 =item C<gv_fetchmethod> and C<perl_call_sv>
688 The C<gv_fetchmethod> function finds a method for an object, just like
689 in Perl 5.003. The GV it returns may be a method cache entry.
690 However, in Perl 5.004, method cache entries are not visible to users;
691 therefore, they can no longer be passed directly to C<perl_call_sv>.
692 Instead, you should use the C<GvCV> macro on the GV to extract its CV,
693 and pass the CV to C<perl_call_sv>.
695 The most likely symptom of passing the result of C<gv_fetchmethod> to
696 C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
697 error on the I<second> call to a given method (since there is no cache
700 =item Extended API for manipulating hashes
702 Internal handling of hash keys has changed. The old hashtable API is
703 still fully supported, and will likely remain so. The additions to the
704 API allow passing keys as C<SV*>s, so that C<tied> hashes can be given
705 real scalars as keys rather than plain strings (non-tied hashes still
706 can only use strings as keys). New extensions must use the new hash
707 access functions and macros if they wish to use C<SV*> keys. These
708 additions also make it feasible to manipulate C<HE*>s (hash entries),
709 which can be more efficient. See L<perlguts> for details.
713 =head1 Documentation Changes
715 Many of the base and library pods were updated. These
716 new pods are included in section 1:
726 Locale support (internationalization and localization).
730 Tutorial on Perl OO programming.
734 Perl internal IO abstraction interface.
738 Although not new, this has been massively updated.
742 Although not new, this has been massively updated.
746 =head1 New Diagnostics
748 Several new conditions will trigger warnings that were
749 silent before. Some only affect certain platforms.
750 The following new warnings and errors outline these.
751 These messages are classified as follows (listed in
752 increasing order of desperation):
754 (W) A warning (optional).
755 (D) A deprecation (optional).
756 (S) A severe warning (mandatory).
757 (F) A fatal error (trappable).
758 (P) An internal error you should never see (trappable).
759 (X) A very fatal error (non-trappable).
760 (A) An alien error message (not generated by Perl).
764 =item "my" variable %s masks earlier declaration in same scope
766 (S) A lexical variable has been redeclared in the same scope, effectively
767 eliminating all access to the previous instance. This is almost always
768 a typographical error. Note that the earlier variable will still exist
769 until the end of the scope or until all closure referents to it are
772 =item %s argument is not a HASH element or slice
774 (F) The argument to delete() must be either a hash element, such as
777 $ref->[12]->{"susie"}
779 or a hash slice, such as
781 @foo{$bar, $baz, $xyzzy}
782 @{$ref->[12]}{"susie", "queue"}
784 =item Allocation too large: %lx
786 (X) You can't allocate more than 64K on an MSDOS machine.
788 =item Allocation too large
790 (F) You can't allocate more than 2^31+"small amount" bytes.
792 =item Attempt to free non-existent shared string
794 (P) Perl maintains a reference counted internal table of strings to
795 optimize the storage and access of hash keys and other strings. This
796 indicates someone tried to decrement the reference count of a string
797 that can no longer be found in the table.
799 =item Attempt to use reference as lvalue in substr
801 (W) You supplied a reference as the first argument to substr() used
802 as an lvalue, which is pretty strange. Perhaps you forgot to
803 dereference it first. See L<perlfunc/substr>.
805 =item Unsupported function fork
807 (F) Your version of executable does not support forking.
809 Note that under some systems, like OS/2, there may be different flavors of
810 Perl executables, some of which may support fork, some not. Try changing
811 the name you call Perl by to C<perl_>, C<perl__>, and so on.
813 =item Ill-formed logical name |%s| in prime_env_iter
815 (W) A warning peculiar to VMS. A logical name was encountered when preparing
816 to iterate over %ENV which violates the syntactic rules governing logical
817 names. Since it cannot be translated normally, it is skipped, and will not
818 appear in %ENV. This may be a benign occurrence, as some software packages
819 might directly modify logical name tables and introduce non-standard names,
820 or it may indicate that a logical name table has been corrupted.
822 =item Can't use bareword ("%s") as %s ref while "strict refs" in use
824 (F) Only hard references are allowed by "strict refs". Symbolic references
825 are disallowed. See L<perlref>.
827 =item Constant subroutine %s redefined
829 (S) You redefined a subroutine which had previously been eligible for
830 inlining. See L<perlsub/"Constant Functions"> for commentary and
835 (F) You passed die() an empty string (the equivalent of C<die "">) or
836 you called it with no args and both C<$@> and C<$_> were empty.
838 =item Integer overflow in hex number
840 (S) The literal hex number you have specified is too big for your
841 architecture. On a 32-bit architecture the largest hex literal is
844 =item Integer overflow in octal number
846 (S) The literal octal number you have specified is too big for your
847 architecture. On a 32-bit architecture the largest octal literal is
850 =item Name "%s::%s" used only once: possible typo
852 (W) Typographical errors often show up as unique variable names.
853 If you had a good reason for having a unique name, then just mention
854 it again somehow to suppress the message (the C<use vars> pragma is
855 provided for just this purpose).
857 =item Null picture in formline
859 (F) The first argument to formline must be a valid format picture
860 specification. It was found to be empty, which probably means you
861 supplied it an uninitialized value. See L<perlform>.
863 =item Offset outside string
865 (F) You tried to do a read/write/send/recv operation with an offset
866 pointing outside the buffer. This is difficult to imagine.
867 The sole exception to this is that C<sysread()>ing past the buffer
868 will extend the buffer and zero pad the new area.
870 =item Stub found while resolving method `%s' overloading `%s' in package `%s'
872 (P) Overloading resolution over @ISA tree may be broken by importing stubs.
873 Stubs should never be implicitely created, but explicit calls to C<can>
876 =item Cannot resolve method `%s' overloading `%s' in package `s'
878 (P) Internal error trying to resolve overloading specified by a method
879 name (as opposed to a subroutine reference).
883 (X|F) The malloc() function returned 0, indicating there was insufficient
884 remaining memory (or virtual memory) to satisfy the request.
886 The request was judged to be small, so the possibility to trap it
887 depends on the way Perl was compiled. By default it is not trappable.
888 However, if compiled for this, Perl may use the contents of C<$^M> as
889 an emergency pool after die()ing with this message. In this case the
890 error is trappable I<once>.
892 =item Out of memory during request for %s
894 (F) The malloc() function returned 0, indicating there was insufficient
895 remaining memory (or virtual memory) to satisfy the request. However,
896 the request was judged large enough (compile-time default is 64K), so
897 a possibility to shut down by trapping this error is granted.
899 =item Possible attempt to put comments in qw() list
901 (W) qw() lists contain items separated by whitespace; as with literal
902 strings, comment characters are not ignored, but are instead treated
903 as literal data. (You may have used different delimiters than the
904 exclamation marks parentheses shown here; braces are also frequently
907 You probably wrote something like this:
914 when you should have written this:
921 If you really want comments, build your list the
922 old-fashioned way, with quotes and commas:
926 'b', # another comment
929 =item Possible attempt to separate words with commas
931 (W) qw() lists contain items separated by whitespace; therefore commas
932 aren't needed to separate the items. (You may have used different
933 delimiters than the parentheses shown here; braces are also frequently
936 You probably wrote something like this:
940 which puts literal commas into some of the list items. Write it without
941 commas if you don't want them to appear in your data:
945 =item Scalar value @%s{%s} better written as $%s{%s}
947 (W) You've used a hash slice (indicated by @) to select a single element of
948 a hash. Generally it's better to ask for a scalar value (indicated by $).
949 The difference is that C<$foo{&bar}> always behaves like a scalar, both when
950 assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
951 like a list when you assign to it, and provides a list context to its
952 subscript, which can do weird things if you're expecting only one subscript.
954 =item untie attempted while %d inner references still exist
956 (W) A copy of the object returned from C<tie> (or C<tied>) was still
957 valid when C<untie> was called.
959 =item Value of %s construct can be "0"; test with defined()
961 (W) In a conditional expression, you used <HANDLE>, <*> (glob), or
962 C<readdir> as a boolean value. Each of these constructs can return a
963 value of "0"; that would make the conditional expression false, which
964 is probably not what you intended. When using these constructs in
965 conditional expressions, test their values with the C<defined> operator.
967 =item Variable "%s" may be unavailable
969 (W) An inner (nested) I<anonymous> subroutine is inside a I<named>
970 subroutine, and outside that is another subroutine; and the anonymous
971 (innermost) subroutine is referencing a lexical variable defined in
972 the outermost subroutine. For example:
974 sub outermost { my $a; sub middle { sub { $a } } }
976 If the anonymous subroutine is called or referenced (directly or
977 indirectly) from the outermost subroutine, it will share the variable
978 as you would expect. But if the anonymous subroutine is called or
979 referenced when the outermost subroutine is not active, it will see
980 the value of the shared variable as it was before and during the
981 *first* call to the outermost subroutine, which is probably not what
984 In these circumstances, it is usually best to make the middle
985 subroutine anonymous, using the C<sub {}> syntax. Perl has specific
986 support for shared variables in nested anonymous subroutines; a named
987 subroutine in between interferes with this feature.
989 =item Variable "%s" will not stay shared
991 (W) An inner (nested) I<named> subroutine is referencing a lexical
992 variable defined in an outer subroutine.
994 When the inner subroutine is called, it will probably see the value of
995 the outer subroutine's variable as it was before and during the
996 *first* call to the outer subroutine; in this case, after the first
997 call to the outer subroutine is complete, the inner and outer
998 subroutines will no longer share a common value for the variable. In
999 other words, the variable will no longer be shared.
1001 Furthermore, if the outer subroutine is anonymous and references a
1002 lexical variable outside itself, then the outer and inner subroutines
1003 will I<never> share the given variable.
1005 This problem can usually be solved by making the inner subroutine
1006 anonymous, using the C<sub {}> syntax. When inner anonymous subs that
1007 reference variables in outer subroutines are called or referenced,
1008 they are automatically re-bound to the current values of such
1011 =item Warning: something's wrong
1013 (W) You passed warn() an empty string (the equivalent of C<warn "">) or
1014 you called it with no args and C<$_> was empty.
1016 =item Got an error from DosAllocMem
1018 (P) An error peculiar to OS/2. Most probably you're using an obsolete
1019 version of Perl, and this should not happen anyway.
1021 =item Malformed PERLLIB_PREFIX
1023 (F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
1031 with non-empty prefix1 and prefix2. If C<prefix1> is indeed a prefix of
1032 a builtin library search path, prefix2 is substituted. The error may appear
1033 if components are not found, or are too long. See L<perlos2/"PERLLIB_PREFIX">.
1035 =item PERL_SH_DIR too long
1037 (F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
1038 C<sh>-shell in. See L<perlos2/"PERL_SH_DIR">.
1040 =item Process terminated by SIG%s
1042 (W) This is a standard message issued by OS/2 applications, while *nix
1043 applications die in silence. It is considered a feature of the OS/2
1044 port. One can easily disable this by appropriate sighandlers, see
1045 L<perlipc/"Signals">. See L<perlos2/"Process terminated by SIGTERM/SIGINT">.
1051 If you find what you think is a bug, you might check the headers of
1052 recently posted articles in the comp.lang.perl.misc newsgroup.
1053 There may also be information at http://www.perl.com/perl/, the Perl
1056 If you believe you have an unreported bug, please run the B<perlbug>
1057 program included with your release. Make sure you trim your bug down
1058 to a tiny but sufficient test case. Your bug report, along with the
1059 output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
1060 analysed by the Perl porting team.
1064 The F<Changes> file for exhaustive details on what changed.
1066 The F<INSTALL> file for how to build Perl. This file has been
1067 significantly updated for 5.004, so even veteran users should
1070 The F<README> file for general stuff.
1072 The F<Copying> file for copyright information.
1076 Constructed by Tom Christiansen, grabbing material with permission
1077 from innumerable contributors, with kibitzing by more than a few Perl
1080 Last update: Tue Jan 14 14:03:02 EST 1997