perl5133delta: Test-Harness to CPAN version 3.21 (6d31366)
[perl.git] / pod / perl5004delta.pod
1 =head1 NAME
2
3 perl5004delta - what's new for perl5.004
4
5 =head1 DESCRIPTION
6
7 This document describes differences between the 5.003 release (as
8 documented in I<Programming Perl>, second edition--the Camel Book) and
9 this one.
10
11 =head1 Supported Environments
12
13 Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2,
14 QNX, AmigaOS, and Windows NT.  Perl runs on Windows 95 as well, but it
15 cannot be built there, for lack of a reasonable command interpreter.
16
17 =head1 Core Changes
18
19 Most importantly, many bugs were fixed, including several security
20 problems.  See the F<Changes> file in the distribution for details.
21
22 =head2 List assignment to %ENV works
23
24 C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS
25 where it generates a fatal error).
26
27 =head2 Change to "Can't locate Foo.pm in @INC" error
28
29 The error "Can't locate Foo.pm in @INC" now lists the contents of @INC
30 for easier debugging.
31
32 =head2 Compilation option: Binary compatibility with 5.003
33
34 There is a new Configure question that asks if you want to maintain
35 binary compatibility with Perl 5.003.  If you choose binary
36 compatibility, you do not have to recompile your extensions, but you
37 might have symbol conflicts if you embed Perl in another application,
38 just as in the 5.003 release.  By default, binary compatibility
39 is preserved at the expense of symbol table pollution.
40
41 =head2 $PERL5OPT environment variable
42
43 You may now put Perl options in the $PERL5OPT environment variable.
44 Unless Perl is running with taint checks, it will interpret this
45 variable as if its contents had appeared on a "#!perl" line at the
46 beginning of your script, except that hyphens are optional.  PERL5OPT
47 may only be used to set the following switches: B<-[DIMUdmw]>.
48
49 =head2 Limitations on B<-M>, B<-m>, and B<-T> options
50
51 The C<-M> and C<-m> options are no longer allowed on the C<#!> line of
52 a script.  If a script needs a module, it should invoke it with the
53 C<use> pragma.
54
55 The B<-T> option is also forbidden on the C<#!> line of a script,
56 unless it was present on the Perl command line.  Due to the way C<#!>
57 works, this usually means that B<-T> must be in the first argument.
58 Thus:
59
60     #!/usr/bin/perl -T -w
61
62 will probably work for an executable script invoked as C<scriptname>,
63 while:
64
65     #!/usr/bin/perl -w -T
66
67 will probably fail under the same conditions.  (Non-Unix systems will
68 probably not follow this rule.)  But C<perl scriptname> is guaranteed
69 to fail, since then there is no chance of B<-T> being found on the
70 command line before it is found on the C<#!> line.
71
72 =head2 More precise warnings
73
74 If you removed the B<-w> option from your Perl 5.003 scripts because it
75 made Perl too verbose, we recommend that you try putting it back when
76 you upgrade to Perl 5.004.  Each new perl version tends to remove some
77 undesirable warnings, while adding new warnings that may catch bugs in
78 your scripts.
79
80 =head2 Deprecated: Inherited C<AUTOLOAD> for non-methods
81
82 Before Perl 5.004, C<AUTOLOAD> functions were looked up as methods
83 (using the C<@ISA> hierarchy), even when the function to be autoloaded
84 was called as a plain function (e.g. C<Foo::bar()>), not a method
85 (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
86
87 Perl 5.005 will use method lookup only for methods' C<AUTOLOAD>s.
88 However, there is a significant base of existing code that may be using
89 the old behavior.  So, as an interim step, Perl 5.004 issues an optional
90 warning when a non-method uses an inherited C<AUTOLOAD>.
91
92 The simple rule is:  Inheritance will not work when autoloading
93 non-methods.  The simple fix for old code is:  In any module that used to
94 depend on inheriting C<AUTOLOAD> for non-methods from a base class named
95 C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup.
96
97 =head2 Previously deprecated %OVERLOAD is no longer usable
98
99 Using %OVERLOAD to define overloading was deprecated in 5.003.
100 Overloading is now defined using the overload pragma. %OVERLOAD is
101 still used internally but should not be used by Perl scripts. See
102 L<overload> for more details.
103
104 =head2 Subroutine arguments created only when they're modified
105
106 In Perl 5.004, nonexistent array and hash elements used as subroutine
107 parameters are brought into existence only if they are actually
108 assigned to (via C<@_>).
109
110 Earlier versions of Perl vary in their handling of such arguments.
111 Perl versions 5.002 and 5.003 always brought them into existence.
112 Perl versions 5.000 and 5.001 brought them into existence only if
113 they were not the first argument (which was almost certainly a bug).
114 Earlier versions of Perl never brought them into existence.
115
116 For 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
124 After this code executes in Perl 5.004, $a{b} exists but $a[2] does
125 not.  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
130 The C<$)> special variable has always (well, in Perl 5, at least)
131 reflected not only the current effective group, but also the group list
132 as returned by the C<getgroups()> C function (if there is one).
133 However, until this release, there has not been a way to call the
134 C<setgroups()> C function from Perl.
135
136 In Perl 5.004, assigning to C<$)> is exactly symmetrical with examining
137 it: The first number in its string value is used as the effective gid;
138 if there are any numbers after the first one, they are passed to the
139 C<setgroups()> C function (if there is one).
140
141 =head2 Fixed parsing of $$<digit>, &$<digit>, etc.
142
143 Perl 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
147 However, the developers of Perl 5.004 could not fix this bug completely,
148 because 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
150 old (broken) way inside strings; but it generates this message as a
151 warning.  And in Perl 5.005, this special treatment will cease.
152
153 =head2 Fixed localization of $<digit>, $&, etc.
154
155 Perl versions before 5.004 did not always properly localize the
156 regex-related special variables.  Perl 5.004 does localize them, as
157 the 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
162 The documentation for Perl 5.0 has always stated that C<$.> is I<not>
163 reset when an already-open file handle is reopened with no intervening
164 call to C<close>.  Due to a bug, perl versions 5.000 through 5.003
165 I<did> reset C<$.> under that circumstance; Perl 5.004 does not.
166
167 =head2 C<wantarray> may return undef
168
169 The C<wantarray> operator returns true if a subroutine is expected to
170 return a list, and false otherwise.  In Perl 5.004, C<wantarray> can
171 also return the undefined value if a subroutine's return value will
172 not be used at all, which allows subroutines to avoid a time-consuming
173 calculation 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
177 Perl (version 5) used to determine the value of EXPR inconsistently,
178 sometimes incorrectly using the surrounding context for the determination.
179 Now, the value of EXPR (before being parsed by eval) is always determined in
180 a scalar context.  Once parsed, it is executed as before, by providing
181 the context that the scope surrounding the eval provided.  This change
182 makes the behavior Perl4 compatible, besides fixing bugs resulting from
183 the inconsistent behavior.  This program:
184
185     @a = qw(time now is time);
186     print eval @a;
187     print '|', scalar eval @a;
188
189 used to print something like "timenowis881399109|4", but now (and in perl4)
190 prints "4|4".
191
192 =head2 Changes to tainting checks
193
194 A bug in previous versions may have failed to detect some insecure
195 conditions when taint checks are turned on.  (Taint checks are used
196 in setuid or setgid scripts, or when explicitly turned on with the
197 C<-T> invocation option.)  Although it's unlikely, this may cause a
198 previously-working script to now fail, which should be construed
199 as a blessing since that indicates a potentially-serious security
200 hole was just plugged.
201
202 The new restrictions when tainting include:
203
204 =over 4
205
206 =item No glob() or <*>
207
208 These operators may spawn the C shell (csh), which cannot be made
209 safe.  This restriction will be lifted in a future version of Perl
210 when globbing is implemented without the use of an external program.
211
212 =item No spawning if tainted $CDPATH, $ENV, $BASH_ENV
213
214 These environment variables may alter the behavior of spawned programs
215 (especially shells) in ways that subvert security.  So now they are
216 treated 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
220 Some termcap libraries do unsafe things with $TERM.  However, it would be
221 unnecessarily harsh to treat all $TERM values as unsafe, since only shell
222 metacharacters can cause trouble in $TERM.  So a tainted $TERM is
223 considered to be safe if it contains only alphanumerics, underscores,
224 dashes, and colons, and unsafe if it contains other characters (including
225 whitespace).
226
227 =back
228
229 =head2 New Opcode module and revised Safe module
230
231 A new Opcode module supports the creation, manipulation and
232 application of opcode masks.  The revised Safe module has a new API
233 and is implemented using the new Opcode module.  Please read the new
234 Opcode and Safe documentation.
235
236 =head2 Embedding improvements
237
238 In older versions of Perl it was not possible to create more than one
239 Perl interpreter instance inside a single process without leaking like a
240 sieve and/or crashing.  The bugs that caused this behavior have all been
241 fixed.  However, you still must take care when embedding Perl in a C
242 program.  See the updated perlembed manpage for tips on how to manage
243 your interpreters.
244
245 =head2 Internal change: FileHandle class based on IO::* classes
246
247 File handles are now stored internally as type IO::Handle.  The
248 FileHandle module is still supported for backwards compatibility, but
249 it is now merely a front end to the IO::* modules, specifically
250 IO::Handle, IO::Seekable, and IO::File.  We suggest, but do not
251 require, that you use the IO::* modules in new code.
252
253 In harmony with this change, C<*GLOB{FILEHANDLE}> is now just a
254 backward-compatible synonym for C<*GLOB{IO}>.
255
256 =head2 Internal change: PerlIO abstraction interface
257
258 It is now possible to build Perl with AT&T's sfio IO package
259 instead of stdio.  See L<perlapio> for more details, and
260 the F<INSTALL> file for how to use it.
261
262 =head2 New and changed syntax
263
264 =over 4
265
266 =item $coderef->(PARAMS)
267
268 A subroutine reference may now be suffixed with an arrow and a
269 (possibly empty) parameter list.  This syntax denotes a call of the
270 referenced subroutine, with the given parameters (if any).
271
272 This new syntax follows the pattern of S<C<< $hashref->{FOO} >>> and
273 S<C<< $aryref->[$foo] >>>: You may now write S<C<&$subref($foo)>> as
274 S<C<< $subref->($foo) >>>.  All these arrow terms may be chained;
275 thus, S<C<< &{$table->{FOO}}($bar) >>> may now be written
276 S<C<< $table->{FOO}->($bar) >>>.
277
278 =back
279
280 =head2 New and changed builtin constants
281
282 =over 4
283
284 =item __PACKAGE__
285
286 The current package name at compile time, or the undefined value if
287 there is no current package (due to a C<package;> directive).  Like
288 C<__FILE__> and C<__LINE__>, C<__PACKAGE__> does I<not> interpolate
289 into strings.
290
291 =back
292
293 =head2 New and changed builtin variables
294
295 =over 4
296
297 =item $^E
298
299 Extended error message on some platforms.  (Also known as
300 $EXTENDED_OS_ERROR if you C<use English>).
301
302 =item $^H
303
304 The current set of syntax checks enabled by C<use strict>.  See the
305 documentation of C<strict> for more details.  Not actually new, but
306 newly documented.
307 Because it is intended for internal use by Perl core components,
308 there is no C<use English> long name for this variable.
309
310 =item $^M
311
312 By default, running out of memory it is not trappable.  However, if
313 compiled for this, Perl may use the contents of C<$^M> as an emergency
314 pool after die()ing with this message.  Suppose that your Perl were
315 compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
316
317     $^M = 'a' x (1<<16);
318
319 would allocate a 64K buffer for use when in emergency.
320 See the F<INSTALL> file for information on how to enable this option.
321 As a disincentive to casual use of this advanced feature,
322 there is no C<use English> long name for this variable.
323
324 =back
325
326 =head2 New and changed builtin functions
327
328 =over 4
329
330 =item delete on slices
331
332 This now works.  (e.g. C<delete @ENV{'PATH', 'MANPATH'}>)
333
334 =item flock
335
336 is now supported on more platforms, prefers fcntl to lockf when
337 emulating, and always flushes before (un)locking.
338
339 =item printf and sprintf
340
341 Perl now implements these functions itself; it doesn't use the C
342 library function sprintf() any more, except for floating-point
343 numbers, and even then only known flags are allowed.  As a result, it
344 is now possible to know which conversions and flags will work, and
345 what they will do.
346
347 The 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
354 The 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
360 Also, where a number would appear in the flags, an asterisk ("*") may
361 be used instead, in which case Perl uses the next item in the
362 parameter list as the given number (that is, as the field width or
363 precision).  If a field width obtained through "*" is negative, it has
364 the same effect as the '-' flag: left-justification.
365
366 See L<perlfunc/sprintf> for a complete list of conversion and flags.
367
368 =item keys as an lvalue
369
370 As an lvalue, C<keys> allows you to increase the number of hash buckets
371 allocated for the given hash.  This can gain you a measure of efficiency if
372 you know the hash is going to get big.  (This is similar to pre-extending
373 an array by assigning a larger number to $#array.)  If you say
374
375     keys %hash = 200;
376
377 then C<%hash> will have at least 200 buckets allocated for it.  These
378 buckets 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.
380 You can't shrink the number of buckets allocated for the hash using
381 C<keys> in this way (but you needn't worry about doing this by accident,
382 as trying has no effect).
383
384 =item my() in Control Structures
385
386 You can now use my() (with or without the parentheses) in the control
387 expressions 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
404 Also, you can declare a foreach loop control variable as lexical by
405 preceding 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
412 the loop, but not beyond it.
413
414 Note that you still cannot use my() on global punctuation variables
415 such as $_ and the like.
416
417 =item pack() and unpack()
418
419 A new format 'w' represents a BER compressed integer (as defined in
420 ASN.1).  Its format is a sequence of one or more bytes, each of which
421 provides seven bits of the total value, with the most significant
422 first.  Bit eight of each byte is set, except for the last byte, in
423 which bit eight is clear.
424
425 If 'p' or 'P' are given undef as values, they now generate a NULL
426 pointer.
427
428 Both pack() and unpack() now fail when their templates contain invalid
429 types.  (Invalid types used to be ignored.)
430
431 =item sysseek()
432
433 The new sysseek() operator is a variant of seek() that sets and gets the
434 file's system read/write position, using the lseek(2) system call.  It is
435 the only reliable way to seek before using sysread() or syswrite().  Its
436 return value is the new position, or the undefined value on failure.
437
438 =item use VERSION
439
440 If the first argument to C<use> is a number, it is treated as a version
441 number instead of a module name.  If the version of the Perl interpreter
442 is less than VERSION, then an error message is printed and Perl exits
443 immediately.  Because C<use> occurs at compile time, this check happens
444 immediately during the compilation process, unlike C<require VERSION>,
445 which waits until runtime for the check.  This is often useful if you
446 need to check the current Perl version before C<use>ing library modules
447 which 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
452 If the VERSION argument is present between Module and LIST, then the
453 C<use> will call the VERSION method in class Module with the given
454 version as an argument.  The default VERSION method, inherited from
455 the UNIVERSAL class, croaks if the given version is larger than the
456 value of the variable $Module::VERSION.  (Note that there is not a
457 comma after VERSION!)
458
459 This version-checking mechanism is similar to the one currently used
460 in the Exporter module, but it is faster and can be used with modules
461 that don't use the Exporter.  It is the recommended method for new
462 code.
463
464 =item prototype(FUNCTION)
465
466 Returns the prototype of a function as a string (or C<undef> if the
467 function has no prototype).  FUNCTION is a reference to or the name of the
468 function whose prototype you want to retrieve.
469 (Not actually new; just never documented before.)
470
471 =item srand
472
473 The default seed for C<srand>, which used to be C<time>, has been changed.
474 Now it's a heady mix of difficult-to-predict system-dependent values,
475 which should be sufficient for most everyday purposes.
476
477 Previous to version 5.004, calling C<rand> without first calling C<srand>
478 would yield the same sequence of random numbers on most or all machines.
479 Now, when perl sees that you're calling C<rand> and haven't yet called
480 C<srand>, it calls C<srand> with the default seed. You should still call
481 C<srand> manually if your code might ever be run on a pre-5.004 system,
482 of course, or if you want a seed other than the default.
483
484 =item $_ as Default
485
486 Functions documented in the Camel to default to $_ now in
487 fact 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
491 The C<m//g> match iteration construct has always reset its target
492 string's search position (which is visible through the C<pos> operator)
493 when a match fails; as a result, the next C<m//g> match after a failure
494 starts again at the beginning of the string.  With Perl 5.004, this
495 reset may be disabled by adding the "c" (for "continue") modifier,
496 i.e. C<m//gc>.  This feature, in conjunction with the C<\G> zero-width
497 assertion, makes it possible to chain matches together.  See L<perlop>
498 and L<perlre>.
499
500 =item C<m//x> ignores whitespace before ?*+{}
501
502 The C<m//x> construct has always been intended to ignore all unescaped
503 whitespace.  However, before Perl 5.004, whitespace had the effect of
504 escaping 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
509 Prior to the 5.004 release, nested anonymous functions didn't work
510 right.  They do now.
511
512 =item formats work right on changing lexicals
513
514 Just like anonymous functions that contain lexical variables
515 that change (like a lexical index variable for a C<foreach> loop),
516 formats now work properly.  For example, this silently failed
517 before (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
528 However, it still fails (without a warning) if the foreach is within a
529 subroutine:
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
547 The C<UNIVERSAL> package automatically contains the following methods that
548 are inherited by all other classes:
549
550 =over 4
551
552 =item isa(CLASS)
553
554 C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
555
556 C<isa> is also exportable and can be called as a sub with two arguments. This
557 allows 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
567 C<can> checks to see if its object has a method called C<METHOD>,
568 if it does then a reference to the sub is returned; if it does not then
569 I<undef> is returned.
570
571 =item VERSION( [NEED] )
572
573 C<VERSION> returns the version number of the class (package).  If the
574 NEED argument is given then it will check that the current version (as
575 defined by the $VERSION variable in the given package) not less than
576 NEED; it will die if this is not the case.  This method is normally
577 called as a class method.  This method is called automatically by the
578 C<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
586 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
587 C<isa> uses a very similar method and caching strategy. This may cause
588 strange effects if the Perl code dynamically changes @ISA in any package.
589
590 You may add other methods to the UNIVERSAL class via Perl or XS code.
591 You do not need to C<use UNIVERSAL> in order to make these methods
592 available to your program.  This is necessary only if you wish to
593 have C<isa> available as a plain subroutine in the current package.
594
595 =head2 TIEHANDLE now supported
596
597 See L<perltie> for other kinds of tie()s.
598
599 =over 4
600
601 =item TIEHANDLE classname, LIST
602
603 This is the constructor for the class.  That means it is expected to
604 return an object of some sort. The reference can be used to
605 hold 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
615 This method will be triggered every time the tied handle is printed to.
616 Beyond its self reference it also expects the list that was passed to
617 the 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
627 This method will be triggered every time the tied handle is printed to
628 with the C<printf()> function.
629 Beyond its self reference it also expects the format and list that was
630 passed 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
640 This method will be called when the handle is read from via the C<read>
641 or 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
651 This method will be called when the handle is read from. The method
652 should 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
661 This 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
667 As with the other types of ties, this method will be called when the
668 tied handle is about to be destroyed. This is useful for debugging and
669 possibly for cleaning up.
670
671     sub DESTROY {
672         print "</shout>\n";
673     }
674
675 =back
676
677 =head2 Malloc enhancements
678
679 If 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
681 memory statistics at runtime by running Perl thusly:
682
683   env PERL_DEBUG_MSTATS=2 perl your_script_here
684
685 The value of 2 means to print statistics after compilation and on
686 exit; 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
688 install the optional module Devel::Peek.)
689
690 Three new compilation flags are recognized by malloc.c.  (They have no
691 effect if perl is compiled with system malloc().)
692
693 =over 4
694
695 =item -DPERL_EMERGENCY_SBRK
696
697 If this macro is defined, running out of memory need not be a fatal
698 error: a memory pool can allocated by assigning to the special
699 variable C<$^M>.  See L<"$^M">.
700
701 =item -DPACK_MALLOC
702
703 Perl memory allocation is by bucket with sizes close to powers of two.
704 Because of these malloc overhead may be big, especially for data of
705 size exactly a power of two.  If C<PACK_MALLOC> is defined, perl uses
706 a slightly different algorithm for small allocations (up to 64 bytes
707 long), which makes it possible to have overhead down to 1 byte for
708 allocations which are powers of two (and appear quite often).
709
710 Expected memory savings (with 8-byte alignment in C<alignbytes>) is
711 about 20% for typical Perl usage.  Expected slowdown due to additional
712 malloc overhead is in fractions of a percent (hard to measure, because
713 of the effect of saved memory on speed).
714
715 =item -DTWO_POT_OPTIMIZE
716
717 Similarly to C<PACK_MALLOC>, this macro improves allocations of data
718 with 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
720 hashes and special-purpose scripts, especially image processing.
721
722 On recent systems, the fact that perl requires 2M from system for 1M
723 allocation will not affect speed of execution, since the tail of such
724 a chunk is not going to be touched (and thus will not require real
725 memory).  However, it may result in a premature out-of-memory error.
726 So if you will be manipulating very large blocks with sizes close to
727 powers of two, it would be wise to define this macro.
728
729 Expected saving of memory is 0-100% (100% in applications which
730 require most memory in such 2**n chunks); expected slowdown is
731 negligible.
732
733 =back
734
735 =head2 Miscellaneous efficiency enhancements
736
737 Functions that have an empty prototype and that do nothing but return
738 a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>).
739
740 Each unique hash key is only allocated once, no matter how many hashes
741 have an entry with that key.  So even if you have 100 copies of the
742 same hash, the hash keys never have to be reallocated.
743
744 =head1 Support for More Operating Systems
745
746 Support for the following operating systems is new in Perl 5.004.
747
748 =head2 Win32
749
750 Perl 5.004 now includes support for building a "native" perl under
751 Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
752 and above) or the Borland C++ compiler (versions 5.02 and above).
753 The resulting perl can be used under Windows 95 (if it
754 is installed in the same directory locations as it got installed
755 in Windows NT).  This port includes support for perl extension
756 building tools like L<MakeMaker> and L<h2xs>, so that many extensions
757 available on the Comprehensive Perl Archive Network (CPAN) can now be
758 readily built under Windows NT.  See http://www.perl.com/ for more
759 information on CPAN and F<README.win32> in the perl distribution for more
760 details on how to get started with building this port.
761
762 There is also support for building perl under the Cygwin32 environment.
763 Cygwin32 is a set of GNU tools that make it possible to compile and run
764 many Unix programs under Windows NT by providing a mostly Unix-like 
765 interface for compilation and execution.  See F<README.cygwin32> in the
766 perl distribution for more details on this port and how to obtain the
767 Cygwin32 toolkit.
768
769 =head2 Plan 9
770
771 See F<README.plan9> in the perl distribution.
772
773 =head2 QNX
774
775 See F<README.qnx> in the perl distribution.
776
777 =head2 AmigaOS
778
779 See F<README.amigaos> in the perl distribution.
780
781 =head1 Pragmata
782
783 Six new pragmatic modules exist:
784
785 =over 4
786
787 =item use autouse MODULE => qw(sub1 sub2 sub3)
788
789 Defers C<require MODULE> until someone calls one of the specified
790 subroutines (which must be exported by MODULE).  This pragma should be
791 used with caution, and only when necessary.
792
793 =item use blib
794
795 =item use blib 'dir'
796
797 Looks for MakeMaker-like I<'blib'> directory structure starting in
798 I<dir> (or current directory) and working back up to five levels of
799 parent directories.
800
801 Intended for use on command line with B<-M> option as a way of testing
802 arbitrary scripts against an uninstalled version of a package.
803
804 =item use constant NAME => VALUE
805
806 Provides a convenient interface for creating compile-time constants,
807 See L<perlsub/"Constant Functions">.
808
809 =item use locale
810
811 Tells the compiler to enable (or disable) the use of POSIX locales for
812 builtin operations.
813
814 When C<use locale> is in effect, the current LC_CTYPE locale is used
815 for regular expressions and case mapping; LC_COLLATE for string
816 ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
817 (but B<not> in print).  LC_NUMERIC is always used in write, since
818 lexical scoping of formats is problematic at best.
819
820 Each C<use locale> or C<no locale> affects statements to the end of
821 the enclosing BLOCK or, if not inside a BLOCK, to the end of the
822 current file.  Locales can be switched and queried with
823 POSIX::setlocale().
824
825 See L<perllocale> for more information.
826
827 =item use ops
828
829 Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
830
831 =item use vmsish
832
833 Enable VMS-specific language features.  Currently, there are three
834 VMS-specific features available: 'status', which makes C<$?> and
835 C<system> return genuine VMS status values instead of emulating POSIX;
836 'exit', which makes C<exit> take a genuine VMS status value instead of
837 assuming that C<exit 1> is an error; and 'time', which makes all times
838 relative to the local time zone, in the VMS tradition.
839
840 =back
841
842 =head1 Modules
843
844 =head2 Required Updates
845
846 Though Perl 5.004 is compatible with almost all modules that work
847 with 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
855 Also, the majordomo mailing list program, version 1.94.1, doesn't work
856 with Perl 5.004 (nor with perl 4), because it executes an invalid
857 regular expression.  This bug is fixed in majordomo version 1.94.2.
858
859 =head2 Installation directories
860
861 The I<installperl> script now places the Perl source files for
862 extensions in the architecture-specific library directory, which is
863 where the shared libraries for extensions have always been.  This
864 change is intended to allow administrators to keep the Perl 5.004
865 library directory unchanged from a previous version, without running
866 the risk of binary incompatibility between extensions' Perl source and
867 shared libraries.
868
869 =head2 Module information summary
870
871 Brand new modules, arranged by topic rather than strictly
872 alphabetically:
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
918 New constants in the existing Fcntl modules are now supported,
919 provided 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
925 These constants are intended for use with the Perl operators sysopen()
926 and fcntl() and the basic database modules like SDBM_File.  For the
927 exact meaning of these and other Fcntl constants please refer to your
928 operating system's documentation for fcntl() and open().
929
930 In addition, the Fcntl module now provides these constants for use
931 with the Perl operator flock():
932
933         LOCK_SH LOCK_EX LOCK_NB LOCK_UN
934
935 These constants are defined in all environments (because where there is
936 no flock() system call, Perl emulates it).  However, for historical
937 reasons, these constants are not exported unless they are explicitly
938 requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
939
940 =head2 IO
941
942 The IO module provides a simple mechanism to load all the IO modules at one
943 go.  Currently this includes:
944
945      IO::Handle
946      IO::Seekable
947      IO::File
948      IO::Pipe
949      IO::Socket
950
951 For more information on any of these modules, please see its
952 respective documentation.
953
954 =head2 Math::Complex
955
956 The Math::Complex module has been totally rewritten, and now supports
957 more operations.  These are overloaded:
958
959      + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
960
961 And 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
977 This new module provides a simpler interface to parts of Math::Complex for
978 those who need trigonometric functions only for real numbers.
979
980 =head2 DB_File
981
982 There have been quite a few changes made to DB_File. Here are a few of
983 the highlights:
984
985 =over 4
986
987 =item *
988
989 Fixed a handful of bugs.
990
991 =item *
992
993 By public demand, added support for the standard hash function exists().
994
995 =item *
996
997 Made it compatible with Berkeley DB 1.86.
998
999 =item *
1000
1001 Made negative subscripts work with RECNO interface.
1002
1003 =item *
1004
1005 Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
1006 mode from 0640 to 0666.
1007
1008 =item *
1009
1010 Made DB_File automatically import the open() constants (O_RDWR,
1011 O_CREAT etc.) from Fcntl, if available.
1012
1013 =item *
1014
1015 Updated documentation.
1016
1017 =back
1018
1019 Refer to the HISTORY section in DB_File.pm for a complete list of
1020 changes. Everything after DB_File 1.01 has been added since 5.003.
1021
1022 =head2 Net::Ping
1023
1024 Major rewrite - support added for both udp echo and real icmp pings.
1025
1026 =head2 Object-oriented overrides for builtin operators
1027
1028 Many of the Perl builtins returning lists now have
1029 object-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
1041 For 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
1051 =over 4
1052
1053 =item Sends converted HTML to standard output
1054
1055 The I<pod2html> utility included with Perl 5.004 is entirely new.
1056 By default, it sends the converted HTML to its standard output,
1057 instead of writing it to a file like Perl 5.003's I<pod2html> did.
1058 Use the B<--outfile=FILENAME> option to write to a file.
1059
1060 =back
1061
1062 =head2 xsubpp
1063
1064 =over 4
1065
1066 =item C<void> XSUBs now default to returning nothing
1067
1068 Due to a documentation/implementation bug in previous versions of
1069 Perl, XSUBs with a return type of C<void> have actually been
1070 returning one value.  Usually that value was the GV for the XSUB,
1071 but sometimes it was some already freed or reused value, which would
1072 sometimes lead to program failure.
1073
1074 In Perl 5.004, if an XSUB is declared as returning C<void>, it
1075 actually returns no value, i.e. an empty list (though there is a
1076 backward-compatibility exception; see below).  If your XSUB really
1077 does return an SV, you should give it a return type of C<SV *>.
1078
1079 For backward compatibility, I<xsubpp> tries to guess whether a
1080 C<void> XSUB is really C<void> or if it wants to return an C<SV *>.
1081 It does so by examining the text of the XSUB: if I<xsubpp> finds
1082 what looks like an assignment to C<ST(0)>, it assumes that the
1083 XSUB's return type is really C<SV *>.
1084
1085 =back
1086
1087 =head1 C Language API Changes
1088
1089 =over 4
1090
1091 =item C<gv_fetchmethod> and C<perl_call_sv>
1092
1093 The C<gv_fetchmethod> function finds a method for an object, just like
1094 in Perl 5.003.  The GV it returns may be a method cache entry.
1095 However, in Perl 5.004, method cache entries are not visible to users;
1096 therefore, they can no longer be passed directly to C<perl_call_sv>.
1097 Instead, you should use the C<GvCV> macro on the GV to extract its CV,
1098 and pass the CV to C<perl_call_sv>.
1099
1100 The most likely symptom of passing the result of C<gv_fetchmethod> to
1101 C<perl_call_sv> is Perl's producing an "Undefined subroutine called"
1102 error on the I<second> call to a given method (since there is no cache
1103 on the first call).
1104
1105 =item C<perl_eval_pv>
1106
1107 A new function handy for eval'ing strings of Perl code inside C code.
1108 This function returns the value from the eval statement, which can
1109 be used instead of fetching globals from the symbol table.  See
1110 L<perlguts>, L<perlembed> and L<perlcall> for details and examples.
1111
1112 =item Extended API for manipulating hashes
1113
1114 Internal handling of hash keys has changed.  The old hashtable API is
1115 still fully supported, and will likely remain so.  The additions to the
1116 API allow passing keys as C<SV*>s, so that C<tied> hashes can be given
1117 real scalars as keys rather than plain strings (nontied hashes still
1118 can only use strings as keys).  New extensions must use the new hash
1119 access functions and macros if they wish to use C<SV*> keys.  These
1120 additions also make it feasible to manipulate C<HE*>s (hash entries),
1121 which can be more efficient.  See L<perlguts> for details.
1122
1123 =back
1124
1125 =head1 Documentation Changes
1126
1127 Many of the base and library pods were updated.  These
1128 new pods are included in section 1:
1129
1130 =over 4
1131
1132 =item L<perldelta>
1133
1134 This document.
1135
1136 =item L<perlfaq>
1137
1138 Frequently asked questions.
1139
1140 =item L<perllocale>
1141
1142 Locale support (internationalization and localization).
1143
1144 =item L<perltoot>
1145
1146 Tutorial on Perl OO programming.
1147
1148 =item L<perlapio>
1149
1150 Perl internal IO abstraction interface.
1151
1152 =item L<perlmodlib>
1153
1154 Perl module library and recommended practice for module creation.
1155 Extracted from L<perlmod> (which is much smaller as a result).
1156
1157 =item L<perldebug>
1158
1159 Although not new, this has been massively updated.
1160
1161 =item L<perlsec>
1162
1163 Although not new, this has been massively updated.
1164
1165 =back
1166
1167 =head1 New Diagnostics
1168
1169 Several new conditions will trigger warnings that were
1170 silent before.  Some only affect certain platforms.
1171 The following new warnings and errors outline these.
1172 These messages are classified as follows (listed in
1173 increasing 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
1183 =over 4
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
1188 eliminating all access to the previous instance.  This is almost always
1189 a typographical error.  Note that the earlier variable will still exist
1190 until the end of the scope or until all closure referents to it are
1191 destroyed.
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
1200 or 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///)
1216 operators work on scalar values.  If you apply one of them to an array
1217 or a hash, it will convert the array or hash to a scalar value (the
1218 length of an array or the population info of a hash) and then work on
1219 that scalar value.  This is probably not what you meant to do.  See
1220 L<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
1225 optimize the storage and access of hash keys and other strings.  This
1226 indicates someone tried to decrement the reference count of a string
1227 that 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
1232 as an lvalue, which is pretty strange.  Perhaps you forgot to
1233 dereference 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
1238 the compiler saw no other uses of that namespace before that point.
1239 Perhaps 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
1244 pointers into them.  You tried to redefine one such sort subroutine when it
1245 was currently active, which is not allowed.  If you really want to do
1246 this, 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
1251 are 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
1256 name (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
1261 inlining.  See L<perlsub/"Constant Functions"> for commentary and
1262 workarounds.
1263
1264 =item Constant subroutine %s undefined
1265
1266 (S) You undefined a subroutine which had previously been eligible for
1267 inlining.  See L<perlsub/"Constant Functions"> for commentary and
1268 workarounds.
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
1277 you 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
1282 subroutine) by unconventional means, such as a goto, or a loop control
1283 statement.  See L<perlfunc/sort>.
1284
1285 =item Identifier too long
1286
1287 (F) Perl limits identifiers (names for variables, functions, etc.) to
1288 252 characters for simple names, somewhat more for compound names (like
1289 C<$A::B>).  You've exceeded Perl's limits.  Future versions of Perl are
1290 likely 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
1295 error, and not a warning, because carriage return characters can break
1296 multi-line strings, including here documents (e.g., C<print <<EOF;>).
1297
1298 =item Illegal switch in PERL5OPT: %s
1299
1300 (X) The PERL5OPT environment variable may only be used to set the
1301 following 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
1306 architecture. On a 32-bit architecture the largest hex literal is
1307 0xFFFFFFFF.
1308
1309 =item Integer overflow in octal number
1310
1311 (S) The literal octal number you have specified is too big for your
1312 architecture. On a 32-bit architecture the largest octal literal is
1313 037777777777.
1314
1315 =item internal error: glob failed
1316
1317 (P) Something went wrong with the external program(s) used for C<glob>
1318 and C<< <*.c> >>.  This may mean that your csh (C shell) is
1319 broken.  If so, you should change all of the csh-related variables in
1320 config.sh:  If you have tcsh, make the variables refer to it as if it
1321 were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
1322 empty (except that C<d_csh> should be C<'undef'>) so that Perl will
1323 think csh is missing.  In either case, after editing config.sh, run
1324 C<./Configure -S> and rebuild Perl.
1325
1326 =item Invalid conversion in %s: "%s"
1327
1328 (W) Perl does not understand the given format conversion.
1329 See 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.
1342 If you had a good reason for having a unique name, then just mention
1343 it again somehow to suppress the message (the C<use vars> pragma is
1344 provided 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
1349 specification.  It was found to be empty, which probably means you
1350 supplied 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
1355 pointing outside the buffer.  This is difficult to imagine.
1356 The sole exception to this is that C<sysread()>ing past the buffer
1357 will 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
1362 remaining memory (or virtual memory) to satisfy the request.
1363
1364 The request was judged to be small, so the possibility to trap it
1365 depends on the way Perl was compiled.  By default it is not trappable.
1366 However, if compiled for this, Perl may use the contents of C<$^M> as
1367 an emergency pool after die()ing with this message.  In this case the
1368 error 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
1373 remaining memory (or virtual memory) to satisfy the request. However,
1374 the request was judged large enough (compile-time default is 64K), so
1375 a 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
1384 strings, comment characters are not ignored, but are instead treated
1385 as literal data.  (You may have used different delimiters than the
1386 parentheses shown here; braces are also frequently used.)
1387
1388 You probably wrote something like this:
1389
1390     @list = qw(
1391         a # a comment
1392         b # another comment
1393     );
1394
1395 when you should have written this:
1396
1397     @list = qw(
1398         a
1399         b
1400     );
1401
1402 If you really want comments, build your list the
1403 old-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
1413 aren't needed to separate the items. (You may have used different
1414 delimiters than the parentheses shown here; braces are also frequently
1415 used.)
1416
1417 You probably wrote something like this:
1418
1419     qw! a, b, c !;
1420
1421 which puts literal commas into some of the list items.  Write it without
1422 commas 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
1429 a hash.  Generally it's better to ask for a scalar value (indicated by $).
1430 The difference is that C<$foo{&bar}> always behaves like a scalar, both when
1431 assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
1432 like a list when you assign to it, and provides a list context to its
1433 subscript, which can do weird things if you're expecting only one subscript.
1434
1435 =item Stub found while resolving method `%s' overloading `%s' in %s
1436
1437 (P) Overloading resolution over @ISA tree may be broken by importing stubs.
1438 Stubs should never be implicitly created, but explicit calls to C<can>
1439 may 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
1444 B<-T> option, but Perl was not invoked with B<-T> in its argument
1445 list.  This is an error because, by the time Perl discovers a B<-T> in
1446 a script, it's too late to properly taint everything from the
1447 environment.  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
1452 valid 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
1457 in your Perl script (or eval).  Perhaps you tried to run a compressed
1458 script, 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
1464 Note that under some systems, like OS/2, there may be different flavors of
1465 Perl executables, some of which may support fork, some not. Try changing
1466 the 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
1471 by "$" 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
1474 However, the developers of Perl 5.004 could not fix this bug completely,
1475 because 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
1477 old (broken) way inside strings; but it generates this message as a
1478 warning.  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()>,
1483 or C<readdir()> as a boolean value.  Each of these constructs can return a
1484 value of "0"; that would make the conditional expression false, which is
1485 probably not what you intended.  When using these constructs in conditional
1486 expressions, 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>
1491 subroutine, and outside that is another subroutine; and the anonymous
1492 (innermost) subroutine is referencing a lexical variable defined in
1493 the outermost subroutine.  For example:
1494
1495    sub outermost { my $a; sub middle { sub { $a } } }
1496
1497 If the anonymous subroutine is called or referenced (directly or
1498 indirectly) from the outermost subroutine, it will share the variable
1499 as you would expect.  But if the anonymous subroutine is called or
1500 referenced when the outermost subroutine is not active, it will see
1501 the value of the shared variable as it was before and during the
1502 *first* call to the outermost subroutine, which is probably not what
1503 you want.
1504
1505 In these circumstances, it is usually best to make the middle
1506 subroutine anonymous, using the C<sub {}> syntax.  Perl has specific
1507 support for shared variables in nested anonymous subroutines; a named
1508 subroutine 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
1513 variable defined in an outer subroutine.
1514
1515 When the inner subroutine is called, it will probably see the value of
1516 the outer subroutine's variable as it was before and during the
1517 *first* call to the outer subroutine; in this case, after the first
1518 call to the outer subroutine is complete, the inner and outer
1519 subroutines will no longer share a common value for the variable.  In
1520 other words, the variable will no longer be shared.
1521
1522 Furthermore, if the outer subroutine is anonymous and references a
1523 lexical variable outside itself, then the outer and inner subroutines
1524 will I<never> share the given variable.
1525
1526 This problem can usually be solved by making the inner subroutine
1527 anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
1528 reference variables in outer subroutines are called or referenced,
1529 they are automatically rebound to the current values of such
1530 variables.
1531
1532 =item Warning: something's wrong
1533
1534 (W) You passed warn() an empty string (the equivalent of C<warn "">) or
1535 you 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
1540 to iterate over %ENV which violates the syntactic rules governing logical
1541 names.  Since it cannot be translated normally, it is skipped, and will not
1542 appear in %ENV.  This may be a benign occurrence, as some software packages
1543 might directly modify logical name tables and introduce nonstandard names,
1544 or 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
1549 version 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
1557 or
1558
1559     prefix1 prefix2
1560
1561 with nonempty prefix1 and prefix2.  If C<prefix1> is indeed a prefix
1562 of a builtin library search path, prefix2 is substituted.  The error
1563 may 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
1569 C<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
1574 applications die in silence.  It is considered a feature of the OS/2
1575 port.  One can easily disable this by appropriate sighandlers, see
1576 L<perlipc/"Signals">.  See also "Process terminated by SIGTERM/SIGINT"
1577 in F<README.os2>.
1578
1579 =back
1580
1581 =head1 BUGS
1582
1583 If you find what you think is a bug, you might check the headers of
1584 recently posted articles in the comp.lang.perl.misc newsgroup.
1585 There may also be information at http://www.perl.com/perl/ , the Perl
1586 Home Page.
1587
1588 If you believe you have an unreported bug, please run the B<perlbug>
1589 program included with your release.  Make sure you trim your bug down
1590 to a tiny but sufficient test case.  Your bug report, along with the
1591 output of C<perl -V>, will be sent off to <F<perlbug@perl.com>> to be
1592 analysed by the Perl porting team.
1593
1594 =head1 SEE ALSO
1595
1596 The F<Changes> file for exhaustive details on what changed.
1597
1598 The F<INSTALL> file for how to build Perl.  This file has been
1599 significantly updated for 5.004, so even veteran users should
1600 look through it.
1601
1602 The F<README> file for general stuff.
1603
1604 The F<Copying> file for copyright information.
1605
1606 =head1 HISTORY
1607
1608 Constructed by Tom Christiansen, grabbing material with permission
1609 from innumerable contributors, with kibitzing by more than a few Perl
1610 porters.
1611
1612 Last update: Wed May 14 11:14:09 EDT 1997