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