| 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 |