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