extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / pod / perl5004delta.pod
CommitLineData
6ee623d5 1=head1 NAME
2
688005af 3perl5004delta - what's new for perl5.004
6ee623d5 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, Plan 9, LynxOS, VMS, OS/2,
14QNX, AmigaOS, and Windows NT. Perl runs on Windows 95 as well, but it
15cannot be built there, for lack of a reasonable command interpreter.
16
17=head1 Core Changes
18
19Most importantly, many bugs were fixed, including several security
20problems. See the F<Changes> file in the distribution for details.
21
22=head2 List assignment to %ENV works
23
24C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS
25where it generates a fatal error).
26
13a2d996 27=head2 Change to "Can't locate Foo.pm in @INC" error
28
29The error "Can't locate Foo.pm in @INC" now lists the contents of @INC
30for easier debugging.
6ee623d5 31
32=head2 Compilation option: Binary compatibility with 5.003
33
34There is a new Configure question that asks if you want to maintain
35binary compatibility with Perl 5.003. If you choose binary
36compatibility, you do not have to recompile your extensions, but you
37might have symbol conflicts if you embed Perl in another application,
38just as in the 5.003 release. By default, binary compatibility
39is preserved at the expense of symbol table pollution.
40
41=head2 $PERL5OPT environment variable
42
43You may now put Perl options in the $PERL5OPT environment variable.
44Unless Perl is running with taint checks, it will interpret this
45variable as if its contents had appeared on a "#!perl" line at the
46beginning of your script, except that hyphens are optional. PERL5OPT
47may only be used to set the following switches: B<-[DIMUdmw]>.
48
49=head2 Limitations on B<-M>, B<-m>, and B<-T> options
50
51The C<-M> and C<-m> options are no longer allowed on the C<#!> line of
52a script. If a script needs a module, it should invoke it with the
53C<use> pragma.
54
55The B<-T> option is also forbidden on the C<#!> line of a script,
56unless it was present on the Perl command line. Due to the way C<#!>
57works, this usually means that B<-T> must be in the first argument.
58Thus:
59
60 #!/usr/bin/perl -T -w
61
62will probably work for an executable script invoked as C<scriptname>,
63while:
64
65 #!/usr/bin/perl -w -T
66
67will probably fail under the same conditions. (Non-Unix systems will
68probably not follow this rule.) But C<perl scriptname> is guaranteed
69to fail, since then there is no chance of B<-T> being found on the
70command line before it is found on the C<#!> line.
71
72=head2 More precise warnings
73
74If you removed the B<-w> option from your Perl 5.003 scripts because it
75made Perl too verbose, we recommend that you try putting it back when
76you upgrade to Perl 5.004. Each new perl version tends to remove some
77undesirable warnings, while adding new warnings that may catch bugs in
78your scripts.
79
80=head2 Deprecated: Inherited C<AUTOLOAD> for non-methods
81
82Before Perl 5.004, C<AUTOLOAD> functions were looked up as methods
83(using the C<@ISA> hierarchy), even when the function to be autoloaded
84was called as a plain function (e.g. C<Foo::bar()>), not a method
c47ff5f1 85(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
6ee623d5 86
87Perl 5.005 will use method lookup only for methods' C<AUTOLOAD>s.
88However, there is a significant base of existing code that may be using
89the old behavior. So, as an interim step, Perl 5.004 issues an optional
90warning when a non-method uses an inherited C<AUTOLOAD>.
91
92The simple rule is: Inheritance will not work when autoloading
93non-methods. The simple fix for old code is: In any module that used to
94depend on inheriting C<AUTOLOAD> for non-methods from a base class named
95C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup.
96
97=head2 Previously deprecated %OVERLOAD is no longer usable
98
99Using %OVERLOAD to define overloading was deprecated in 5.003.
100Overloading is now defined using the overload pragma. %OVERLOAD is
101still used internally but should not be used by Perl scripts. See
102L<overload> for more details.
103
104=head2 Subroutine arguments created only when they're modified
105
106In Perl 5.004, nonexistent array and hash elements used as subroutine
107parameters are brought into existence only if they are actually
108assigned to (via C<@_>).
109
110Earlier versions of Perl vary in their handling of such arguments.
111Perl versions 5.002 and 5.003 always brought them into existence.
112Perl versions 5.000 and 5.001 brought them into existence only if
113they were not the first argument (which was almost certainly a bug).
114Earlier versions of Perl never brought them into existence.
115
116For example, given this code:
117
118 undef @a; undef %a;
119 sub show { print $_[0] };
120 sub change { $_[0]++ };
121 show($a[2]);
122 change($a{b});
123
124After this code executes in Perl 5.004, $a{b} exists but $a[2] does
125not. In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed
126(but $a[2]'s value would have been undefined).
127
128=head2 Group vector changeable with C<$)>
129
130The C<$)> special variable has always (well, in Perl 5, at least)
131reflected not only the current effective group, but also the group list
132as returned by the C<getgroups()> C function (if there is one).
133However, until this release, there has not been a way to call the
134C<setgroups()> C function from Perl.
135
136In Perl 5.004, assigning to C<$)> is exactly symmetrical with examining
137it: The first number in its string value is used as the effective gid;
138if there are any numbers after the first one, they are passed to the
139C<setgroups()> C function (if there is one).
140
141=head2 Fixed parsing of $$<digit>, &$<digit>, etc.
142
143Perl versions before 5.004 misinterpreted any type marker followed by
144"$" and a digit. For example, "$$0" was incorrectly taken to mean
145"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
146
147However, the developers of Perl 5.004 could not fix this bug completely,
148because at least two widely-used modules depend on the old meaning of
149"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
150old (broken) way inside strings; but it generates this message as a
151warning. And in Perl 5.005, this special treatment will cease.
152
153=head2 Fixed localization of $<digit>, $&, etc.
154
155Perl versions before 5.004 did not always properly localize the
156regex-related special variables. Perl 5.004 does localize them, as
157the documentation has always said it should. This may result in $1,
158$2, etc. no longer being set where existing programs use them.
159
160=head2 No resetting of $. on implicit close
161
162The documentation for Perl 5.0 has always stated that C<$.> is I<not>
163reset when an already-open file handle is reopened with no intervening
164call to C<close>. Due to a bug, perl versions 5.000 through 5.003
165I<did> reset C<$.> under that circumstance; Perl 5.004 does not.
166
167=head2 C<wantarray> may return undef
168
169The C<wantarray> operator returns true if a subroutine is expected to
170return a list, and false otherwise. In Perl 5.004, C<wantarray> can
171also return the undefined value if a subroutine's return value will
172not be used at all, which allows subroutines to avoid a time-consuming
173calculation of a return value if it isn't going to be used.
174
175=head2 C<eval EXPR> determines value of EXPR in scalar context
176
177Perl (version 5) used to determine the value of EXPR inconsistently,
178sometimes incorrectly using the surrounding context for the determination.
179Now, the value of EXPR (before being parsed by eval) is always determined in
180a scalar context. Once parsed, it is executed as before, by providing
181the context that the scope surrounding the eval provided. This change
182makes the behavior Perl4 compatible, besides fixing bugs resulting from
183the inconsistent behavior. This program:
184
185 @a = qw(time now is time);
186 print eval @a;
187 print '|', scalar eval @a;
188
189used to print something like "timenowis881399109|4", but now (and in perl4)
190prints "4|4".
191
192=head2 Changes to tainting checks
193
194A bug in previous versions may have failed to detect some insecure
195conditions when taint checks are turned on. (Taint checks are used
196in setuid or setgid scripts, or when explicitly turned on with the
197C<-T> invocation option.) Although it's unlikely, this may cause a
198previously-working script to now fail -- which should be construed
199as a blessing, since that indicates a potentially-serious security
200hole was just plugged.
201
202The new restrictions when tainting include:
203
13a2d996 204=over 4
6ee623d5 205
206=item No glob() or <*>
207
208These operators may spawn the C shell (csh), which cannot be made
209safe. This restriction will be lifted in a future version of Perl
210when globbing is implemented without the use of an external program.
211
212=item No spawning if tainted $CDPATH, $ENV, $BASH_ENV
213
214These environment variables may alter the behavior of spawned programs
215(especially shells) in ways that subvert security. So now they are
216treated as dangerous, in the manner of $IFS and $PATH.
217
218=item No spawning if tainted $TERM doesn't look like a terminal name
219
220Some termcap libraries do unsafe things with $TERM. However, it would be
221unnecessarily harsh to treat all $TERM values as unsafe, since only shell
222metacharacters can cause trouble in $TERM. So a tainted $TERM is
223considered to be safe if it contains only alphanumerics, underscores,
224dashes, and colons, and unsafe if it contains other characters (including
225whitespace).
226
227=back
228
229=head2 New Opcode module and revised Safe module
230
231A new Opcode module supports the creation, manipulation and
232application of opcode masks. The revised Safe module has a new API
233and is implemented using the new Opcode module. Please read the new
234Opcode and Safe documentation.
235
236=head2 Embedding improvements
237
238In older versions of Perl it was not possible to create more than one
239Perl interpreter instance inside a single process without leaking like a
240sieve and/or crashing. The bugs that caused this behavior have all been
241fixed. However, you still must take care when embedding Perl in a C
242program. See the updated perlembed manpage for tips on how to manage
243your interpreters.
244
245=head2 Internal change: FileHandle class based on IO::* classes
246
247File handles are now stored internally as type IO::Handle. The
248FileHandle module is still supported for backwards compatibility, but
249it is now merely a front end to the IO::* modules -- specifically,
250IO::Handle, IO::Seekable, and IO::File. We suggest, but do not
251require, that you use the IO::* modules in new code.
252
253In harmony with this change, C<*GLOB{FILEHANDLE}> is now just a
254backward-compatible synonym for C<*GLOB{IO}>.
255
256=head2 Internal change: PerlIO abstraction interface
257
258It is now possible to build Perl with AT&T's sfio IO package
259instead of stdio. See L<perlapio> for more details, and
260the F<INSTALL> file for how to use it.
261
262=head2 New and changed syntax
263
13a2d996 264=over 4
6ee623d5 265
266=item $coderef->(PARAMS)
267
268A subroutine reference may now be suffixed with an arrow and a
269(possibly empty) parameter list. This syntax denotes a call of the
270referenced subroutine, with the given parameters (if any).
271
c47ff5f1 272This new syntax follows the pattern of S<C<< $hashref->{FOO} >>> and
273S<C<< $aryref->[$foo] >>>: You may now write S<C<&$subref($foo)>> as
274S<C<< $subref->($foo) >>>. All these arrow terms may be chained;
275thus, S<C<< &{$table->{FOO}}($bar) >>> may now be written
276S<C<< $table->{FOO}->($bar) >>>.
6ee623d5 277
278=back
279
280=head2 New and changed builtin constants
281
13a2d996 282=over 4
6ee623d5 283
284=item __PACKAGE__
285
286The current package name at compile time, or the undefined value if
287there is no current package (due to a C<package;> directive). Like
288C<__FILE__> and C<__LINE__>, C<__PACKAGE__> does I<not> interpolate
289into strings.
290
291=back
292
293=head2 New and changed builtin variables
294
13a2d996 295=over 4
6ee623d5 296
297=item $^E
298
299Extended error message on some platforms. (Also known as
300$EXTENDED_OS_ERROR if you C<use English>).
301
302=item $^H
303
304The current set of syntax checks enabled by C<use strict>. See the
305documentation of C<strict> for more details. Not actually new, but
306newly documented.
307Because it is intended for internal use by Perl core components,
308there is no C<use English> long name for this variable.
309
310=item $^M
311
312By default, running out of memory it is not trappable. However, if
313compiled for this, Perl may use the contents of C<$^M> as an emergency
314pool after die()ing with this message. Suppose that your Perl were
315compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then
316
317 $^M = 'a' x (1<<16);
318
319would allocate a 64K buffer for use when in emergency.
320See the F<INSTALL> file for information on how to enable this option.
321As a disincentive to casual use of this advanced feature,
322there is no C<use English> long name for this variable.
323
324=back
325
326=head2 New and changed builtin functions
327
13a2d996 328=over 4
6ee623d5 329
330=item delete on slices
331
332This now works. (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
333
334=item flock
335
336is now supported on more platforms, prefers fcntl to lockf when
337emulating, and always flushes before (un)locking.
338
339=item printf and sprintf
340
341Perl now implements these functions itself; it doesn't use the C
342library function sprintf() any more, except for floating-point
343numbers, and even then only known flags are allowed. As a result, it
344is now possible to know which conversions and flags will work, and
345what they will do.
346
347The new conversions in Perl's sprintf() are:
348
349 %i a synonym for %d
350 %p a pointer (the address of the Perl value, in hexadecimal)
351 %n special: *stores* the number of characters output so far
352 into the next variable in the parameter list
353
354The new flags that go between the C<%> and the conversion are:
355
356 # prefix octal with "0", hex with "0x"
357 h interpret integer as C type "short" or "unsigned short"
358 V interpret integer as Perl's standard integer type
359
360Also, where a number would appear in the flags, an asterisk ("*") may
361be used instead, in which case Perl uses the next item in the
362parameter list as the given number (that is, as the field width or
363precision). If a field width obtained through "*" is negative, it has
364the same effect as the '-' flag: left-justification.
365
366See L<perlfunc/sprintf> for a complete list of conversion and flags.
367
368=item keys as an lvalue
369
370As an lvalue, C<keys> allows you to increase the number of hash buckets
371allocated for the given hash. This can gain you a measure of efficiency if
372you know the hash is going to get big. (This is similar to pre-extending
373an array by assigning a larger number to $#array.) If you say
374
375 keys %hash = 200;
376
377then C<%hash> will have at least 200 buckets allocated for it. These
378buckets will be retained even if you do C<%hash = ()>; use C<undef
379%hash> if you want to free the storage while C<%hash> is still in scope.
380You can't shrink the number of buckets allocated for the hash using
381C<keys> in this way (but you needn't worry about doing this by accident,
382as trying has no effect).
383
384=item my() in Control Structures
385
386You can now use my() (with or without the parentheses) in the control
387expressions of control structures such as:
388
389 while (defined(my $line = <>)) {
390 $line = lc $line;
391 } continue {
392 print $line;
393 }
394
395 if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
396 user_agrees();
397 } elsif ($answer =~ /^n(o)?$/i) {
398 user_disagrees();
399 } else {
400 chomp $answer;
401 die "`$answer' is neither `yes' nor `no'";
402 }
403
404Also, you can declare a foreach loop control variable as lexical by
405preceding it with the word "my". For example, in:
406
407 foreach my $i (1, 2, 3) {
408 some_function();
409 }
410
411$i is a lexical variable, and the scope of $i extends to the end of
412the loop, but not beyond it.
413
414Note that you still cannot use my() on global punctuation variables
415such as $_ and the like.
416
417=item pack() and unpack()
418
419A new format 'w' represents a BER compressed integer (as defined in
420ASN.1). Its format is a sequence of one or more bytes, each of which
421provides seven bits of the total value, with the most significant
422first. Bit eight of each byte is set, except for the last byte, in
423which bit eight is clear.
424
425If 'p' or 'P' are given undef as values, they now generate a NULL
426pointer.
427
428Both pack() and unpack() now fail when their templates contain invalid
429types. (Invalid types used to be ignored.)
430
431=item sysseek()
432
433The new sysseek() operator is a variant of seek() that sets and gets the
434file's system read/write position, using the lseek(2) system call. It is
435the only reliable way to seek before using sysread() or syswrite(). Its
436return value is the new position, or the undefined value on failure.
437
438=item use VERSION
439
440If the first argument to C<use> is a number, it is treated as a version
441number instead of a module name. If the version of the Perl interpreter
442is less than VERSION, then an error message is printed and Perl exits
443immediately. Because C<use> occurs at compile time, this check happens
444immediately during the compilation process, unlike C<require VERSION>,
445which waits until runtime for the check. This is often useful if you
446need to check the current Perl version before C<use>ing library modules
447which have changed in incompatible ways from older versions of Perl.
448(We try not to do this more than we have to.)
449
450=item use Module VERSION LIST
451
452If the VERSION argument is present between Module and LIST, then the
453C<use> will call the VERSION method in class Module with the given
454version as an argument. The default VERSION method, inherited from
455the UNIVERSAL class, croaks if the given version is larger than the
456value of the variable $Module::VERSION. (Note that there is not a
457comma after VERSION!)
458
459This version-checking mechanism is similar to the one currently used
460in the Exporter module, but it is faster and can be used with modules
461that don't use the Exporter. It is the recommended method for new
462code.
463
464=item prototype(FUNCTION)
465
466Returns the prototype of a function as a string (or C<undef> if the
467function has no prototype). FUNCTION is a reference to or the name of the
468function whose prototype you want to retrieve.
469(Not actually new; just never documented before.)
470
471=item srand
472
473The default seed for C<srand>, which used to be C<time>, has been changed.
474Now it's a heady mix of difficult-to-predict system-dependent values,
475which should be sufficient for most everyday purposes.
476
477Previous to version 5.004, calling C<rand> without first calling C<srand>
478would yield the same sequence of random numbers on most or all machines.
479Now, when perl sees that you're calling C<rand> and haven't yet called
480C<srand>, it calls C<srand> with the default seed. You should still call
481C<srand> manually if your code might ever be run on a pre-5.004 system,
482of course, or if you want a seed other than the default.
483
484=item $_ as Default
485
486Functions documented in the Camel to default to $_ now in
487fact do, and all those that do are so documented in L<perlfunc>.
488
489=item C<m//gc> does not reset search position on failure
490
491The C<m//g> match iteration construct has always reset its target
492string's search position (which is visible through the C<pos> operator)
493when a match fails; as a result, the next C<m//g> match after a failure
494starts again at the beginning of the string. With Perl 5.004, this
495reset may be disabled by adding the "c" (for "continue") modifier,
496i.e. C<m//gc>. This feature, in conjunction with the C<\G> zero-width
497assertion, makes it possible to chain matches together. See L<perlop>
498and L<perlre>.
499
500=item C<m//x> ignores whitespace before ?*+{}
501
502The C<m//x> construct has always been intended to ignore all unescaped
503whitespace. However, before Perl 5.004, whitespace had the effect of
504escaping repeat modifiers like "*" or "?"; for example, C</a *b/x> was
505(mis)interpreted as C</a\*b/x>. This bug has been fixed in 5.004.
506
507=item nested C<sub{}> closures work now
508
509Prior to the 5.004 release, nested anonymous functions didn't work
510right. They do now.
511
512=item formats work right on changing lexicals
513
514Just like anonymous functions that contain lexical variables
515that change (like a lexical index variable for a C<foreach> loop),
516formats now work properly. For example, this silently failed
517before (printed only zeros), but is fine now:
518
519 my $i;
520 foreach $i ( 1 .. 10 ) {
521 write;
522 }
523 format =
524 my i is @#
525 $i
526 .
527
528However, it still fails (without a warning) if the foreach is within a
529subroutine:
530
531 my $i;
532 sub foo {
533 foreach $i ( 1 .. 10 ) {
534 write;
535 }
536 }
537 foo;
538 format =
539 my i is @#
540 $i
541 .
542
543=back
544
545=head2 New builtin methods
546
547The C<UNIVERSAL> package automatically contains the following methods that
548are inherited by all other classes:
549
13a2d996 550=over 4
6ee623d5 551
552=item isa(CLASS)
553
554C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
555
556C<isa> is also exportable and can be called as a sub with two arguments. This
557allows the ability to check what a reference points to. Example:
558
559 use UNIVERSAL qw(isa);
560
561 if(isa($ref, 'ARRAY')) {
562 ...
563 }
564
565=item can(METHOD)
566
567C<can> checks to see if its object has a method called C<METHOD>,
568if it does then a reference to the sub is returned; if it does not then
569I<undef> is returned.
570
571=item VERSION( [NEED] )
572
573C<VERSION> returns the version number of the class (package). If the
574NEED argument is given then it will check that the current version (as
575defined by the $VERSION variable in the given package) not less than
576NEED; it will die if this is not the case. This method is normally
577called as a class method. This method is called automatically by the
578C<VERSION> form of C<use>.
579
580 use A 1.2 qw(some imported subs);
581 # implies:
582 A->VERSION(1.2);
583
584=back
585
586B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
587C<isa> uses a very similar method and caching strategy. This may cause
588strange effects if the Perl code dynamically changes @ISA in any package.
589
590You may add other methods to the UNIVERSAL class via Perl or XS code.
591You do not need to C<use UNIVERSAL> in order to make these methods
592available to your program. This is necessary only if you wish to
593have C<isa> available as a plain subroutine in the current package.
594
595=head2 TIEHANDLE now supported
596
597See L<perltie> for other kinds of tie()s.
598
13a2d996 599=over 4
6ee623d5 600
601=item TIEHANDLE classname, LIST
602
603This is the constructor for the class. That means it is expected to
604return an object of some sort. The reference can be used to
605hold some internal information.
606
607 sub TIEHANDLE {
608 print "<shout>\n";
609 my $i;
610 return bless \$i, shift;
611 }
612
613=item PRINT this, LIST
614
615This method will be triggered every time the tied handle is printed to.
616Beyond its self reference it also expects the list that was passed to
617the print function.
618
619 sub PRINT {
620 $r = shift;
621 $$r++;
622 return print join( $, => map {uc} @_), $\;
623 }
624
625=item PRINTF this, LIST
626
627This method will be triggered every time the tied handle is printed to
628with the C<printf()> function.
629Beyond its self reference it also expects the format and list that was
630passed to the printf function.
631
632 sub PRINTF {
633 shift;
634 my $fmt = shift;
635 print sprintf($fmt, @_)."\n";
636 }
637
638=item READ this LIST
639
640This method will be called when the handle is read from via the C<read>
641or C<sysread> functions.
642
643 sub READ {
644 $r = shift;
645 my($buf,$len,$offset) = @_;
646 print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset";
647 }
648
649=item READLINE this
650
651This method will be called when the handle is read from. The method
652should return undef when there is no more data.
653
654 sub READLINE {
655 $r = shift;
656 return "PRINT called $$r times\n"
657 }
658
659=item GETC this
660
661This method will be called when the C<getc> function is called.
662
663 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
664
665=item DESTROY this
666
667As with the other types of ties, this method will be called when the
668tied handle is about to be destroyed. This is useful for debugging and
669possibly for cleaning up.
670
671 sub DESTROY {
672 print "</shout>\n";
673 }
674
675=back
676
677=head2 Malloc enhancements
678
679If perl is compiled with the malloc included with the perl distribution
680(that is, if C<perl -V:d_mymalloc> is 'define') then you can print
681memory statistics at runtime by running Perl thusly:
682
683 env PERL_DEBUG_MSTATS=2 perl your_script_here
684
685The value of 2 means to print statistics after compilation and on
686exit; with a value of 1, the statistics are printed only on exit.
687(If you want the statistics at an arbitrary time, you'll need to
688install the optional module Devel::Peek.)
689
690Three new compilation flags are recognized by malloc.c. (They have no
691effect if perl is compiled with system malloc().)
692
13a2d996 693=over 4
6ee623d5 694
695=item -DPERL_EMERGENCY_SBRK
696
697If this macro is defined, running out of memory need not be a fatal
698error: a memory pool can allocated by assigning to the special
699variable C<$^M>. See L<"$^M">.
700
701=item -DPACK_MALLOC
702
703Perl memory allocation is by bucket with sizes close to powers of two.
704Because of these malloc overhead may be big, especially for data of
705size exactly a power of two. If C<PACK_MALLOC> is defined, perl uses
706a slightly different algorithm for small allocations (up to 64 bytes
707long), which makes it possible to have overhead down to 1 byte for
708allocations which are powers of two (and appear quite often).
709
710Expected memory savings (with 8-byte alignment in C<alignbytes>) is
711about 20% for typical Perl usage. Expected slowdown due to additional
712malloc overhead is in fractions of a percent (hard to measure, because
713of the effect of saved memory on speed).
714
715=item -DTWO_POT_OPTIMIZE
716
717Similarly to C<PACK_MALLOC>, this macro improves allocations of data
718with size close to a power of two; but this works for big allocations
719(starting with 16K by default). Such allocations are typical for big
720hashes and special-purpose scripts, especially image processing.
721
722On recent systems, the fact that perl requires 2M from system for 1M
723allocation will not affect speed of execution, since the tail of such
724a chunk is not going to be touched (and thus will not require real
725memory). However, it may result in a premature out-of-memory error.
726So if you will be manipulating very large blocks with sizes close to
727powers of two, it would be wise to define this macro.
728
729Expected saving of memory is 0-100% (100% in applications which
730require most memory in such 2**n chunks); expected slowdown is
731negligible.
732
733=back
734
735=head2 Miscellaneous efficiency enhancements
736
737Functions that have an empty prototype and that do nothing but return
738a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
739
740Each unique hash key is only allocated once, no matter how many hashes
741have an entry with that key. So even if you have 100 copies of the
742same hash, the hash keys never have to be reallocated.
743
744=head1 Support for More Operating Systems
745
746Support for the following operating systems is new in Perl 5.004.
747
748=head2 Win32
749
750Perl 5.004 now includes support for building a "native" perl under
751Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
752and above) or the Borland C++ compiler (versions 5.02 and above).
753The resulting perl can be used under Windows 95 (if it
754is installed in the same directory locations as it got installed
755in Windows NT). This port includes support for perl extension
756building tools like L<MakeMaker> and L<h2xs>, so that many extensions
757available on the Comprehensive Perl Archive Network (CPAN) can now be
758readily built under Windows NT. See http://www.perl.com/ for more
7b8d334a 759information on CPAN and F<README.win32> in the perl distribution for more
760details on how to get started with building this port.
6ee623d5 761
762There is also support for building perl under the Cygwin32 environment.
763Cygwin32 is a set of GNU tools that make it possible to compile and run
19799a22 764many Unix programs under Windows NT by providing a mostly Unix-like
7b8d334a 765interface for compilation and execution. See F<README.cygwin32> in the
766perl distribution for more details on this port and how to obtain the
767Cygwin32 toolkit.
6ee623d5 768
769=head2 Plan 9
770
7b8d334a 771See F<README.plan9> in the perl distribution.
6ee623d5 772
773=head2 QNX
774
7b8d334a 775See F<README.qnx> in the perl distribution.
6ee623d5 776
777=head2 AmigaOS
778
7b8d334a 779See F<README.amigaos> in the perl distribution.
6ee623d5 780
781=head1 Pragmata
782
783Six new pragmatic modules exist:
784
13a2d996 785=over 4
6ee623d5 786
787=item use autouse MODULE => qw(sub1 sub2 sub3)
788
789Defers C<require MODULE> until someone calls one of the specified
790subroutines (which must be exported by MODULE). This pragma should be
791used with caution, and only when necessary.
792
793=item use blib
794
795=item use blib 'dir'
796
797Looks for MakeMaker-like I<'blib'> directory structure starting in
798I<dir> (or current directory) and working back up to five levels of
799parent directories.
800
801Intended for use on command line with B<-M> option as a way of testing
802arbitrary scripts against an uninstalled version of a package.
803
804=item use constant NAME => VALUE
805
806Provides a convenient interface for creating compile-time constants,
807See L<perlsub/"Constant Functions">.
808
809=item use locale
810
811Tells the compiler to enable (or disable) the use of POSIX locales for
812builtin operations.
813
814When C<use locale> is in effect, the current LC_CTYPE locale is used
815for regular expressions and case mapping; LC_COLLATE for string
a31a806a 816ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
6ee623d5 817(but B<not> in print). LC_NUMERIC is always used in write, since
818lexical scoping of formats is problematic at best.
819
820Each C<use locale> or C<no locale> affects statements to the end of
821the enclosing BLOCK or, if not inside a BLOCK, to the end of the
822current file. Locales can be switched and queried with
823POSIX::setlocale().
824
825See L<perllocale> for more information.
826
827=item use ops
828
829Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
830
831=item use vmsish
832
833Enable VMS-specific language features. Currently, there are three
834VMS-specific features available: 'status', which makes C<$?> and
835C<system> return genuine VMS status values instead of emulating POSIX;
836'exit', which makes C<exit> take a genuine VMS status value instead of
837assuming that C<exit 1> is an error; and 'time', which makes all times
838relative to the local time zone, in the VMS tradition.
839
840=back
841
842=head1 Modules
843
844=head2 Required Updates
845
846Though Perl 5.004 is compatible with almost all modules that work
847with Perl 5.003, there are a few exceptions:
848
849 Module Required Version for Perl 5.004
850 ------ -------------------------------
851 Filter Filter-1.12
852 LWP libwww-perl-5.08
853 Tk Tk400.202 (-w makes noise)
854
855Also, the majordomo mailing list program, version 1.94.1, doesn't work
856with Perl 5.004 (nor with perl 4), because it executes an invalid
857regular expression. This bug is fixed in majordomo version 1.94.2.
858
859=head2 Installation directories
860
861The I<installperl> script now places the Perl source files for
862extensions in the architecture-specific library directory, which is
863where the shared libraries for extensions have always been. This
864change is intended to allow administrators to keep the Perl 5.004
865library directory unchanged from a previous version, without running
866the risk of binary incompatibility between extensions' Perl source and
867shared libraries.
868
869=head2 Module information summary
870
871Brand new modules, arranged by topic rather than strictly
872alphabetically:
873
874 CGI.pm Web server interface ("Common Gateway Interface")
875 CGI/Apache.pm Support for Apache's Perl module
876 CGI/Carp.pm Log server errors with helpful context
877 CGI/Fast.pm Support for FastCGI (persistent server process)
878 CGI/Push.pm Support for server push
879 CGI/Switch.pm Simple interface for multiple server types
880
881 CPAN Interface to Comprehensive Perl Archive Network
882 CPAN::FirstTime Utility for creating CPAN configuration file
883 CPAN::Nox Runs CPAN while avoiding compiled extensions
884
885 IO.pm Top-level interface to IO::* classes
886 IO/File.pm IO::File extension Perl module
887 IO/Handle.pm IO::Handle extension Perl module
888 IO/Pipe.pm IO::Pipe extension Perl module
889 IO/Seekable.pm IO::Seekable extension Perl module
890 IO/Select.pm IO::Select extension Perl module
891 IO/Socket.pm IO::Socket extension Perl module
892
893 Opcode.pm Disable named opcodes when compiling Perl code
894
895 ExtUtils/Embed.pm Utilities for embedding Perl in C programs
896 ExtUtils/testlib.pm Fixes up @INC to use just-built extension
897
898 FindBin.pm Find path of currently executing program
899
900 Class/Struct.pm Declare struct-like datatypes as Perl classes
901 File/stat.pm By-name interface to Perl's builtin stat
902 Net/hostent.pm By-name interface to Perl's builtin gethost*
903 Net/netent.pm By-name interface to Perl's builtin getnet*
904 Net/protoent.pm By-name interface to Perl's builtin getproto*
905 Net/servent.pm By-name interface to Perl's builtin getserv*
906 Time/gmtime.pm By-name interface to Perl's builtin gmtime
907 Time/localtime.pm By-name interface to Perl's builtin localtime
908 Time/tm.pm Internal object for Time::{gm,local}time
909 User/grent.pm By-name interface to Perl's builtin getgr*
910 User/pwent.pm By-name interface to Perl's builtin getpw*
911
912 Tie/RefHash.pm Base class for tied hashes with references as keys
913
914 UNIVERSAL.pm Base class for *ALL* classes
915
916=head2 Fcntl
917
918New constants in the existing Fcntl modules are now supported,
919provided that your operating system happens to support them:
920
921 F_GETOWN F_SETOWN
922 O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
923 O_EXLOCK O_SHLOCK
924
925These constants are intended for use with the Perl operators sysopen()
926and fcntl() and the basic database modules like SDBM_File. For the
927exact meaning of these and other Fcntl constants please refer to your
928operating system's documentation for fcntl() and open().
929
930In addition, the Fcntl module now provides these constants for use
931with the Perl operator flock():
932
933 LOCK_SH LOCK_EX LOCK_NB LOCK_UN
934
935These constants are defined in all environments (because where there is
936no flock() system call, Perl emulates it). However, for historical
937reasons, these constants are not exported unless they are explicitly
938requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
939
940=head2 IO
941
19799a22 942The IO module provides a simple mechanism to load all the IO modules at one
6ee623d5 943go. Currently this includes:
944
945 IO::Handle
946 IO::Seekable
947 IO::File
948 IO::Pipe
949 IO::Socket
950
951For more information on any of these modules, please see its
952respective documentation.
953
954=head2 Math::Complex
955
956The Math::Complex module has been totally rewritten, and now supports
957more operations. These are overloaded:
958
959 + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
960
961And these functions are now exported:
962
963 pi i Re Im arg
964 log10 logn ln cbrt root
965 tan
966 csc sec cot
967 asin acos atan
968 acsc asec acot
969 sinh cosh tanh
970 csch sech coth
971 asinh acosh atanh
972 acsch asech acoth
973 cplx cplxe
974
975=head2 Math::Trig
976
977This new module provides a simpler interface to parts of Math::Complex for
978those who need trigonometric functions only for real numbers.
979
980=head2 DB_File
981
982There have been quite a few changes made to DB_File. Here are a few of
983the highlights:
984
13a2d996 985=over 4
6ee623d5 986
987=item *
988
989Fixed a handful of bugs.
990
991=item *
992
993By public demand, added support for the standard hash function exists().
994
995=item *
996
997Made it compatible with Berkeley DB 1.86.
998
999=item *
1000
1001Made negative subscripts work with RECNO interface.
1002
1003=item *
1004
1005Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
1006mode from 0640 to 0666.
1007
1008=item *
1009
1010Made DB_File automatically import the open() constants (O_RDWR,
1011O_CREAT etc.) from Fcntl, if available.
1012
1013=item *
1014
1015Updated documentation.
1016
1017=back
1018
1019Refer to the HISTORY section in DB_File.pm for a complete list of
1020changes. Everything after DB_File 1.01 has been added since 5.003.
1021
1022=head2 Net::Ping
1023
1024Major rewrite - support added for both udp echo and real icmp pings.
1025
1026=head2 Object-oriented overrides for builtin operators
1027
1028Many of the Perl builtins returning lists now have
1029object-oriented overrides. These are:
1030
1031 File::stat
1032 Net::hostent
1033 Net::netent
1034 Net::protoent
1035 Net::servent
1036 Time::gmtime
1037 Time::localtime
1038 User::grent
1039 User::pwent
1040
1041For example, you can now say
1042
1043 use File::stat;
1044 use User::pwent;
1045 $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);
1046
1047=head1 Utility Changes
1048
1049=head2 pod2html
1050
13a2d996 1051=over 4
6ee623d5 1052
1053=item Sends converted HTML to standard output
1054
1055The I<pod2html> utility included with Perl 5.004 is entirely new.
1056By default, it sends the converted HTML to its standard output,
1057instead of writing it to a file like Perl 5.003's I<pod2html> did.
1058Use the B<--outfile=FILENAME> option to write to a file.
1059
1060=back
1061
1062=head2 xsubpp
1063
13a2d996 1064=over 4
6ee623d5 1065
1066=item C<void> XSUBs now default to returning nothing
1067
1068Due to a documentation/implementation bug in previous versions of
1069Perl, XSUBs with a return type of C<void> have actually been
1070returning one value. Usually that value was the GV for the XSUB,
1071but sometimes it was some already freed or reused value, which would
1072sometimes lead to program failure.
1073
1074In Perl 5.004, if an XSUB is declared as returning C<void>, it
1075actually returns no value, i.e. an empty list (though there is a
1076backward-compatibility exception; see below). If your XSUB really
1077does return an SV, you should give it a return type of C<SV *>.
1078
1079For backward compatibility, I<xsubpp> tries to guess whether a
1080C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
1081It does so by examining the text of the XSUB: if I<xsubpp> finds
1082what looks like an assignment to C<ST(0)>, it assumes that the
1083XSUB's return type is really C<SV *>.
1084
1085=back
1086
1087=head1 C Language API Changes
1088
13a2d996 1089=over 4
6ee623d5 1090
1091=item C<gv_fetchmethod> and C<perl_call_sv>
1092
1093The C<gv_fetchmethod> function finds a method for an object, just like
1094in Perl 5.003. The GV it returns may be a method cache entry.
1095However, in Perl 5.004, method cache entries are not visible to users;
1096therefore, they can no longer be passed directly to C<perl_call_sv>.
1097Instead, you should use the C<GvCV> macro on the GV to extract its CV,
1098and pass the CV to C<perl_call_sv>.
1099
1100The most likely symptom of passing the result of C<gv_fetchmethod> to
1101C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
1102error on the I<second> call to a given method (since there is no cache
1103on the first call).
1104
1105=item C<perl_eval_pv>
1106
1107A new function handy for eval'ing strings of Perl code inside C code.
1108This function returns the value from the eval statement, which can
1109be used instead of fetching globals from the symbol table. See
1110L<perlguts>, L<perlembed> and L<perlcall> for details and examples.
1111
1112=item Extended API for manipulating hashes
1113
1114Internal handling of hash keys has changed. The old hashtable API is
1115still fully supported, and will likely remain so. The additions to the
1116API allow passing keys as C<SV*>s, so that C<tied> hashes can be given
1117real scalars as keys rather than plain strings (nontied hashes still
1118can only use strings as keys). New extensions must use the new hash
1119access functions and macros if they wish to use C<SV*> keys. These
1120additions also make it feasible to manipulate C<HE*>s (hash entries),
1121which can be more efficient. See L<perlguts> for details.
1122
1123=back
1124
1125=head1 Documentation Changes
1126
1127Many of the base and library pods were updated. These
1128new pods are included in section 1:
1129
13a2d996 1130=over 4
6ee623d5 1131
1132=item L<perldelta>
1133
1134This document.
1135
1136=item L<perlfaq>
1137
1138Frequently asked questions.
1139
1140=item L<perllocale>
1141
1142Locale support (internationalization and localization).
1143
1144=item L<perltoot>
1145
1146Tutorial on Perl OO programming.
1147
1148=item L<perlapio>
1149
1150Perl internal IO abstraction interface.
1151
1152=item L<perlmodlib>
1153
1154Perl module library and recommended practice for module creation.
1155Extracted from L<perlmod> (which is much smaller as a result).
1156
1157=item L<perldebug>
1158
1159Although not new, this has been massively updated.
1160
1161=item L<perlsec>
1162
1163Although not new, this has been massively updated.
1164
1165=back
1166
1167=head1 New Diagnostics
1168
1169Several new conditions will trigger warnings that were
1170silent before. Some only affect certain platforms.
1171The following new warnings and errors outline these.
1172These messages are classified as follows (listed in
1173increasing order of desperation):
1174
1175 (W) A warning (optional).
1176 (D) A deprecation (optional).
1177 (S) A severe warning (mandatory).
1178 (F) A fatal error (trappable).
1179 (P) An internal error you should never see (trappable).
1180 (X) A very fatal error (nontrappable).
1181 (A) An alien error message (not generated by Perl).
1182
13a2d996 1183=over 4
6ee623d5 1184
1185=item "my" variable %s masks earlier declaration in same scope
1186
1187(W) A lexical variable has been redeclared in the same scope, effectively
1188eliminating all access to the previous instance. This is almost always
1189a typographical error. Note that the earlier variable will still exist
1190until the end of the scope or until all closure referents to it are
1191destroyed.
1192
1193=item %s argument is not a HASH element or slice
1194
1195(F) The argument to delete() must be either a hash element, such as
1196
1197 $foo{$bar}
1198 $ref->[12]->{"susie"}
1199
1200or a hash slice, such as
1201
1202 @foo{$bar, $baz, $xyzzy}
1203 @{$ref->[12]}{"susie", "queue"}
1204
1205=item Allocation too large: %lx
1206
1207(X) You can't allocate more than 64K on an MS-DOS machine.
1208
1209=item Allocation too large
1210
1211(F) You can't allocate more than 2^31+"small amount" bytes.
1212
1213=item Applying %s to %s will act on scalar(%s)
1214
1215(W) The pattern match (//), substitution (s///), and transliteration (tr///)
1216operators work on scalar values. If you apply one of them to an array
1217or a hash, it will convert the array or hash to a scalar value -- the
1218length of an array, or the population info of a hash -- and then work on
1219that scalar value. This is probably not what you meant to do. See
1220L<perlfunc/grep> and L<perlfunc/map> for alternatives.
1221
1222=item Attempt to free nonexistent shared string
1223
1224(P) Perl maintains a reference counted internal table of strings to
1225optimize the storage and access of hash keys and other strings. This
1226indicates someone tried to decrement the reference count of a string
1227that can no longer be found in the table.
1228
1229=item Attempt to use reference as lvalue in substr
1230
1231(W) You supplied a reference as the first argument to substr() used
1232as an lvalue, which is pretty strange. Perhaps you forgot to
1233dereference it first. See L<perlfunc/substr>.
1234
1235=item Bareword "%s" refers to nonexistent package
1236
1237(W) You used a qualified bareword of the form C<Foo::>, but
1238the compiler saw no other uses of that namespace before that point.
1239Perhaps you need to predeclare a package?
1240
1241=item Can't redefine active sort subroutine %s
1242
1243(F) Perl optimizes the internal handling of sort subroutines and keeps
1244pointers into them. You tried to redefine one such sort subroutine when it
1245was currently active, which is not allowed. If you really want to do
1246this, you should write C<sort { &func } @x> instead of C<sort func @x>.
1247
1248=item Can't use bareword ("%s") as %s ref while "strict refs" in use
1249
1250(F) Only hard references are allowed by "strict refs". Symbolic references
1251are disallowed. See L<perlref>.
1252
1253=item Cannot resolve method `%s' overloading `%s' in package `%s'
1254
1255(P) Internal error trying to resolve overloading specified by a method
1256name (as opposed to a subroutine reference).
1257
1258=item Constant subroutine %s redefined
1259
1260(S) You redefined a subroutine which had previously been eligible for
1261inlining. See L<perlsub/"Constant Functions"> for commentary and
1262workarounds.
1263
1264=item Constant subroutine %s undefined
1265
1266(S) You undefined a subroutine which had previously been eligible for
1267inlining. See L<perlsub/"Constant Functions"> for commentary and
1268workarounds.
1269
1270=item Copy method did not return a reference
1271
1272(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
1273
1274=item Died
1275
1276(F) You passed die() an empty string (the equivalent of C<die "">) or
1277you called it with no args and both C<$@> and C<$_> were empty.
1278
1279=item Exiting pseudo-block via %s
1280
1281(W) You are exiting a rather special block construct (like a sort block or
1282subroutine) by unconventional means, such as a goto, or a loop control
1283statement. See L<perlfunc/sort>.
1284
1285=item Identifier too long
1286
1287(F) Perl limits identifiers (names for variables, functions, etc.) to
1288252 characters for simple names, somewhat more for compound names (like
1289C<$A::B>). You've exceeded Perl's limits. Future versions of Perl are
1290likely to eliminate these arbitrary limitations.
1291
1292=item Illegal character %s (carriage return)
1293
1294(F) A carriage return character was found in the input. This is an
1295error, and not a warning, because carriage return characters can break
c47ff5f1 1296multi-line strings, including here documents (e.g., C<print <<EOF;>).
6ee623d5 1297
1298=item Illegal switch in PERL5OPT: %s
1299
1300(X) The PERL5OPT environment variable may only be used to set the
1301following switches: B<-[DIMUdmw]>.
1302
1303=item Integer overflow in hex number
1304
1305(S) The literal hex number you have specified is too big for your
1306architecture. On a 32-bit architecture the largest hex literal is
13070xFFFFFFFF.
1308
1309=item Integer overflow in octal number
1310
1311(S) The literal octal number you have specified is too big for your
1312architecture. On a 32-bit architecture the largest octal literal is
1313037777777777.
1314
1315=item internal error: glob failed
1316
1317(P) Something went wrong with the external program(s) used for C<glob>
c47ff5f1 1318and C<< <*.c> >>. This may mean that your csh (C shell) is
6ee623d5 1319broken. If so, you should change all of the csh-related variables in
1320config.sh: If you have tcsh, make the variables refer to it as if it
1321were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
1322empty (except that C<d_csh> should be C<'undef'>) so that Perl will
1323think csh is missing. In either case, after editing config.sh, run
1324C<./Configure -S> and rebuild Perl.
1325
1326=item Invalid conversion in %s: "%s"
1327
1328(W) Perl does not understand the given format conversion.
1329See L<perlfunc/sprintf>.
1330
1331=item Invalid type in pack: '%s'
1332
1333(F) The given character is not a valid pack type. See L<perlfunc/pack>.
1334
1335=item Invalid type in unpack: '%s'
1336
1337(F) The given character is not a valid unpack type. See L<perlfunc/unpack>.
1338
1339=item Name "%s::%s" used only once: possible typo
1340
1341(W) Typographical errors often show up as unique variable names.
1342If you had a good reason for having a unique name, then just mention
1343it again somehow to suppress the message (the C<use vars> pragma is
1344provided for just this purpose).
1345
1346=item Null picture in formline
1347
1348(F) The first argument to formline must be a valid format picture
1349specification. It was found to be empty, which probably means you
1350supplied it an uninitialized value. See L<perlform>.
1351
1352=item Offset outside string
1353
1354(F) You tried to do a read/write/send/recv operation with an offset
1355pointing outside the buffer. This is difficult to imagine.
1356The sole exception to this is that C<sysread()>ing past the buffer
1357will extend the buffer and zero pad the new area.
1358
1359=item Out of memory!
1360
1361(X|F) The malloc() function returned 0, indicating there was insufficient
1362remaining memory (or virtual memory) to satisfy the request.
1363
1364The request was judged to be small, so the possibility to trap it
1365depends on the way Perl was compiled. By default it is not trappable.
1366However, if compiled for this, Perl may use the contents of C<$^M> as
1367an emergency pool after die()ing with this message. In this case the
1368error is trappable I<once>.
1369
1370=item Out of memory during request for %s
1371
1372(F) The malloc() function returned 0, indicating there was insufficient
1373remaining memory (or virtual memory) to satisfy the request. However,
1374the request was judged large enough (compile-time default is 64K), so
1375a possibility to shut down by trapping this error is granted.
1376
1377=item panic: frexp
1378
1379(P) The library function frexp() failed, making printf("%f") impossible.
1380
1381=item Possible attempt to put comments in qw() list
1382
1383(W) qw() lists contain items separated by whitespace; as with literal
1384strings, comment characters are not ignored, but are instead treated
1385as literal data. (You may have used different delimiters than the
7b8d334a 1386parentheses shown here; braces are also frequently used.)
6ee623d5 1387
1388You probably wrote something like this:
1389
1390 @list = qw(
1391 a # a comment
1392 b # another comment
1393 );
1394
1395when you should have written this:
1396
1397 @list = qw(
1398 a
1399 b
1400 );
1401
1402If you really want comments, build your list the
1403old-fashioned way, with quotes and commas:
1404
1405 @list = (
1406 'a', # a comment
1407 'b', # another comment
1408 );
1409
1410=item Possible attempt to separate words with commas
1411
1412(W) qw() lists contain items separated by whitespace; therefore commas
1413aren't needed to separate the items. (You may have used different
1414delimiters than the parentheses shown here; braces are also frequently
1415used.)
1416
1417You probably wrote something like this:
1418
1419 qw! a, b, c !;
1420
1421which puts literal commas into some of the list items. Write it without
1422commas if you don't want them to appear in your data:
1423
1424 qw! a b c !;
1425
1426=item Scalar value @%s{%s} better written as $%s{%s}
1427
1428(W) You've used a hash slice (indicated by @) to select a single element of
1429a hash. Generally it's better to ask for a scalar value (indicated by $).
1430The difference is that C<$foo{&bar}> always behaves like a scalar, both when
1431assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
1432like a list when you assign to it, and provides a list context to its
1433subscript, which can do weird things if you're expecting only one subscript.
1434
551e1d92 1435=item Stub found while resolving method `%s' overloading `%s' in %s
6ee623d5 1436
1437(P) Overloading resolution over @ISA tree may be broken by importing stubs.
c2611fb3 1438Stubs should never be implicitly created, but explicit calls to C<can>
6ee623d5 1439may break this.
1440
1441=item Too late for "B<-T>" option
1442
1443(X) The #! line (or local equivalent) in a Perl script contains the
1444B<-T> option, but Perl was not invoked with B<-T> in its argument
1445list. This is an error because, by the time Perl discovers a B<-T> in
1446a script, it's too late to properly taint everything from the
1447environment. So Perl gives up.
1448
1449=item untie attempted while %d inner references still exist
1450
1451(W) A copy of the object returned from C<tie> (or C<tied>) was still
1452valid when C<untie> was called.
1453
1454=item Unrecognized character %s
1455
1456(F) The Perl parser has no idea what to do with the specified character
1457in your Perl script (or eval). Perhaps you tried to run a compressed
1458script, a binary program, or a directory as a Perl program.
1459
1460=item Unsupported function fork
1461
1462(F) Your version of executable does not support forking.
1463
1464Note that under some systems, like OS/2, there may be different flavors of
1465Perl executables, some of which may support fork, some not. Try changing
1466the name you call Perl by to C<perl_>, C<perl__>, and so on.
1467
1468=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
1469
1470(D) Perl versions before 5.004 misinterpreted any type marker followed
1471by "$" and a digit. For example, "$$0" was incorrectly taken to mean
1472"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
1473
1474However, the developers of Perl 5.004 could not fix this bug completely,
1475because at least two widely-used modules depend on the old meaning of
1476"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
1477old (broken) way inside strings; but it generates this message as a
1478warning. And in Perl 5.005, this special treatment will cease.
1479
1480=item Value of %s can be "0"; test with defined()
1481
1482(W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>,
1483or C<readdir()> as a boolean value. Each of these constructs can return a
1484value of "0"; that would make the conditional expression false, which is
1485probably not what you intended. When using these constructs in conditional
1486expressions, test their values with the C<defined> operator.
1487
1488=item Variable "%s" may be unavailable
1489
1490(W) An inner (nested) I<anonymous> subroutine is inside a I<named>
1491subroutine, and outside that is another subroutine; and the anonymous
1492(innermost) subroutine is referencing a lexical variable defined in
1493the outermost subroutine. For example:
1494
1495 sub outermost { my $a; sub middle { sub { $a } } }
1496
1497If the anonymous subroutine is called or referenced (directly or
1498indirectly) from the outermost subroutine, it will share the variable
1499as you would expect. But if the anonymous subroutine is called or
1500referenced when the outermost subroutine is not active, it will see
1501the value of the shared variable as it was before and during the
1502*first* call to the outermost subroutine, which is probably not what
1503you want.
1504
1505In these circumstances, it is usually best to make the middle
1506subroutine anonymous, using the C<sub {}> syntax. Perl has specific
1507support for shared variables in nested anonymous subroutines; a named
1508subroutine in between interferes with this feature.
1509
1510=item Variable "%s" will not stay shared
1511
1512(W) An inner (nested) I<named> subroutine is referencing a lexical
1513variable defined in an outer subroutine.
1514
1515When the inner subroutine is called, it will probably see the value of
1516the outer subroutine's variable as it was before and during the
1517*first* call to the outer subroutine; in this case, after the first
1518call to the outer subroutine is complete, the inner and outer
1519subroutines will no longer share a common value for the variable. In
1520other words, the variable will no longer be shared.
1521
1522Furthermore, if the outer subroutine is anonymous and references a
1523lexical variable outside itself, then the outer and inner subroutines
1524will I<never> share the given variable.
1525
1526This problem can usually be solved by making the inner subroutine
1527anonymous, using the C<sub {}> syntax. When inner anonymous subs that
1528reference variables in outer subroutines are called or referenced,
1529they are automatically rebound to the current values of such
1530variables.
1531
1532=item Warning: something's wrong
1533
1534(W) You passed warn() an empty string (the equivalent of C<warn "">) or
1535you called it with no args and C<$_> was empty.
1536
1537=item Ill-formed logical name |%s| in prime_env_iter
1538
1539(W) A warning peculiar to VMS. A logical name was encountered when preparing
1540to iterate over %ENV which violates the syntactic rules governing logical
1541names. Since it cannot be translated normally, it is skipped, and will not
1542appear in %ENV. This may be a benign occurrence, as some software packages
1543might directly modify logical name tables and introduce nonstandard names,
1544or it may indicate that a logical name table has been corrupted.
1545
1546=item Got an error from DosAllocMem
1547
1548(P) An error peculiar to OS/2. Most probably you're using an obsolete
1549version of Perl, and this should not happen anyway.
1550
1551=item Malformed PERLLIB_PREFIX
1552
1553(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
1554
1555 prefix1;prefix2
1556
1557or
1558
1559 prefix1 prefix2
1560
1561with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix
1562of a builtin library search path, prefix2 is substituted. The error
1563may appear if components are not found, or are too long. See
1564"PERLLIB_PREFIX" in F<README.os2>.
1565
1566=item PERL_SH_DIR too long
1567
1568(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
1569C<sh>-shell in. See "PERL_SH_DIR" in F<README.os2>.
1570
1571=item Process terminated by SIG%s
1572
1573(W) This is a standard message issued by OS/2 applications, while *nix
1574applications die in silence. It is considered a feature of the OS/2
1575port. One can easily disable this by appropriate sighandlers, see
1576L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT"
1577in F<README.os2>.
1578
1579=back
1580
1581=head1 BUGS
1582
1583If you find what you think is a bug, you might check the headers of
1584recently posted articles in the comp.lang.perl.misc newsgroup.
f224927c 1585There may also be information at http://www.perl.com/perl/ , the Perl
6ee623d5 1586Home Page.
1587
1588If you believe you have an unreported bug, please run the B<perlbug>
1589program included with your release. Make sure you trim your bug down
1590to a tiny but sufficient test case. Your bug report, along with the
1591output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
1592analysed by the Perl porting team.
1593
1594=head1 SEE ALSO
1595
1596The F<Changes> file for exhaustive details on what changed.
1597
1598The F<INSTALL> file for how to build Perl. This file has been
1599significantly updated for 5.004, so even veteran users should
1600look through it.
1601
1602The F<README> file for general stuff.
1603
1604The F<Copying> file for copyright information.
1605
1606=head1 HISTORY
1607
1608Constructed by Tom Christiansen, grabbing material with permission
1609from innumerable contributors, with kibitzing by more than a few Perl
1610porters.
1611
1612Last update: Wed May 14 11:14:09 EDT 1997