extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / pod / perl5005delta.pod
CommitLineData
01784f0d 1=head1 NAME
2
688005af 3perl5005delta - what's new for perl5.005
01784f0d 4
5=head1 DESCRIPTION
6
7This document describes differences between the 5.004 release and this one.
8
429b3afa 9=head1 About the new versioning system
10
9cde0e7f 11Perl is now developed on two tracks: a maintenance track that makes
12small, safe updates to released production versions with emphasis on
13compatibility; and a development track that pursues more aggressive
14evolution. Maintenance releases (which should be considered production
15quality) have subversion numbers that run from C<1> to C<49>, and
16development releases (which should be considered "alpha" quality) run
17from C<50> to C<99>.
18
19Perl 5.005 is the combined product of the new dual-track development
20scheme.
21
01784f0d 22=head1 Incompatible Changes
23
429b3afa 24=head2 WARNING: This version is not binary compatible with Perl 5.004.
25
26Starting with Perl 5.004_50 there were many deep and far-reaching changes
27to the language internals. If you have dynamically loaded extensions
28that you built under perl 5.003 or 5.004, you can continue to use them
29with 5.004, but you will need to rebuild and reinstall those extensions
b4bc034f 30to use them 5.005. See F<INSTALL> for detailed instructions on how to
429b3afa 31upgrade.
32
7ea97eb9 33=head2 Default installation structure has changed
429b3afa 34
7ea97eb9 35The new Configure defaults are designed to allow a smooth upgrade from
b4bc034f 365.004 to 5.005, but you should read F<INSTALL> for a detailed
7ea97eb9 37discussion of the changes in order to adapt them to your system.
429b3afa 38
39=head2 Perl Source Compatibility
40
41When none of the experimental features are enabled, there should be
9cde0e7f 42very few user-visible Perl source compatibility issues.
429b3afa 43
44If threads are enabled, then some caveats apply. C<@_> and C<$_> become
45lexical variables. The effect of this should be largely transparent to
46the user, but there are some boundary conditions under which user will
9cde0e7f 47need to be aware of the issues. For example, C<local(@_)> results in
48a "Can't localize lexical variable @_ ..." message. This may be enabled
49in a future version.
429b3afa 50
fe61ab85 51Some new keywords have been introduced. These are generally expected to
9cde0e7f 52have very little impact on compatibility. See L<New C<INIT> keyword>,
bc15cdb8 53L<New C<lock> keyword>, and L<New C<qrE<sol>E<sol>> operator>.
fe61ab85 54
55Certain barewords are now reserved. Use of these will provoke a warning
56if you have asked for them with the C<-w> switch.
9cde0e7f 57See L<C<our> is now a reserved word>.
fe61ab85 58
429b3afa 59=head2 C Source Compatibility
60
9cde0e7f 61There have been a large number of changes in the internals to support
62the new features in this release.
63
64=over 4
65
551e1d92 66=item *
67
68Core sources now require ANSI C compiler
429b3afa 69
9cde0e7f 70An ANSI C compiler is now B<required> to build perl. See F<INSTALL>.
71
551e1d92 72=item *
73
74All Perl global variables must now be referenced with an explicit prefix
9cde0e7f 75
76All Perl global variables that are visible for use by extensions now
77have a C<PL_> prefix. New extensions should C<not> refer to perl globals
78by their unqualified names. To preserve sanity, we provide limited
79backward compatibility for globals that are being widely used like
80C<sv_undef> and C<na> (which should now be written as C<PL_sv_undef>,
81C<PL_na> etc.)
82
83If you find that your XS extension does not compile anymore because a
84perl global is not visible, try adding a C<PL_> prefix to the global
85and rebuild.
86
87It is strongly recommended that all functions in the Perl API that don't
88begin with C<perl> be referenced with a C<Perl_> prefix. The bare function
89names without the C<Perl_> prefix are supported with macros, but this
90support may cease in a future release.
91
8a2949d9 92See L<perlapi>.
9cde0e7f 93
551e1d92 94=item *
95
96Enabling threads has source compatibility issues
429b3afa 97
9cde0e7f 98Perl built with threading enabled requires extensions to use the new
99C<dTHR> macro to initialize the handle to access per-thread data.
100If you see a compiler error that talks about the variable C<thr> not
101being declared (when building a module that has XS code), you need
102to add C<dTHR;> at the beginning of the block that elicited the error.
103
104The API function C<perl_get_sv("@",FALSE)> should be used instead of
105directly accessing perl globals as C<GvSV(errgv)>. The API call is
106backward compatible with existing perls and provides source compatibility
107with threading is enabled.
108
b687b08b 109See L<"C Source Compatibility"> for more information.
9cde0e7f 110
111=back
112
429b3afa 113=head2 Binary Compatibility
114
115This version is NOT binary compatible with older versions. All extensions
9cde0e7f 116will need to be recompiled. Further binaries built with threads enabled
117are incompatible with binaries built without. This should largely be
118transparent to the user, as all binary incompatible configurations have
119their own unique architecture name, and extension binaries get installed at
120unique locations. This allows coexistence of several configurations in
121the same directory hierarchy. See F<INSTALL>.
429b3afa 122
123=head2 Security fixes may affect compatibility
124
125A few taint leaks and taint omissions have been corrected. This may lead
126to "failure" of scripts that used to work with older versions. Compiling
127with -DINCOMPLETE_TAINTS provides a perl with minimal amounts of changes
128to the tainting behavior. But note that the resulting perl will have
129known insecurities.
130
131Oneliners with the C<-e> switch do not create temporary files anymore.
132
133=head2 Relaxed new mandatory warnings introduced in 5.004
134
fe61ab85 135Many new warnings that were introduced in 5.004 have been made
429b3afa 136optional. Some of these warnings are still present, but perl's new
137features make them less often a problem. See L<New Diagnostics>.
138
139=head2 Licensing
140
fe61ab85 141Perl has a new Social Contract for contributors. See F<Porting/Contract>.
429b3afa 142
fe61ab85 143The license included in much of the Perl documentation has changed.
b8957cf1 144Most of the Perl documentation was previously under the implicit GNU
145General Public License or the Artistic License (at the user's choice).
c2611fb3 146Now much of the documentation unambiguously states the terms under which
b8957cf1 147it may be distributed. Those terms are in general much less restrictive
3958b146 148than the GNU GPL. See L<perl> and the individual perl manpages listed
b8957cf1 149therein.
429b3afa 150
01784f0d 151=head1 Core Changes
152
01784f0d 153
429b3afa 154=head2 Threads
155
9cde0e7f 156WARNING: Threading is considered an B<experimental> feature. Details of the
429b3afa 157implementation may change without notice. There are known limitations
9cde0e7f 158and some bugs. These are expected to be fixed in future versions.
429b3afa 159
b4bc034f 160See F<README.threads>.
429b3afa 161
162=head2 Compiler
163
9cde0e7f 164WARNING: The Compiler and related tools are considered B<experimental>.
429b3afa 165Features may change without notice, and there are known limitations
9cde0e7f 166and bugs. Since the compiler is fully external to perl, the default
167configuration will build and install it.
429b3afa 168
fe61ab85 169The Compiler produces three different types of transformations of a
170perl program. The C backend generates C code that captures perl's state
171just before execution begins. It eliminates the compile-time overheads
172of the regular perl interpreter, but the run-time performance remains
173comparatively the same. The CC backend generates optimized C code
88c0f958 174equivalent to the code path at run-time. The CC backend has greater
fe61ab85 175potential for big optimizations, but only a few optimizations are
176implemented currently. The Bytecode backend generates a platform
177independent bytecode representation of the interpreter's state
178just before execution. Thus, the Bytecode back end also eliminates
179much of the compilation overhead of the interpreter.
180
181The compiler comes with several valuable utilities.
182
183C<B::Lint> is an experimental module to detect and warn about suspicious
184code, especially the cases that the C<-w> switch does not detect.
185
186C<B::Deparse> can be used to demystify perl code, and understand
187how perl optimizes certain constructs.
188
189C<B::Xref> generates cross reference reports of all definition and use
190of variables, subroutines and formats in a program.
429b3afa 191
fe61ab85 192C<B::Showlex> show the lexical variables used by a subroutine or file
193at a glance.
194
195C<perlcc> is a simple frontend for compiling perl.
429b3afa 196
9cde0e7f 197See C<ext/B/README>, L<B>, and the respective compiler modules.
429b3afa 198
199=head2 Regular Expressions
200
9cde0e7f 201Perl's regular expression engine has been seriously overhauled, and
202many new constructs are supported. Several bugs have been fixed.
203
204Here is an itemized summary:
205
206=over 4
207
208=item Many new and improved optimizations
209
210Changes in the RE engine:
211
212 Unneeded nodes removed;
213 Substrings merged together;
214 New types of nodes to process (SUBEXPR)* and similar expressions
215 quickly, used if the SUBEXPR has no side effects and matches
216 strings of the same length;
88c0f958 217 Better optimizations by lookup for constant substrings;
9cde0e7f 218 Better search for constants substrings anchored by $ ;
219
220Changes in Perl code using RE engine:
221
88c0f958 222 More optimizations to s/longer/short/;
9cde0e7f 223 study() was not working;
224 /blah/ may be optimized to an analogue of index() if $& $` $' not seen;
225 Unneeded copying of matched-against string removed;
226 Only matched part of the string is copying if $` $' were not seen;
227
228=item Many bug fixes
229
230Note that only the major bug fixes are listed here. See F<Changes> for others.
231
232 Backtracking might not restore start of $3.
233 No feedback if max count for * or + on "complex" subexpression
234 was reached, similarly (but at compile time) for {3,34567}
235 Primitive restrictions on max count introduced to decrease a
236 possibility of a segfault;
237 (ZERO-LENGTH)* could segfault;
238 (ZERO-LENGTH)* was prohibited;
88c0f958 239 Long REs were not allowed;
9cde0e7f 240 /RE/g could skip matches at the same position after a
241 zero-length match;
242
243=item New regular expression constructs
244
245The following new syntax elements are supported:
246
247 (?<=RE)
248 (?<!RE)
249 (?{ CODE })
250 (?i-x)
251 (?i:RE)
252 (?(COND)YES_RE|NO_RE)
253 (?>RE)
254 \z
255
256=item New operator for precompiled regular expressions
257
bc15cdb8 258See L<New C<qrE<sol>E<sol>> operator>.
9cde0e7f 259
260=item Other improvements
261
88c0f958 262 Better debugging output (possibly with colors),
263 even from non-debugging Perl;
9cde0e7f 264 RE engine code now looks like C, not like assembler;
88c0f958 265 Behaviour of RE modifiable by `use re' directive;
9cde0e7f 266 Improved documentation;
267 Test suite significantly extended;
268 Syntax [:^upper:] etc., reserved inside character classes;
269
270=item Incompatible changes
271
272 (?i) localized inside enclosing group;
273 $( is not interpolated into RE any more;
274 /RE/g may match at the same position (with non-zero length)
275 after a zero-length match (bug fix).
276
277=back
278
429b3afa 279See L<perlre> and L<perlop>.
280
281=head2 Improved malloc()
282
283See banner at the beginning of C<malloc.c> for details.
284
285=head2 Quicksort is internally implemented
286
9cde0e7f 287Perl now contains its own highly optimized qsort() routine. The new qsort()
288is resistant to inconsistent comparison functions, so Perl's C<sort()> will
289not provoke coredumps any more when given poorly written sort subroutines.
290(Some C library C<qsort()>s that were being used before used to have this
291problem.) In our testing, the new C<qsort()> required the minimal number
292of pair-wise compares on average, among all known C<qsort()> implementations.
293
429b3afa 294See C<perlfunc/sort>.
295
296=head2 Reliable signals
297
9cde0e7f 298Perl's signal handling is susceptible to random crashes, because signals
299arrive asynchronously, and the Perl runtime is not reentrant at arbitrary
300times.
fe61ab85 301
9cde0e7f 302However, one experimental implementation of reliable signals is available
303when threads are enabled. See C<Thread::Signal>. Also see F<INSTALL> for
304how to build a Perl capable of threads.
429b3afa 305
306=head2 Reliable stack pointers
307
fe61ab85 308The internals now reallocate the perl stack only at predictable times.
429b3afa 309In particular, magic calls never trigger reallocations of the stack,
310because all reentrancy of the runtime is handled using a "stack of stacks".
fe61ab85 311This should improve reliability of cached stack pointers in the internals
312and in XSUBs.
429b3afa 313
637e9122 314=head2 More generous treatment of carriage returns
315
b8957cf1 316Perl used to complain if it encountered literal carriage returns in
317scripts. Now they are mostly treated like whitespace within program text.
318Inside string literals and here documents, literal carriage returns are
453f83e7 319ignored if they occur paired with linefeeds, or get interpreted as whitespace
b8957cf1 320if they stand alone. This behavior means that literal carriage returns
321in files should be avoided. You can get the older, more compatible (but
322less generous) behavior by defining the preprocessor symbol
323C<PERL_STRICT_CR> when building perl. Of course, all this has nothing
324whatever to do with how escapes like C<\r> are handled within strings.
637e9122 325
326Note that this doesn't somehow magically allow you to keep all text files
327in DOS format. The generous treatment only applies to files that perl
328itself parses. If your C compiler doesn't allow carriage returns in
329files, you may still be unable to build modules that need a C compiler.
330
331=head2 Memory leaks
332
333C<substr>, C<pos> and C<vec> don't leak memory anymore when used in lvalue
334context. Many small leaks that impacted applications that embed multiple
335interpreters have been fixed.
336
337=head2 Better support for multiple interpreters
338
339The build-time option C<-DMULTIPLICITY> has had many of the details
340reworked. Some previously global variables that should have been
341per-interpreter now are. With care, this allows interpreters to call
342each other. See the C<PerlInterp> extension on CPAN.
343
407eff0f 344=head2 Behavior of local() on array and hash elements is now well-defined
429b3afa 345
407eff0f 346See L<perlsub/"Temporary Values via local()">.
429b3afa 347
348=head2 C<%!> is transparently tied to the L<Errno> module
349
fe61ab85 350See L<perlvar>, and L<Errno>.
429b3afa 351
352=head2 Pseudo-hashes are supported
353
354See L<perlref>.
355
356=head2 C<EXPR foreach EXPR> is supported
357
358See L<perlsyn>.
359
429b3afa 360=head2 Keywords can be globally overridden
361
362See L<perlsub>.
363
364=head2 C<$^E> is meaningful on Win32
365
366See L<perlvar>.
367
368=head2 C<foreach (1..1000000)> optimized
369
370C<foreach (1..1000000)> is now optimized into a counting loop. It does
371not try to allocate a 1000000-size list anymore.
372
373=head2 C<Foo::> can be used as implicitly quoted package name
374
9cde0e7f 375Barewords caused unintuitive behavior when a subroutine with the same
376name as a package happened to be defined. Thus, C<new Foo @args>,
377use the result of the call to C<Foo()> instead of C<Foo> being treated
378as a literal. The recommended way to write barewords in the indirect
379object slot is C<new Foo:: @args>. Note that the method C<new()> is
380called with a first argument of C<Foo>, not C<Foo::> when you do that.
429b3afa 381
382=head2 C<exists $Foo::{Bar::}> tests existence of a package
383
9cde0e7f 384It was impossible to test for the existence of a package without
385actually creating it before. Now C<exists $Foo::{Bar::}> can be
386used to test if the C<Foo::Bar> namespace has been created.
429b3afa 387
388=head2 Better locale support
389
390See L<perllocale>.
391
7ea97eb9 392=head2 Experimental support for 64-bit platforms
429b3afa 393
7ea97eb9 394Perl5 has always had 64-bit support on systems with 64-bit longs.
395Starting with 5.005, the beginnings of experimental support for systems
396with 32-bit long and 64-bit 'long long' integers has been added.
397If you add -DUSE_LONG_LONG to your ccflags in config.sh (or manually
398define it in perl.h) then perl will be built with 'long long' support.
399There will be many compiler warnings, and the resultant perl may not
400work on all systems. There are many other issues related to
401third-party extensions and libraries. This option exists to allow
402people to work on those issues.
429b3afa 403
404=head2 prototype() returns useful results on builtins
405
406See L<perlfunc/prototype>.
407
1a159553 408=head2 Extended support for exception handling
409
410C<die()> now accepts a reference value, and C<$@> gets set to that
411value in exception traps. This makes it possible to propagate
9cde0e7f 412exception objects. This is an undocumented B<experimental> feature.
1a159553 413
429b3afa 414=head2 Re-blessing in DESTROY() supported for chaining DESTROY() methods
415
416See L<perlobj/Destructors>.
417
418=head2 All C<printf> format conversions are handled internally
419
420See L<perlfunc/printf>.
421
422=head2 New C<INIT> keyword
423
fe61ab85 424C<INIT> subs are like C<BEGIN> and C<END>, but they get run just before
425the perl runtime begins execution. e.g., the Perl Compiler makes use of
426C<INIT> blocks to initialize and resolve pointers to XSUBs.
429b3afa 427
429b3afa 428=head2 New C<lock> keyword
429
fe61ab85 430The C<lock> keyword is the fundamental synchronization primitive
431in threaded perl. When threads are not enabled, it is currently a noop.
432
429b3afa 433To minimize impact on source compatibility this keyword is "weak", i.e., any
434user-defined subroutine of the same name overrides it, unless a C<use Thread>
435has been seen.
436
fe61ab85 437=head2 New C<qr//> operator
438
439The C<qr//> operator, which is syntactically similar to the other quote-like
0a92e3a8 440operators, is used to create precompiled regular expressions. This compiled
fe61ab85 441form can now be explicitly passed around in variables, and interpolated in
0a92e3a8 442other regular expressions. See L<perlop>.
fe61ab85 443
444=head2 C<our> is now a reserved word
445
9cde0e7f 446Calling a subroutine with the name C<our> will now provoke a warning when
447using the C<-w> switch.
448
429b3afa 449=head2 Tied arrays are now fully supported
450
451See L<Tie::Array>.
452
453=head2 Tied handles support is better
454
455Several missing hooks have been added. There is also a new base class for
456TIEARRAY implementations. See L<Tie::Array>.
457
6bb4e6d4 458=head2 4th argument to substr
459
460substr() can now both return and replace in one operation. The optional
4614th argument is the replacement string. See L<perlfunc/substr>.
462
463=head2 Negative LENGTH argument to splice
464
88c0f958 465splice() with a negative LENGTH argument now work similar to what the
6bb4e6d4 466LENGTH did for substr(). Previously a negative LENGTH was treated as
4670. See L<perlfunc/splice>.
468
407eff0f 469=head2 Magic lvalues are now more magical
470
471When you say something like C<substr($x, 5) = "hi">, the scalar returned
472by substr() is special, in that any modifications to it affect $x.
473(This is called a 'magic lvalue' because an 'lvalue' is something on
474the left side of an assignment.) Normally, this is exactly what you
475would expect to happen, but Perl uses the same magic if you use substr(),
476pos(), or vec() in a context where they might be modified, like taking
477a reference with C<\> or as an argument to a sub that modifies C<@_>.
478In previous versions, this 'magic' only went one way, but now changes
479to the scalar the magic refers to ($x in the above example) affect the
480magic lvalue too. For instance, this code now acts differently:
481
482 $x = "hello";
483 sub printit {
484 $x = "g'bye";
485 print $_[0], "\n";
486 }
487 printit(substr($x, 0, 5));
488
489In previous versions, this would print "hello", but it now prints "g'bye".
490
c47ff5f1 491=head2 <> now reads in records
3bf5f72b 492
c2611fb3 493If C<$/> is a reference to an integer, or a scalar that holds an integer,
c47ff5f1 494<> will read in records instead of lines. For more info, see
ffc145e8 495L<perlvar/$E<sol>>.
429b3afa 496
497=head1 Supported Platforms
498
499Configure has many incremental improvements. Site-wide policy for building
fe61ab85 500perl can now be made persistent, via Policy.sh. Configure also records
7ea97eb9 501the command-line arguments used in F<config.sh>.
429b3afa 502
503=head2 New Platforms
504
b4bc034f 505BeOS is now supported. See F<README.beos>.
429b3afa 506
b4bc034f 507DOS is now supported under the DJGPP tools. See F<README.dos> (installed
508as L<perldos> on some systems).
429b3afa 509
b4bc034f 510MiNT is now supported. See F<README.mint>.
f3d48bde 511
b4bc034f 512MPE/iX is now supported. See F<README.mpeix>.
1d84e8df 513
b4bc034f 514MVS (aka OS390, aka Open Edition) is now supported. See F<README.os390>
515(installed as L<perlos390> on some systems).
6c67e1bb 516
b4bc034f 517Stratus VOS is now supported. See F<README.vos>.
9d116dd7 518
429b3afa 519=head2 Changes in existing support
520
521Win32 support has been vastly enhanced. Support for Perl Object, a C++
522encapsulation of Perl. GCC and EGCS are now supported on Win32.
9cde0e7f 523See F<README.win32>, aka L<perlwin32>.
429b3afa 524
b4bc034f 525VMS configuration system has been rewritten. See F<README.vms> (installed
526as L<README_vms> on some systems).
429b3afa 527
9cde0e7f 528The hints files for most Unix platforms have seen incremental improvements.
429b3afa 529
530=head1 Modules and Pragmata
531
532=head2 New Modules
533
13a2d996 534=over 4
429b3afa 535
536=item B
537
9cde0e7f 538Perl compiler and tools. See L<B>.
429b3afa 539
540=item Data::Dumper
541
542A module to pretty print Perl data. See L<Data::Dumper>.
543
f3d48bde 544=item Dumpvalue
545
546A module to dump perl values to the screen. See L<Dumpvalue>.
547
429b3afa 548=item Errno
549
550A module to look up errors more conveniently. See L<Errno>.
551
552=item File::Spec
553
554A portable API for file operations.
555
556=item ExtUtils::Installed
557
558Query and manage installed modules.
559
560=item ExtUtils::Packlist
561
562Manipulate .packlist files.
563
564=item Fatal
565
566Make functions/builtins succeed or die.
567
568=item IPC::SysV
569
570Constants and other support infrastructure for System V IPC operations
571in perl.
572
573=item Test
574
575A framework for writing testsuites.
01784f0d 576
429b3afa 577=item Tie::Array
578
579Base class for tied arrays.
580
581=item Tie::Handle
582
583Base class for tied handles.
584
585=item Thread
586
587Perl thread creation, manipulation, and support.
588
589=item attrs
590
591Set subroutine attributes.
592
593=item fields
594
595Compile-time class fields.
596
597=item re
598
599Various pragmata to control behavior of regular expressions.
600
601=back
602
603=head2 Changes in existing modules
604
13a2d996 605=over 4
429b3afa 606
2eac2f99 607=item Benchmark
608
609You can now run tests for I<x> seconds instead of guessing the right
610number of tests to run.
611
cea6626f 612Keeps better time.
613
f3d48bde 614=item Carp
615
616Carp has a new function cluck(). cluck() warns, like carp(), but also adds
617a stack backtrace to the error message, like confess().
618
429b3afa 619=item CGI
620
621CGI has been updated to version 2.42.
622
2eac2f99 623=item Fcntl
624
625More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
626large (more than 4G) file access (the 64-bit support is not yet
627working, though, so no need to get overly excited), Free/Net/OpenBSD
628locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and
629O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
630
631=item Math::Complex
f3d48bde 632
633The accessors methods Re, Im, arg, abs, rho, theta, methods can
634($z->Re()) now also act as mutators ($z->Re(3)).
635
636=item Math::Trig
637
2eac2f99 638A little bit of radial trigonometry (cylindrical and spherical) added,
639for example the great circle distance.
640
429b3afa 641=item POSIX
642
643POSIX now has its own platform-specific hints files.
644
645=item DB_File
646
647DB_File supports version 2.x of Berkeley DB. See C<ext/DB_File/Changes>.
648
649=item MakeMaker
650
651MakeMaker now supports writing empty makefiles, provides a way to
652specify that site umask() policy should be honored. There is also
653better support for manipulation of .packlist files, and getting
654information about installed modules.
655
7ea97eb9 656Extensions that have both architecture-dependent and
657architecture-independent files are now always installed completely in
658the architecture-dependent locations. Previously, the shareable parts
659were shared both across architectures and across perl versions and were
660therefore liable to be overwritten with newer versions that might have
661subtle incompatibilities.
662
429b3afa 663=item CPAN
664
884bad00 665See L<perlmodinstall> and L<CPAN>.
429b3afa 666
667=item Cwd
668
669Cwd::cwd is faster on most platforms.
670
429b3afa 671=back
01784f0d 672
673=head1 Utility Changes
674
637e9122 675C<h2ph> and related utilities have been vastly overhauled.
676
677C<perlcc>, a new experimental front end for the compiler is available.
429b3afa 678
637e9122 679The crude GNU C<configure> emulator is now called C<configure.gnu> to
680avoid trampling on C<Configure> under case-insensitive filesystems.
429b3afa 681
637e9122 682C<perldoc> used to be rather slow. The slower features are now optional.
683In particular, case-insensitive searches need the C<-i> switch, and
684recursive searches need C<-r>. You can set these switches in the
685C<PERLDOC> environment variable to get the old behavior.
7ea97eb9 686
01784f0d 687=head1 Documentation Changes
688
429b3afa 689Config.pm now has a glossary of variables.
690
9cde0e7f 691F<Porting/patching.pod> has detailed instructions on how to create and
429b3afa 692submit patches for perl.
693
9cde0e7f 694L<perlport> specifies guidelines on how to write portably.
695
696L<perlmodinstall> describes how to fetch and install modules from C<CPAN>
697sites.
698
699Some more Perl traps are documented now. See L<perltrap>.
700
f3d48bde 701L<perlopentut> gives a tutorial on using open().
702
703L<perlreftut> gives a tutorial on references.
704
705L<perlthrtut> gives a tutorial on threads.
706
429b3afa 707=head1 New Diagnostics
708
13a2d996 709=over 4
429b3afa 710
711=item Ambiguous call resolved as CORE::%s(), qualify as such or use &
712
713(W) A subroutine you have declared has the same name as a Perl keyword,
714and you have used the name without qualification for calling one or the
715other. Perl decided to call the builtin because the subroutine is
716not imported.
717
718To force interpretation as a subroutine call, either put an ampersand
719before the subroutine name, or qualify the name with its package.
720Alternatively, you can import the subroutine (or pretend that it's
721imported with the C<use subs> pragma).
722
723To silently interpret it as the Perl operator, use the C<CORE::> prefix
724on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
725to be an object method (see L<attrs>).
726
727=item Bad index while coercing array into hash
728
729(F) The index looked up in the hash found as the 0'th element of a
730pseudo-hash is not legal. Index values must be at 1 or greater.
731See L<perlref>.
732
733=item Bareword "%s" refers to nonexistent package
734
735(W) You used a qualified bareword of the form C<Foo::>, but
736the compiler saw no other uses of that namespace before that point.
737Perhaps you need to predeclare a package?
738
739=item Can't call method "%s" on an undefined value
740
741(F) You used the syntax of a method call, but the slot filled by the
742object reference or package name contains an undefined value.
743Something like this will reproduce the error:
744
745 $BADREF = 42;
746 process $BADREF 1,2,3;
747 $BADREF->process(1,2,3);
748
f3d48bde 749=item Can't check filesystem of script "%s" for nosuid
750
751(P) For some reason you can't check the filesystem of the script for nosuid.
752
429b3afa 753=item Can't coerce array into hash
754
755(F) You used an array where a hash was expected, but the array has no
756information on how to map from keys to array indices. You can do that
757only with arrays that have a hash reference at index 0.
758
759=item Can't goto subroutine from an eval-string
760
761(F) The "goto subroutine" call can't be used to jump out of an eval "string".
762(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)
763
0ebe0038 764=item Can't localize pseudo-hash element
765
c47ff5f1 766(F) You said something like C<< local $ar->{'key'} >>, where $ar is
0ebe0038 767a reference to a pseudo-hash. That hasn't been implemented yet, but
768you can get a similar effect by localizing the corresponding array
c47ff5f1 769element directly -- C<< local $ar->[$ar->[0]{'key'}] >>.
0ebe0038 770
429b3afa 771=item Can't use %%! because Errno.pm is not available
772
773(F) The first time the %! hash is used, perl automatically loads the
774Errno.pm module. The Errno module is expected to tie the %! hash to
775provide symbolic names for C<$!> errno values.
776
429b3afa 777=item Cannot find an opnumber for "%s"
778
779(F) A string of a form C<CORE::word> was given to prototype(), but
780there is no builtin with the name C<word>.
781
782=item Character class syntax [. .] is reserved for future extensions
783
784(W) Within regular expression character classes ([]) the syntax beginning
785with "[." and ending with ".]" is reserved for future extensions.
786If you need to represent those character sequences inside a regular
787expression character class, just quote the square brackets with the
788backslash: "\[." and ".\]".
789
790=item Character class syntax [: :] is reserved for future extensions
791
792(W) Within regular expression character classes ([]) the syntax beginning
793with "[:" and ending with ":]" is reserved for future extensions.
794If you need to represent those character sequences inside a regular
795expression character class, just quote the square brackets with the
796backslash: "\[:" and ":\]".
797
798=item Character class syntax [= =] is reserved for future extensions
799
800(W) Within regular expression character classes ([]) the syntax
801beginning with "[=" and ending with "=]" is reserved for future extensions.
802If you need to represent those character sequences inside a regular
803expression character class, just quote the square brackets with the
804backslash: "\[=" and "=\]".
805
806=item %s: Eval-group in insecure regular expression
807
808(F) Perl detected tainted data when trying to compile a regular expression
809that contains the C<(?{ ... })> zero-width assertion, which is unsafe.
810See L<perlre/(?{ code })>, and L<perlsec>.
811
812=item %s: Eval-group not allowed, use re 'eval'
813
814(F) A regular expression contained the C<(?{ ... })> zero-width assertion,
815but that construct is only allowed when the C<use re 'eval'> pragma is
816in effect. See L<perlre/(?{ code })>.
817
818=item %s: Eval-group not allowed at run time
819
820(F) Perl tried to compile a regular expression containing the C<(?{ ... })>
821zero-width assertion at run time, as it would when the pattern contains
822interpolated values. Since that is a security risk, it is not allowed.
823If you insist, you may still do this by explicitly building the pattern
824from an interpolated string at run time and using that in an eval().
825See L<perlre/(?{ code })>.
826
827=item Explicit blessing to '' (assuming package main)
828
829(W) You are blessing a reference to a zero length string. This has
830the effect of blessing the reference into the package main. This is
831usually not what you want. Consider providing a default target
ae6c4aac 832package, e.g. bless($ref, $p || 'MyPackage');
429b3afa 833
834=item Illegal hex digit ignored
835
836(W) You may have tried to use a character other than 0 - 9 or A - F in a
837hexadecimal number. Interpretation of the hexadecimal number stopped
838before the illegal character.
839
840=item No such array field
841
842(F) You tried to access an array as a hash, but the field name used is
843not defined. The hash at index 0 should map all valid field names to
844array indices for that to work.
845
846=item No such field "%s" in variable %s of type %s
847
848(F) You tried to access a field of a typed variable where the type
849does not know about the field name. The field names are looked up in
850the %FIELDS hash in the type package at compile time. The %FIELDS hash
851is usually set up with the 'fields' pragma.
852
853=item Out of memory during ridiculously large request
854
855(F) You can't allocate more than 2^31+"small amount" bytes. This error
856is most likely to be caused by a typo in the Perl program. e.g., C<$arr[time]>
857instead of C<$arr[$time]>.
858
859=item Range iterator outside integer range
860
861(F) One (or both) of the numeric arguments to the range operator ".."
862are outside the range which can be represented by integers internally.
863One possible workaround is to force Perl to use magical string
864increment by prepending "0" to your numbers.
865
551e1d92 866=item Recursive inheritance detected while looking for method '%s' %s
429b3afa 867
868(F) More than 100 levels of inheritance were encountered while invoking a
869method. Probably indicates an unintended loop in your inheritance hierarchy.
870
871=item Reference found where even-sized list expected
872
873(W) You gave a single reference where Perl was expecting a list with
874an even number of elements (for assignment to a hash). This
875usually means that you used the anon hash constructor when you meant
876to use parens. In any case, a hash requires key/value B<pairs>.
877
878 %hash = { one => 1, two => 2, }; # WRONG
879 %hash = [ qw/ an anon array / ]; # WRONG
880 %hash = ( one => 1, two => 2, ); # right
881 %hash = qw( one 1 two 2 ); # also fine
882
883=item Undefined value assigned to typeglob
884
885(W) An undefined value was assigned to a typeglob, a la C<*foo = undef>.
886This does nothing. It's possible that you really mean C<undef *foo>.
887
888=item Use of reserved word "%s" is deprecated
889
890(D) The indicated bareword is a reserved word. Future versions of perl
891may use it as a keyword, so you're better off either explicitly quoting
892the word in a manner appropriate for its context of use, or using a
893different name altogether. The warning can be suppressed for subroutine
894names by either adding a C<&> prefix, or using a package qualifier,
895e.g. C<&our()>, or C<Foo::our()>.
896
897=item perl: warning: Setting locale failed.
898
899(S) The whole warning message will look something like:
900
901 perl: warning: Setting locale failed.
902 perl: warning: Please check that your locale settings:
903 LC_ALL = "En_US",
904 LANG = (unset)
905 are supported and installed on your system.
906 perl: warning: Falling back to the standard locale ("C").
907
908Exactly what were the failed locale settings varies. In the above the
909settings were that the LC_ALL was "En_US" and the LANG had no value.
910This error means that Perl detected that you and/or your system
911administrator have set up the so-called variable system but Perl could
912not use those settings. This was not dead serious, fortunately: there
913is a "default locale" called "C" that Perl can and will use, the
914script will be run. Before you really fix the problem, however, you
915will get the same error message each time you run Perl. How to really
2eac2f99 916fix the problem can be found in L<perllocale/"LOCALE PROBLEMS">.
429b3afa 917
918=back
919
920
921=head1 Obsolete Diagnostics
922
13a2d996 923=over 4
6cc33c6d 924
429b3afa 925=item Can't mktemp()
926
927(F) The mktemp() routine failed for some reason while trying to process
928a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
929
2eac2f99 930Removed because B<-e> doesn't use temporary files any more.
931
429b3afa 932=item Can't write to temp file for B<-e>: %s
933
934(F) The write routine failed for some reason while trying to process
935a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
936
2eac2f99 937Removed because B<-e> doesn't use temporary files any more.
938
429b3afa 939=item Cannot open temporary file
940
941(F) The create routine failed for some reason while trying to process
942a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
943
2eac2f99 944Removed because B<-e> doesn't use temporary files any more.
945
0f31cffe 946=item regexp too big
947
948(F) The current implementation of regular expressions uses shorts as
949address offsets within a string. Unfortunately this means that if
950the regular expression compiles to longer than 32767, it'll blow up.
951Usually when you want a regular expression this big, there is a better
be59e445 952way to do it with multiple statements. See L<perlre>.
953
f3d48bde 954=back
0f31cffe 955
f3d48bde 956=head1 Configuration Changes
0f31cffe 957
f3d48bde 958You can use "Configure -Uinstallusrbinperl" which causes installperl
959to skip installing perl also as /usr/bin/perl. This is useful if you
960prefer not to modify /usr/bin for some reason or another but harmful
961because many scripts assume to find Perl in /usr/bin/perl.
429b3afa 962
01784f0d 963=head1 BUGS
964
965If you find what you think is a bug, you might check the headers of
966recently posted articles in the comp.lang.perl.misc newsgroup.
f224927c 967There may also be information at http://www.perl.com/perl/ , the Perl
01784f0d 968Home Page.
969
970If you believe you have an unreported bug, please run the B<perlbug>
971program included with your release. Make sure you trim your bug down
972to a tiny but sufficient test case. Your bug report, along with the
973output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
974analysed by the Perl porting team.
975
976=head1 SEE ALSO
977
978The F<Changes> file for exhaustive details on what changed.
979
980The F<INSTALL> file for how to build Perl.
981
982The F<README> file for general stuff.
983
984The F<Artistic> and F<Copying> files for copyright information.
985
986=head1 HISTORY
429b3afa 987
6e238990 988Written by Gurusamy Sarathy <F<gsar@activestate.com>>, with many contributions
9cde0e7f 989from The Perl Porters.
990
991Send omissions or corrections to <F<perlbug@perl.com>>.
992
429b3afa 993=cut