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