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