Debian Codegraph @

upstream/debian-unstable/man1/perl5004delta.1

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