Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perl5004delta.1

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