Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlvar - Perl predefined variables |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | =head2 Predefined Names |
8 | |
5a964f20 |
9 | The following names have special meaning to Perl. Most |
14218588 |
10 | punctuation names have reasonable mnemonics, or analogs in the |
11 | shells. Nevertheless, if you wish to use long variable names, |
12 | you need only say |
a0d0e21e |
13 | |
14 | use English; |
15 | |
a1ce9542 |
16 | at the top of your program. This aliases all the short names to the long |
17 | names in the current package. Some even have medium names, generally |
18 | borrowed from B<awk>. In general, it's best to use the |
a0d0e21e |
19 | |
a1ce9542 |
20 | use English '-no_match_vars'; |
21 | |
22 | invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids |
23 | a certain performance hit with the use of regular expressions. See |
24 | L<English>. |
25 | |
26 | Variables that depend on the currently selected filehandle may be set by |
27 | calling an appropriate object method on the IO::Handle object, although |
28 | this is less efficient than using the regular built-in variables. (Summary |
29 | lines below for this contain the word HANDLE.) First you must say |
a0d0e21e |
30 | |
19799a22 |
31 | use IO::Handle; |
a0d0e21e |
32 | |
33 | after which you may use either |
34 | |
35 | method HANDLE EXPR |
36 | |
5a964f20 |
37 | or more safely, |
a0d0e21e |
38 | |
39 | HANDLE->method(EXPR) |
40 | |
14218588 |
41 | Each method returns the old value of the IO::Handle attribute. |
a1ce9542 |
42 | The methods each take an optional EXPR, which, if supplied, specifies the |
19799a22 |
43 | new value for the IO::Handle attribute in question. If not supplied, |
14218588 |
44 | most methods do nothing to the current value--except for |
a0d0e21e |
45 | autoflush(), which will assume a 1 for you, just to be different. |
a1ce9542 |
46 | |
14218588 |
47 | Because loading in the IO::Handle class is an expensive operation, you should |
19799a22 |
48 | learn how to use the regular built-in variables. |
a0d0e21e |
49 | |
748a9306 |
50 | A few of these variables are considered "read-only". This means that if |
51 | you try to assign to this variable, either directly or indirectly through |
52 | a reference, you'll raise a run-time exception. |
a0d0e21e |
53 | |
22d0716c |
54 | You should be very careful when modifying the default values of most |
55 | special variables described in this document. In most cases you want |
56 | to localize these variables before changing them, since if you don't, |
57 | the change may affect other modules which rely on the default values |
58 | of the special variables that you have changed. This is one of the |
59 | correct ways to read the whole file at once: |
60 | |
b0169937 |
61 | open my $fh, "<", "foo" or die $!; |
22d0716c |
62 | local $/; # enable localized slurp mode |
63 | my $content = <$fh>; |
64 | close $fh; |
65 | |
66 | But the following code is quite bad: |
67 | |
b0169937 |
68 | open my $fh, "<", "foo" or die $!; |
22d0716c |
69 | undef $/; # enable slurp mode |
70 | my $content = <$fh>; |
71 | close $fh; |
72 | |
73 | since some other module, may want to read data from some file in the |
74 | default "line mode", so if the code we have just presented has been |
75 | executed, the global value of C<$/> is now changed for any other code |
76 | running inside the same Perl interpreter. |
77 | |
78 | Usually when a variable is localized you want to make sure that this |
79 | change affects the shortest scope possible. So unless you are already |
80 | inside some short C<{}> block, you should create one yourself. For |
81 | example: |
82 | |
83 | my $content = ''; |
b0169937 |
84 | open my $fh, "<", "foo" or die $!; |
22d0716c |
85 | { |
86 | local $/; |
87 | $content = <$fh>; |
88 | } |
89 | close $fh; |
90 | |
91 | Here is an example of how your own code can go broken: |
92 | |
93 | for (1..5){ |
94 | nasty_break(); |
95 | print "$_ "; |
96 | } |
97 | sub nasty_break { |
98 | $_ = 5; |
99 | # do something with $_ |
100 | } |
101 | |
102 | You probably expect this code to print: |
103 | |
104 | 1 2 3 4 5 |
105 | |
106 | but instead you get: |
107 | |
108 | 5 5 5 5 5 |
109 | |
110 | Why? Because nasty_break() modifies C<$_> without localizing it |
111 | first. The fix is to add local(): |
112 | |
113 | local $_ = 5; |
114 | |
115 | It's easy to notice the problem in such a short example, but in more |
116 | complicated code you are looking for trouble if you don't localize |
117 | changes to the special variables. |
118 | |
fb73857a |
119 | The following list is ordered by scalar variables first, then the |
87275199 |
120 | arrays, then the hashes. |
fb73857a |
121 | |
a0d0e21e |
122 | =over 8 |
123 | |
124 | =item $ARG |
125 | |
126 | =item $_ |
a054c801 |
127 | X<$_> X<$ARG> |
a0d0e21e |
128 | |
129 | The default input and pattern-searching space. The following pairs are |
130 | equivalent: |
131 | |
19799a22 |
132 | while (<>) {...} # equivalent only in while! |
54310121 |
133 | while (defined($_ = <>)) {...} |
a0d0e21e |
134 | |
135 | /^Subject:/ |
136 | $_ =~ /^Subject:/ |
137 | |
138 | tr/a-z/A-Z/ |
139 | $_ =~ tr/a-z/A-Z/ |
140 | |
19799a22 |
141 | chomp |
142 | chomp($_) |
a0d0e21e |
143 | |
54310121 |
144 | Here are the places where Perl will assume $_ even if you |
cb1a09d0 |
145 | don't use it: |
146 | |
147 | =over 3 |
148 | |
149 | =item * |
150 | |
db1511c8 |
151 | The following functions: |
152 | |
b0169937 |
153 | abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob, |
154 | hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, |
155 | quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), |
156 | rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst, |
157 | unlink, unpack. |
cb1a09d0 |
158 | |
159 | =item * |
160 | |
db1511c8 |
161 | All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. |
162 | See L<perlfunc/-X> |
163 | |
cb1a09d0 |
164 | |
165 | =item * |
166 | |
b0169937 |
167 | The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>) |
168 | when used without an C<=~> operator. |
cb1a09d0 |
169 | |
54310121 |
170 | =item * |
cb1a09d0 |
171 | |
172 | The default iterator variable in a C<foreach> loop if no other |
173 | variable is supplied. |
174 | |
54310121 |
175 | =item * |
cb1a09d0 |
176 | |
177 | The implicit iterator variable in the grep() and map() functions. |
178 | |
54310121 |
179 | =item * |
cb1a09d0 |
180 | |
db1511c8 |
181 | The implicit variable of given(). |
182 | |
183 | =item * |
184 | |
c47ff5f1 |
185 | The default place to put an input record when a C<< <FH> >> |
cb1a09d0 |
186 | operation's result is tested by itself as the sole criterion of a C<while> |
14218588 |
187 | test. Outside a C<while> test, this will not happen. |
cb1a09d0 |
188 | |
189 | =back |
190 | |
59f00321 |
191 | As C<$_> is a global variable, this may lead in some cases to unwanted |
192 | side-effects. As of perl 5.9.1, you can now use a lexical version of |
193 | C<$_> by declaring it in a file or in a block with C<my>. Moreover, |
4fd88bf8 |
194 | declaring C<our $_> restores the global C<$_> in the current scope. |
59f00321 |
195 | |
a0d0e21e |
196 | (Mnemonic: underline is understood in certain operations.) |
197 | |
6e2995f4 |
198 | =back |
199 | |
200 | =over 8 |
201 | |
a1db74c9 |
202 | =item $a |
203 | |
204 | =item $b |
a054c801 |
205 | X<$a> X<$b> |
a1db74c9 |
206 | |
207 | Special package variables when using sort(), see L<perlfunc/sort>. |
208 | Because of this specialness $a and $b don't need to be declared |
f83912f2 |
209 | (using use vars, or our()) even when using the C<strict 'vars'> pragma. |
210 | Don't lexicalize them with C<my $a> or C<my $b> if you want to be |
211 | able to use them in the sort() comparison block or function. |
a1db74c9 |
212 | |
213 | =back |
214 | |
215 | =over 8 |
216 | |
c47ff5f1 |
217 | =item $<I<digits>> |
a054c801 |
218 | X<$1> X<$2> X<$3> |
a0d0e21e |
219 | |
19799a22 |
220 | Contains the subpattern from the corresponding set of capturing |
221 | parentheses from the last pattern match, not counting patterns |
222 | matched in nested blocks that have been exited already. (Mnemonic: |
223 | like \digits.) These variables are all read-only and dynamically |
224 | scoped to the current BLOCK. |
a0d0e21e |
225 | |
226 | =item $MATCH |
227 | |
228 | =item $& |
a054c801 |
229 | X<$&> X<$MATCH> |
a0d0e21e |
230 | |
231 | The string matched by the last successful pattern match (not counting |
232 | any matches hidden within a BLOCK or eval() enclosed by the current |
19799a22 |
233 | BLOCK). (Mnemonic: like & in some editors.) This variable is read-only |
234 | and dynamically scoped to the current BLOCK. |
a0d0e21e |
235 | |
19ddd453 |
236 | The use of this variable anywhere in a program imposes a considerable |
667e1aea |
237 | performance penalty on all regular expression matches. See L</BUGS>. |
19ddd453 |
238 | |
a054c801 |
239 | See L</@-> for a replacement. |
240 | |
cde0cee5 |
241 | =item ${^MATCH} |
242 | X<${^MATCH}> |
243 | |
6210e03f |
244 | This is similar to C<$&> (C<$MATCH>) except that it does not incur the |
cde0cee5 |
245 | performance penalty associated with that variable, and is only guaranteed |
246 | to return a defined value when the pattern was compiled or executed with |
87e95b7f |
247 | the C</p> modifier. |
cde0cee5 |
248 | |
a0d0e21e |
249 | =item $PREMATCH |
250 | |
251 | =item $` |
a054c801 |
252 | X<$`> X<$PREMATCH> |
a0d0e21e |
253 | |
254 | The string preceding whatever was matched by the last successful |
255 | pattern match (not counting any matches hidden within a BLOCK or eval |
a8f8344d |
256 | enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted |
a0d0e21e |
257 | string.) This variable is read-only. |
258 | |
19ddd453 |
259 | The use of this variable anywhere in a program imposes a considerable |
667e1aea |
260 | performance penalty on all regular expression matches. See L</BUGS>. |
19ddd453 |
261 | |
a054c801 |
262 | See L</@-> for a replacement. |
263 | |
cde0cee5 |
264 | =item ${^PREMATCH} |
265 | X<${^PREMATCH}> |
266 | |
267 | This is similar to C<$`> ($PREMATCH) except that it does not incur the |
268 | performance penalty associated with that variable, and is only guaranteed |
269 | to return a defined value when the pattern was compiled or executed with |
87e95b7f |
270 | the C</p> modifier. |
cde0cee5 |
271 | |
a0d0e21e |
272 | =item $POSTMATCH |
273 | |
274 | =item $' |
a054c801 |
275 | X<$'> X<$POSTMATCH> |
a0d0e21e |
276 | |
277 | The string following whatever was matched by the last successful |
278 | pattern match (not counting any matches hidden within a BLOCK or eval() |
a8f8344d |
279 | enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted |
a0d0e21e |
280 | string.) Example: |
281 | |
22d0716c |
282 | local $_ = 'abcdefghi'; |
a0d0e21e |
283 | /def/; |
284 | print "$`:$&:$'\n"; # prints abc:def:ghi |
285 | |
19799a22 |
286 | This variable is read-only and dynamically scoped to the current BLOCK. |
a0d0e21e |
287 | |
19ddd453 |
288 | The use of this variable anywhere in a program imposes a considerable |
667e1aea |
289 | performance penalty on all regular expression matches. See L</BUGS>. |
19ddd453 |
290 | |
a054c801 |
291 | See L</@-> for a replacement. |
292 | |
cde0cee5 |
293 | =item ${^POSTMATCH} |
294 | X<${^POSTMATCH}> |
295 | |
296 | This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the |
297 | performance penalty associated with that variable, and is only guaranteed |
298 | to return a defined value when the pattern was compiled or executed with |
87e95b7f |
299 | the C</p> modifier. |
cde0cee5 |
300 | |
a0d0e21e |
301 | =item $LAST_PAREN_MATCH |
302 | |
303 | =item $+ |
a054c801 |
304 | X<$+> X<$LAST_PAREN_MATCH> |
a0d0e21e |
305 | |
a01268b5 |
306 | The text matched by the last bracket of the last successful search pattern. |
307 | This is useful if you don't know which one of a set of alternative patterns |
308 | matched. For example: |
a0d0e21e |
309 | |
310 | /Version: (.*)|Revision: (.*)/ && ($rev = $+); |
311 | |
312 | (Mnemonic: be positive and forward looking.) |
19799a22 |
313 | This variable is read-only and dynamically scoped to the current BLOCK. |
a0d0e21e |
314 | |
daaddde1 |
315 | =item $LAST_SUBMATCH_RESULT |
316 | |
a01268b5 |
317 | =item $^N |
a054c801 |
318 | X<$^N> |
a01268b5 |
319 | |
320 | The text matched by the used group most-recently closed (i.e. the group |
321 | with the rightmost closing parenthesis) of the last successful search |
ad83b128 |
322 | pattern. (Mnemonic: the (possibly) Nested parenthesis that most |
323 | recently closed.) |
324 | |
210b36aa |
325 | This is primarily used inside C<(?{...})> blocks for examining text |
a01268b5 |
326 | recently matched. For example, to effectively capture text to a variable |
327 | (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with |
328 | |
329 | (?:(...)(?{ $var = $^N })) |
330 | |
331 | By setting and then using C<$var> in this way relieves you from having to |
332 | worry about exactly which numbered set of parentheses they are. |
333 | |
334 | This variable is dynamically scoped to the current BLOCK. |
335 | |
fe307981 |
336 | =item @LAST_MATCH_END |
337 | |
6cef1e77 |
338 | =item @+ |
a054c801 |
339 | X<@+> X<@LAST_MATCH_END> |
6cef1e77 |
340 | |
4ba05bdc |
341 | This array holds the offsets of the ends of the last successful |
342 | submatches in the currently active dynamic scope. C<$+[0]> is |
343 | the offset into the string of the end of the entire match. This |
344 | is the same value as what the C<pos> function returns when called |
345 | on the variable that was matched against. The I<n>th element |
346 | of this array holds the offset of the I<n>th submatch, so |
347 | C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset |
348 | past where $2 ends, and so on. You can use C<$#+> to determine |
349 | how many subgroups were in the last successful match. See the |
350 | examples given for the C<@-> variable. |
6cef1e77 |
351 | |
43239f90 |
352 | =item %LAST_PAREN_MATCH |
8e08999f |
353 | |
81714fb9 |
354 | =item %+ |
355 | X<%+> |
356 | |
357 | Similar to C<@+>, the C<%+> hash allows access to the named capture |
358 | buffers, should they exist, in the last successful match in the |
359 | currently active dynamic scope. |
360 | |
3195cf34 |
361 | For example, C<$+{foo}> is equivalent to C<$1> after the following match: |
81714fb9 |
362 | |
3195cf34 |
363 | 'foo' =~ /(?<foo>foo)/; |
81714fb9 |
364 | |
3195cf34 |
365 | The keys of the C<%+> hash list only the names of buffers that have |
366 | captured (and that are thus associated to defined values). |
44a2ac75 |
367 | |
3195cf34 |
368 | The underlying behaviour of C<%+> is provided by the |
80305961 |
369 | L<Tie::Hash::NamedCapture> module. |
3195cf34 |
370 | |
371 | B<Note:> C<%-> and C<%+> are tied views into a common internal hash |
44a2ac75 |
372 | associated with the last successful regular expression. Therefore mixing |
373 | iterative access to them via C<each> may have unpredictable results. |
3195cf34 |
374 | Likewise, if the last successful match changes, then the results may be |
44a2ac75 |
375 | surprising. |
376 | |
fcc7d916 |
377 | =item HANDLE->input_line_number(EXPR) |
a0d0e21e |
378 | |
379 | =item $INPUT_LINE_NUMBER |
380 | |
381 | =item $NR |
382 | |
383 | =item $. |
a054c801 |
384 | X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number> |
a0d0e21e |
385 | |
81714fb9 |
386 | Current line number for the last filehandle accessed. |
fcc7d916 |
387 | |
388 | Each filehandle in Perl counts the number of lines that have been read |
389 | from it. (Depending on the value of C<$/>, Perl's idea of what |
390 | constitutes a line may not match yours.) When a line is read from a |
391 | filehandle (via readline() or C<< <> >>), or when tell() or seek() is |
392 | called on it, C<$.> becomes an alias to the line counter for that |
393 | filehandle. |
394 | |
395 | You can adjust the counter by assigning to C<$.>, but this will not |
396 | actually move the seek pointer. I<Localizing C<$.> will not localize |
397 | the filehandle's line count>. Instead, it will localize perl's notion |
398 | of which filehandle C<$.> is currently aliased to. |
399 | |
400 | C<$.> is reset when the filehandle is closed, but B<not> when an open |
401 | filehandle is reopened without an intervening close(). For more |
e48df184 |
402 | details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does |
fcc7d916 |
403 | an explicit close, line numbers increase across ARGV files (but see |
404 | examples in L<perlfunc/eof>). |
405 | |
406 | You can also use C<< HANDLE->input_line_number(EXPR) >> to access the |
407 | line counter for a given filehandle without having to worry about |
408 | which handle you last accessed. |
409 | |
410 | (Mnemonic: many programs use "." to mean the current line number.) |
411 | |
412 | =item IO::Handle->input_record_separator(EXPR) |
a0d0e21e |
413 | |
414 | =item $INPUT_RECORD_SEPARATOR |
415 | |
416 | =item $RS |
417 | |
418 | =item $/ |
a054c801 |
419 | X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> |
a0d0e21e |
420 | |
14218588 |
421 | The input record separator, newline by default. This |
422 | influences Perl's idea of what a "line" is. Works like B<awk>'s RS |
19799a22 |
423 | variable, including treating empty lines as a terminator if set to |
14218588 |
424 | the null string. (An empty line cannot contain any spaces |
425 | or tabs.) You may set it to a multi-character string to match a |
19799a22 |
426 | multi-character terminator, or to C<undef> to read through the end |
427 | of file. Setting it to C<"\n\n"> means something slightly |
428 | different than setting to C<"">, if the file contains consecutive |
429 | empty lines. Setting to C<""> will treat two or more consecutive |
430 | empty lines as a single empty line. Setting to C<"\n\n"> will |
431 | blindly assume that the next input character belongs to the next |
14218588 |
432 | paragraph, even if it's a newline. (Mnemonic: / delimits |
19799a22 |
433 | line boundaries when quoting poetry.) |
a0d0e21e |
434 | |
22d0716c |
435 | local $/; # enable "slurp" mode |
436 | local $_ = <FH>; # whole file now here |
a0d0e21e |
437 | s/\n[ \t]+/ /g; |
438 | |
19799a22 |
439 | Remember: the value of C<$/> is a string, not a regex. B<awk> has to be |
440 | better for something. :-) |
68dc0745 |
441 | |
19799a22 |
442 | Setting C<$/> to a reference to an integer, scalar containing an integer, or |
443 | scalar that's convertible to an integer will attempt to read records |
5b2b9c68 |
444 | instead of lines, with the maximum record size being the referenced |
19799a22 |
445 | integer. So this: |
5b2b9c68 |
446 | |
22d0716c |
447 | local $/ = \32768; # or \"32768", or \$var_containing_32768 |
b0169937 |
448 | open my $fh, "<", $myfile or die $!; |
22d0716c |
449 | local $_ = <$fh>; |
5b2b9c68 |
450 | |
19799a22 |
451 | will read a record of no more than 32768 bytes from FILE. If you're |
452 | not reading from a record-oriented file (or your OS doesn't have |
453 | record-oriented files), then you'll likely get a full chunk of data |
454 | with every read. If a record is larger than the record size you've |
acbd132f |
455 | set, you'll get the record back in pieces. Trying to set the record |
456 | size to zero or less will cause reading in the (rest of the) whole file. |
5b2b9c68 |
457 | |
19799a22 |
458 | On VMS, record reads are done with the equivalent of C<sysread>, |
459 | so it's best not to mix record and non-record reads on the same |
460 | file. (This is unlikely to be a problem, because any file you'd |
83763826 |
461 | want to read in record mode is probably unusable in line mode.) |
14218588 |
462 | Non-VMS systems do normal I/O, so it's safe to mix record and |
19799a22 |
463 | non-record reads of a file. |
5b2b9c68 |
464 | |
14218588 |
465 | See also L<perlport/"Newlines">. Also see C<$.>. |
883faa13 |
466 | |
fcc7d916 |
467 | =item HANDLE->autoflush(EXPR) |
a0d0e21e |
468 | |
469 | =item $OUTPUT_AUTOFLUSH |
470 | |
471 | =item $| |
a054c801 |
472 | X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH> |
a0d0e21e |
473 | |
19799a22 |
474 | If set to nonzero, forces a flush right away and after every write |
475 | or print on the currently selected output channel. Default is 0 |
14218588 |
476 | (regardless of whether the channel is really buffered by the |
19799a22 |
477 | system or not; C<$|> tells you only whether you've asked Perl |
478 | explicitly to flush after each write). STDOUT will |
479 | typically be line buffered if output is to the terminal and block |
480 | buffered otherwise. Setting this variable is useful primarily when |
481 | you are outputting to a pipe or socket, such as when you are running |
482 | a Perl program under B<rsh> and want to see the output as it's |
483 | happening. This has no effect on input buffering. See L<perlfunc/getc> |
b0169937 |
484 | for that. See L<perldoc/select> on how to select the output channel. |
485 | See also L<IO::Handle>. (Mnemonic: when you want your pipes to be piping hot.) |
a0d0e21e |
486 | |
46550894 |
487 | =item IO::Handle->output_field_separator EXPR |
a0d0e21e |
488 | |
489 | =item $OUTPUT_FIELD_SEPARATOR |
490 | |
491 | =item $OFS |
492 | |
493 | =item $, |
a054c801 |
494 | X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> |
a0d0e21e |
495 | |
d6584ed8 |
496 | The output field separator for the print operator. If defined, this |
497 | value is printed between each of print's arguments. Default is C<undef>. |
498 | (Mnemonic: what is printed when there is a "," in your print statement.) |
a0d0e21e |
499 | |
46550894 |
500 | =item IO::Handle->output_record_separator EXPR |
a0d0e21e |
501 | |
502 | =item $OUTPUT_RECORD_SEPARATOR |
503 | |
504 | =item $ORS |
505 | |
506 | =item $\ |
a054c801 |
507 | X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> |
a0d0e21e |
508 | |
d6584ed8 |
509 | The output record separator for the print operator. If defined, this |
510 | value is printed after the last of print's arguments. Default is C<undef>. |
511 | (Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. |
512 | Also, it's just like C<$/>, but it's what you get "back" from Perl.) |
a0d0e21e |
513 | |
514 | =item $LIST_SEPARATOR |
515 | |
516 | =item $" |
a054c801 |
517 | X<$"> X<$LIST_SEPARATOR> |
a0d0e21e |
518 | |
19799a22 |
519 | This is like C<$,> except that it applies to array and slice values |
520 | interpolated into a double-quoted string (or similar interpreted |
521 | string). Default is a space. (Mnemonic: obvious, I think.) |
a0d0e21e |
522 | |
523 | =item $SUBSCRIPT_SEPARATOR |
524 | |
525 | =item $SUBSEP |
526 | |
527 | =item $; |
a054c801 |
528 | X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR> |
a0d0e21e |
529 | |
54310121 |
530 | The subscript separator for multidimensional array emulation. If you |
a0d0e21e |
531 | refer to a hash element as |
532 | |
533 | $foo{$a,$b,$c} |
534 | |
535 | it really means |
536 | |
537 | $foo{join($;, $a, $b, $c)} |
538 | |
539 | But don't put |
540 | |
541 | @foo{$a,$b,$c} # a slice--note the @ |
542 | |
543 | which means |
544 | |
545 | ($foo{$a},$foo{$b},$foo{$c}) |
546 | |
19799a22 |
547 | Default is "\034", the same as SUBSEP in B<awk>. If your |
548 | keys contain binary data there might not be any safe value for C<$;>. |
a0d0e21e |
549 | (Mnemonic: comma (the syntactic subscript separator) is a |
19799a22 |
550 | semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already |
a0d0e21e |
551 | taken for something more important.) |
552 | |
19799a22 |
553 | Consider using "real" multidimensional arrays as described |
554 | in L<perllol>. |
a0d0e21e |
555 | |
fcc7d916 |
556 | =item HANDLE->format_page_number(EXPR) |
a0d0e21e |
557 | |
558 | =item $FORMAT_PAGE_NUMBER |
559 | |
560 | =item $% |
a054c801 |
561 | X<$%> X<$FORMAT_PAGE_NUMBER> |
a0d0e21e |
562 | |
563 | The current page number of the currently selected output channel. |
19799a22 |
564 | Used with formats. |
a0d0e21e |
565 | (Mnemonic: % is page number in B<nroff>.) |
566 | |
fcc7d916 |
567 | =item HANDLE->format_lines_per_page(EXPR) |
a0d0e21e |
568 | |
569 | =item $FORMAT_LINES_PER_PAGE |
570 | |
571 | =item $= |
a054c801 |
572 | X<$=> X<$FORMAT_LINES_PER_PAGE> |
a0d0e21e |
573 | |
574 | The current page length (printable lines) of the currently selected |
19799a22 |
575 | output channel. Default is 60. |
576 | Used with formats. |
577 | (Mnemonic: = has horizontal lines.) |
a0d0e21e |
578 | |
fcc7d916 |
579 | =item HANDLE->format_lines_left(EXPR) |
a0d0e21e |
580 | |
581 | =item $FORMAT_LINES_LEFT |
582 | |
583 | =item $- |
a054c801 |
584 | X<$-> X<$FORMAT_LINES_LEFT> |
a0d0e21e |
585 | |
586 | The number of lines left on the page of the currently selected output |
19799a22 |
587 | channel. |
588 | Used with formats. |
589 | (Mnemonic: lines_on_page - lines_printed.) |
a0d0e21e |
590 | |
fe307981 |
591 | =item @LAST_MATCH_START |
592 | |
6cef1e77 |
593 | =item @- |
a054c801 |
594 | X<@-> X<@LAST_MATCH_START> |
6cef1e77 |
595 | |
19799a22 |
596 | $-[0] is the offset of the start of the last successful match. |
6cef1e77 |
597 | C<$-[>I<n>C<]> is the offset of the start of the substring matched by |
8f580fb8 |
598 | I<n>-th subpattern, or undef if the subpattern did not match. |
6cef1e77 |
599 | |
600 | Thus after a match against $_, $& coincides with C<substr $_, $-[0], |
5060ef7b |
601 | $+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], |
602 | $+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with |
603 | C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last |
14218588 |
604 | matched subgroup in the last successful match. Contrast with |
605 | C<$#+>, the number of subgroups in the regular expression. Compare |
19799a22 |
606 | with C<@+>. |
6cef1e77 |
607 | |
4ba05bdc |
608 | This array holds the offsets of the beginnings of the last |
609 | successful submatches in the currently active dynamic scope. |
610 | C<$-[0]> is the offset into the string of the beginning of the |
611 | entire match. The I<n>th element of this array holds the offset |
0926d669 |
612 | of the I<n>th submatch, so C<$-[1]> is the offset where $1 |
613 | begins, C<$-[2]> the offset where $2 begins, and so on. |
4ba05bdc |
614 | |
615 | After a match against some variable $var: |
616 | |
617 | =over 5 |
618 | |
4375e838 |
619 | =item C<$`> is the same as C<substr($var, 0, $-[0])> |
4ba05bdc |
620 | |
4375e838 |
621 | =item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> |
4ba05bdc |
622 | |
4375e838 |
623 | =item C<$'> is the same as C<substr($var, $+[0])> |
4ba05bdc |
624 | |
625 | =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> |
626 | |
627 | =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> |
628 | |
80dc6883 |
629 | =item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> |
4ba05bdc |
630 | |
631 | =back |
632 | |
44a2ac75 |
633 | =item %- |
634 | X<%-> |
635 | |
3195cf34 |
636 | Similar to C<%+>, this variable allows access to the named capture buffers |
637 | in the last successful match in the currently active dynamic scope. To |
638 | each capture buffer name found in the regular expression, it associates a |
639 | reference to an array containing the list of values captured by all |
640 | buffers with that name (should there be several of them), in the order |
641 | where they appear. |
642 | |
643 | Here's an example: |
44a2ac75 |
644 | |
3195cf34 |
645 | if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { |
646 | foreach my $bufname (sort keys %-) { |
647 | my $ary = $-{$bufname}; |
44a2ac75 |
648 | foreach my $idx (0..$#$ary) { |
3195cf34 |
649 | print "\$-{$bufname}[$idx] : ", |
44a2ac75 |
650 | (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), |
651 | "\n"; |
652 | } |
653 | } |
654 | } |
655 | |
656 | would print out: |
657 | |
658 | $-{A}[0] : '1' |
659 | $-{A}[1] : '3' |
660 | $-{B}[0] : '2' |
661 | $-{B}[1] : '4' |
662 | |
3195cf34 |
663 | The keys of the C<%-> hash correspond to all buffer names found in |
664 | the regular expression. |
665 | |
666 | The behaviour of C<%-> is implemented via the |
80305961 |
667 | L<Tie::Hash::NamedCapture> module. |
44a2ac75 |
668 | |
3195cf34 |
669 | B<Note:> C<%-> and C<%+> are tied views into a common internal hash |
44a2ac75 |
670 | associated with the last successful regular expression. Therefore mixing |
671 | iterative access to them via C<each> may have unpredictable results. |
3195cf34 |
672 | Likewise, if the last successful match changes, then the results may be |
44a2ac75 |
673 | surprising. |
674 | |
fcc7d916 |
675 | =item HANDLE->format_name(EXPR) |
a0d0e21e |
676 | |
677 | =item $FORMAT_NAME |
678 | |
679 | =item $~ |
a054c801 |
680 | X<$~> X<$FORMAT_NAME> |
a0d0e21e |
681 | |
682 | The name of the current report format for the currently selected output |
14218588 |
683 | channel. Default is the name of the filehandle. (Mnemonic: brother to |
19799a22 |
684 | C<$^>.) |
a0d0e21e |
685 | |
fcc7d916 |
686 | =item HANDLE->format_top_name(EXPR) |
a0d0e21e |
687 | |
688 | =item $FORMAT_TOP_NAME |
689 | |
690 | =item $^ |
a054c801 |
691 | X<$^> X<$FORMAT_TOP_NAME> |
a0d0e21e |
692 | |
693 | The name of the current top-of-page format for the currently selected |
14218588 |
694 | output channel. Default is the name of the filehandle with _TOP |
a0d0e21e |
695 | appended. (Mnemonic: points to top of page.) |
696 | |
46550894 |
697 | =item IO::Handle->format_line_break_characters EXPR |
a0d0e21e |
698 | |
699 | =item $FORMAT_LINE_BREAK_CHARACTERS |
700 | |
701 | =item $: |
a054c801 |
702 | X<$:> X<FORMAT_LINE_BREAK_CHARACTERS> |
a0d0e21e |
703 | |
704 | The current set of characters after which a string may be broken to |
54310121 |
705 | fill continuation fields (starting with ^) in a format. Default is |
a0d0e21e |
706 | S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in |
707 | poetry is a part of a line.) |
708 | |
46550894 |
709 | =item IO::Handle->format_formfeed EXPR |
a0d0e21e |
710 | |
711 | =item $FORMAT_FORMFEED |
712 | |
713 | =item $^L |
a054c801 |
714 | X<$^L> X<$FORMAT_FORMFEED> |
a0d0e21e |
715 | |
14218588 |
716 | What formats output as a form feed. Default is \f. |
a0d0e21e |
717 | |
718 | =item $ACCUMULATOR |
719 | |
720 | =item $^A |
a054c801 |
721 | X<$^A> X<$ACCUMULATOR> |
a0d0e21e |
722 | |
723 | The current value of the write() accumulator for format() lines. A format |
19799a22 |
724 | contains formline() calls that put their result into C<$^A>. After |
a0d0e21e |
725 | calling its format, write() prints out the contents of C<$^A> and empties. |
14218588 |
726 | So you never really see the contents of C<$^A> unless you call |
a0d0e21e |
727 | formline() yourself and then look at it. See L<perlform> and |
728 | L<perlfunc/formline()>. |
729 | |
730 | =item $CHILD_ERROR |
731 | |
732 | =item $? |
a054c801 |
733 | X<$?> X<$CHILD_ERROR> |
a0d0e21e |
734 | |
54310121 |
735 | The status returned by the last pipe close, backtick (C<``>) command, |
19799a22 |
736 | successful call to wait() or waitpid(), or from the system() |
737 | operator. This is just the 16-bit status word returned by the |
e5218da5 |
738 | traditional Unix wait() system call (or else is made up to look like it). Thus, the |
c47ff5f1 |
739 | exit value of the subprocess is really (C<<< $? >> 8 >>>), and |
19799a22 |
740 | C<$? & 127> gives which signal, if any, the process died from, and |
741 | C<$? & 128> reports whether there was a core dump. (Mnemonic: |
742 | similar to B<sh> and B<ksh>.) |
a0d0e21e |
743 | |
7b8d334a |
744 | Additionally, if the C<h_errno> variable is supported in C, its value |
14218588 |
745 | is returned via $? if any C<gethost*()> function fails. |
7b8d334a |
746 | |
19799a22 |
747 | If you have installed a signal handler for C<SIGCHLD>, the |
aa689395 |
748 | value of C<$?> will usually be wrong outside that handler. |
749 | |
a8f8344d |
750 | Inside an C<END> subroutine C<$?> contains the value that is going to be |
751 | given to C<exit()>. You can modify C<$?> in an C<END> subroutine to |
19799a22 |
752 | change the exit status of your program. For example: |
753 | |
754 | END { |
755 | $? = 1 if $? == 255; # die would make it 255 |
756 | } |
a8f8344d |
757 | |
aa689395 |
758 | Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the |
ff0cee69 |
759 | actual VMS exit status, instead of the default emulation of POSIX |
9bc98430 |
760 | status; see L<perlvms/$?> for details. |
f86702cc |
761 | |
55602bd2 |
762 | Also see L<Error Indicators>. |
763 | |
e5218da5 |
764 | =item ${^CHILD_ERROR_NATIVE} |
a054c801 |
765 | X<$^CHILD_ERROR_NATIVE> |
e5218da5 |
766 | |
767 | The native status returned by the last pipe close, backtick (C<``>) |
768 | command, successful call to wait() or waitpid(), or from the system() |
769 | operator. On POSIX-like systems this value can be decoded with the |
770 | WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG |
771 | and WIFCONTINUED functions provided by the L<POSIX> module. |
772 | |
773 | Under VMS this reflects the actual VMS exit status; i.e. it is the same |
774 | as $? when the pragma C<use vmsish 'status'> is in effect. |
775 | |
0a378802 |
776 | =item ${^ENCODING} |
a054c801 |
777 | X<$^ENCODING> |
0a378802 |
778 | |
740bd165 |
779 | The I<object reference> to the Encode object that is used to convert |
780 | the source code to Unicode. Thanks to this variable your perl script |
781 | does not have to be written in UTF-8. Default is I<undef>. The direct |
749e08de |
782 | manipulation of this variable is highly discouraged. |
0a378802 |
783 | |
a0d0e21e |
784 | =item $OS_ERROR |
785 | |
786 | =item $ERRNO |
787 | |
788 | =item $! |
a054c801 |
789 | X<$!> X<$ERRNO> X<$OS_ERROR> |
a0d0e21e |
790 | |
19799a22 |
791 | If used numerically, yields the current value of the C C<errno> |
6ab308ee |
792 | variable, or in other words, if a system or library call fails, it |
793 | sets this variable. This means that the value of C<$!> is meaningful |
794 | only I<immediately> after a B<failure>: |
795 | |
b0169937 |
796 | if (open my $fh, "<", $filename) { |
6ab308ee |
797 | # Here $! is meaningless. |
798 | ... |
799 | } else { |
800 | # ONLY here is $! meaningful. |
801 | ... |
802 | # Already here $! might be meaningless. |
803 | } |
804 | # Since here we might have either success or failure, |
805 | # here $! is meaningless. |
806 | |
807 | In the above I<meaningless> stands for anything: zero, non-zero, |
808 | C<undef>. A successful system or library call does B<not> set |
809 | the variable to zero. |
810 | |
271df126 |
811 | If used as a string, yields the corresponding system error string. |
19799a22 |
812 | You can assign a number to C<$!> to set I<errno> if, for instance, |
813 | you want C<"$!"> to return the string for error I<n>, or you want |
814 | to set the exit value for the die() operator. (Mnemonic: What just |
815 | went bang?) |
a0d0e21e |
816 | |
55602bd2 |
817 | Also see L<Error Indicators>. |
818 | |
daaddde1 |
819 | =item %OS_ERROR |
820 | |
821 | =item %ERRNO |
822 | |
4c5cef9b |
823 | =item %! |
a054c801 |
824 | X<%!> |
4c5cef9b |
825 | |
826 | Each element of C<%!> has a true value only if C<$!> is set to that |
827 | value. For example, C<$!{ENOENT}> is true if and only if the current |
3be065a1 |
828 | value of C<$!> is C<ENOENT>; that is, if the most recent error was |
829 | "No such file or directory" (or its moral equivalent: not all operating |
830 | systems give that exact error, and certainly not all languages). |
831 | To check if a particular key is meaningful on your system, use |
832 | C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>. |
833 | See L<Errno> for more information, and also see above for the |
834 | validity of C<$!>. |
4c5cef9b |
835 | |
5c055ba3 |
836 | =item $EXTENDED_OS_ERROR |
837 | |
838 | =item $^E |
a054c801 |
839 | X<$^E> X<$EXTENDED_OS_ERROR> |
5c055ba3 |
840 | |
22fae026 |
841 | Error information specific to the current operating system. At |
842 | the moment, this differs from C<$!> under only VMS, OS/2, and Win32 |
843 | (and for MacPerl). On all other platforms, C<$^E> is always just |
844 | the same as C<$!>. |
845 | |
846 | Under VMS, C<$^E> provides the VMS status value from the last |
847 | system error. This is more specific information about the last |
848 | system error than that provided by C<$!>. This is particularly |
d516a115 |
849 | important when C<$!> is set to B<EVMSERR>. |
22fae026 |
850 | |
1c1c7f20 |
851 | Under OS/2, C<$^E> is set to the error code of the last call to |
852 | OS/2 API either via CRT, or directly from perl. |
22fae026 |
853 | |
854 | Under Win32, C<$^E> always returns the last error information |
855 | reported by the Win32 call C<GetLastError()> which describes |
856 | the last error from within the Win32 API. Most Win32-specific |
19799a22 |
857 | code will report errors via C<$^E>. ANSI C and Unix-like calls |
22fae026 |
858 | set C<errno> and so most portable Perl code will report errors |
859 | via C<$!>. |
860 | |
861 | Caveats mentioned in the description of C<$!> generally apply to |
862 | C<$^E>, also. (Mnemonic: Extra error explanation.) |
5c055ba3 |
863 | |
55602bd2 |
864 | Also see L<Error Indicators>. |
865 | |
a0d0e21e |
866 | =item $EVAL_ERROR |
867 | |
868 | =item $@ |
a054c801 |
869 | X<$@> X<$EVAL_ERROR> |
a0d0e21e |
870 | |
4a280ebe |
871 | The Perl syntax error message from the last eval() operator. |
872 | If $@ is the null string, the last eval() parsed and executed |
873 | correctly (although the operations you invoked may have failed in the |
874 | normal fashion). (Mnemonic: Where was the syntax error "at"?) |
a0d0e21e |
875 | |
19799a22 |
876 | Warning messages are not collected in this variable. You can, |
a8f8344d |
877 | however, set up a routine to process warnings by setting C<$SIG{__WARN__}> |
54310121 |
878 | as described below. |
748a9306 |
879 | |
55602bd2 |
880 | Also see L<Error Indicators>. |
881 | |
a0d0e21e |
882 | =item $PROCESS_ID |
883 | |
884 | =item $PID |
885 | |
886 | =item $$ |
a054c801 |
887 | X<$$> X<$PID> X<$PROCESS_ID> |
a0d0e21e |
888 | |
19799a22 |
889 | The process number of the Perl running this script. You should |
890 | consider this variable read-only, although it will be altered |
891 | across fork() calls. (Mnemonic: same as shells.) |
a0d0e21e |
892 | |
4d76a344 |
893 | Note for Linux users: on Linux, the C functions C<getpid()> and |
894 | C<getppid()> return different values from different threads. In order to |
895 | be portable, this behavior is not reflected by C<$$>, whose value remains |
896 | consistent across threads. If you want to call the underlying C<getpid()>, |
e3256f86 |
897 | you may use the CPAN module C<Linux::Pid>. |
4d76a344 |
898 | |
a0d0e21e |
899 | =item $REAL_USER_ID |
900 | |
901 | =item $UID |
902 | |
903 | =item $< |
a054c801 |
904 | X<< $< >> X<$UID> X<$REAL_USER_ID> |
a0d0e21e |
905 | |
19799a22 |
906 | The real uid of this process. (Mnemonic: it's the uid you came I<from>, |
a043a685 |
907 | if you're running setuid.) You can change both the real uid and |
a537debe |
908 | the effective uid at the same time by using POSIX::setuid(). Since |
909 | changes to $< require a system call, check $! after a change attempt to |
910 | detect any possible errors. |
a0d0e21e |
911 | |
912 | =item $EFFECTIVE_USER_ID |
913 | |
914 | =item $EUID |
915 | |
916 | =item $> |
a054c801 |
917 | X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> |
a0d0e21e |
918 | |
919 | The effective uid of this process. Example: |
920 | |
921 | $< = $>; # set real to effective uid |
922 | ($<,$>) = ($>,$<); # swap real and effective uid |
923 | |
a043a685 |
924 | You can change both the effective uid and the real uid at the same |
a537debe |
925 | time by using POSIX::setuid(). Changes to $> require a check to $! |
926 | to detect any possible errors after an attempted change. |
a043a685 |
927 | |
19799a22 |
928 | (Mnemonic: it's the uid you went I<to>, if you're running setuid.) |
c47ff5f1 |
929 | C<< $< >> and C<< $> >> can be swapped only on machines |
8cc95fdb |
930 | supporting setreuid(). |
a0d0e21e |
931 | |
932 | =item $REAL_GROUP_ID |
933 | |
934 | =item $GID |
935 | |
936 | =item $( |
a054c801 |
937 | X<$(> X<$GID> X<$REAL_GROUP_ID> |
a0d0e21e |
938 | |
939 | The real gid of this process. If you are on a machine that supports |
940 | membership in multiple groups simultaneously, gives a space separated |
941 | list of groups you are in. The first number is the one returned by |
942 | getgid(), and the subsequent ones by getgroups(), one of which may be |
8cc95fdb |
943 | the same as the first number. |
944 | |
19799a22 |
945 | However, a value assigned to C<$(> must be a single number used to |
946 | set the real gid. So the value given by C<$(> should I<not> be assigned |
2bc0d022 |
947 | back to C<$(> without being forced numeric, such as by adding zero. Note |
948 | that this is different to the effective gid (C<$)>) which does take a |
949 | list. |
8cc95fdb |
950 | |
a043a685 |
951 | You can change both the real gid and the effective gid at the same |
a537debe |
952 | time by using POSIX::setgid(). Changes to $( require a check to $! |
953 | to detect any possible errors after an attempted change. |
a043a685 |
954 | |
19799a22 |
955 | (Mnemonic: parentheses are used to I<group> things. The real gid is the |
956 | group you I<left>, if you're running setgid.) |
a0d0e21e |
957 | |
958 | =item $EFFECTIVE_GROUP_ID |
959 | |
960 | =item $EGID |
961 | |
962 | =item $) |
a054c801 |
963 | X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> |
a0d0e21e |
964 | |
965 | The effective gid of this process. If you are on a machine that |
966 | supports membership in multiple groups simultaneously, gives a space |
967 | separated list of groups you are in. The first number is the one |
968 | returned by getegid(), and the subsequent ones by getgroups(), one of |
8cc95fdb |
969 | which may be the same as the first number. |
970 | |
19799a22 |
971 | Similarly, a value assigned to C<$)> must also be a space-separated |
14218588 |
972 | list of numbers. The first number sets the effective gid, and |
8cc95fdb |
973 | the rest (if any) are passed to setgroups(). To get the effect of an |
974 | empty list for setgroups(), just repeat the new effective gid; that is, |
975 | to force an effective gid of 5 and an effectively empty setgroups() |
976 | list, say C< $) = "5 5" >. |
977 | |
a043a685 |
978 | You can change both the effective gid and the real gid at the same |
979 | time by using POSIX::setgid() (use only a single numeric argument). |
a537debe |
980 | Changes to $) require a check to $! to detect any possible errors |
981 | after an attempted change. |
a043a685 |
982 | |
19799a22 |
983 | (Mnemonic: parentheses are used to I<group> things. The effective gid |
984 | is the group that's I<right> for you, if you're running setgid.) |
a0d0e21e |
985 | |
c47ff5f1 |
986 | C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on |
19799a22 |
987 | machines that support the corresponding I<set[re][ug]id()> routine. C<$(> |
988 | and C<$)> can be swapped only on machines supporting setregid(). |
a0d0e21e |
989 | |
990 | =item $PROGRAM_NAME |
991 | |
992 | =item $0 |
a054c801 |
993 | X<$0> X<$PROGRAM_NAME> |
a0d0e21e |
994 | |
80bca1b4 |
995 | Contains the name of the program being executed. |
996 | |
997 | On some (read: not all) operating systems assigning to C<$0> modifies |
998 | the argument area that the C<ps> program sees. On some platforms you |
999 | may have to use special C<ps> options or a different C<ps> to see the |
1000 | changes. Modifying the $0 is more useful as a way of indicating the |
1001 | current program state than it is for hiding the program you're |
1002 | running. (Mnemonic: same as B<sh> and B<ksh>.) |
f9cbb277 |
1003 | |
cf525c36 |
1004 | Note that there are platform specific limitations on the maximum |
f9cbb277 |
1005 | length of C<$0>. In the most extreme case it may be limited to the |
1006 | space occupied by the original C<$0>. |
a0d0e21e |
1007 | |
80bca1b4 |
1008 | In some platforms there may be arbitrary amount of padding, for |
1009 | example space characters, after the modified name as shown by C<ps>. |
dda345b7 |
1010 | In some platforms this padding may extend all the way to the original |
c80e2480 |
1011 | length of the argument area, no matter what you do (this is the case |
1012 | for example with Linux 2.2). |
80bca1b4 |
1013 | |
4bc88a62 |
1014 | Note for BSD users: setting C<$0> does not completely remove "perl" |
6a4647a3 |
1015 | from the ps(1) output. For example, setting C<$0> to C<"foobar"> may |
1016 | result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix |
1017 | and the " (perl)" suffix are shown depends on your exact BSD variant |
1018 | and version). This is an operating system feature, Perl cannot help it. |
4bc88a62 |
1019 | |
e2975953 |
1020 | In multithreaded scripts Perl coordinates the threads so that any |
1021 | thread may modify its copy of the C<$0> and the change becomes visible |
cf525c36 |
1022 | to ps(1) (assuming the operating system plays along). Note that |
80bca1b4 |
1023 | the view of C<$0> the other threads have will not change since they |
1024 | have their own copies of it. |
e2975953 |
1025 | |
52c447a8 |
1026 | If the program has been given to perl via the switches C<-e> or C<-E>, |
1027 | C<$0> will contain the string C<"-e">. |
1028 | |
a0d0e21e |
1029 | =item $[ |
a054c801 |
1030 | X<$[> |
a0d0e21e |
1031 | |
1032 | The index of the first element in an array, and of the first character |
19799a22 |
1033 | in a substring. Default is 0, but you could theoretically set it |
1034 | to 1 to make Perl behave more like B<awk> (or Fortran) when |
1035 | subscripting and when evaluating the index() and substr() functions. |
1036 | (Mnemonic: [ begins subscripts.) |
a0d0e21e |
1037 | |
19799a22 |
1038 | As of release 5 of Perl, assignment to C<$[> is treated as a compiler |
1039 | directive, and cannot influence the behavior of any other file. |
55b67815 |
1040 | (That's why you can only assign compile-time constants to it.) Its |
1041 | use is deprecated, and will trigger a warning (if the deprecation |
1042 | L<warnings> category is enabled. You did C<use warnings>, right?) |
a0d0e21e |
1043 | |
f83ed198 |
1044 | Note that, unlike other compile-time directives (such as L<strict>), |
af7a0647 |
1045 | assignment to C<$[> can be seen from outer lexical scopes in the same file. |
1046 | However, you can use local() on it to strictly bind its value to a |
f83ed198 |
1047 | lexical block. |
1048 | |
a0d0e21e |
1049 | =item $] |
a054c801 |
1050 | X<$]> |
a0d0e21e |
1051 | |
54310121 |
1052 | The version + patchlevel / 1000 of the Perl interpreter. This variable |
1053 | can be used to determine whether the Perl interpreter executing a |
1054 | script is in the right range of versions. (Mnemonic: Is this version |
1055 | of perl in the right bracket?) Example: |
a0d0e21e |
1056 | |
1057 | warn "No checksumming!\n" if $] < 3.019; |
1058 | |
54310121 |
1059 | See also the documentation of C<use VERSION> and C<require VERSION> |
19799a22 |
1060 | for a convenient way to fail if the running Perl interpreter is too old. |
a0d0e21e |
1061 | |
0c8d858b |
1062 | The floating point representation can sometimes lead to inaccurate |
1063 | numeric comparisons. See C<$^V> for a more modern representation of |
1064 | the Perl version that allows accurate string comparisons. |
16070b82 |
1065 | |
305aace0 |
1066 | =item $COMPILING |
1067 | |
1068 | =item $^C |
a054c801 |
1069 | X<$^C> X<$COMPILING> |
305aace0 |
1070 | |
19799a22 |
1071 | The current value of the flag associated with the B<-c> switch. |
1072 | Mainly of use with B<-MO=...> to allow code to alter its behavior |
1073 | when being compiled, such as for example to AUTOLOAD at compile |
59f521f4 |
1074 | time rather than normal, deferred loading. Setting |
19799a22 |
1075 | C<$^C = 1> is similar to calling C<B::minus_c>. |
305aace0 |
1076 | |
a0d0e21e |
1077 | =item $DEBUGGING |
1078 | |
1079 | =item $^D |
a054c801 |
1080 | X<$^D> X<$DEBUGGING> |
a0d0e21e |
1081 | |
1082 | The current value of the debugging flags. (Mnemonic: value of B<-D> |
b4ab917c |
1083 | switch.) May be read or set. Like its command-line equivalent, you can use |
1084 | numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">. |
a0d0e21e |
1085 | |
a3621e74 |
1086 | =item ${^RE_DEBUG_FLAGS} |
1087 | |
1088 | The current value of the regex debugging flags. Set to 0 for no debug output |
1089 | even when the re 'debug' module is loaded. See L<re> for details. |
1090 | |
0111c4fd |
1091 | =item ${^RE_TRIE_MAXBUF} |
a3621e74 |
1092 | |
1093 | Controls how certain regex optimisations are applied and how much memory they |
1094 | utilize. This value by default is 65536 which corresponds to a 512kB temporary |
1095 | cache. Set this to a higher value to trade memory for speed when matching |
1096 | large alternations. Set it to a lower value if you want the optimisations to |
1097 | be as conservative of memory as possible but still occur, and set it to a |
1098 | negative value to prevent the optimisation and conserve the most memory. |
1099 | Under normal situations this variable should be of no interest to you. |
1100 | |
a0d0e21e |
1101 | =item $SYSTEM_FD_MAX |
1102 | |
1103 | =item $^F |
a054c801 |
1104 | X<$^F> X<$SYSTEM_FD_MAX> |
a0d0e21e |
1105 | |
1106 | The maximum system file descriptor, ordinarily 2. System file |
1107 | descriptors are passed to exec()ed processes, while higher file |
1108 | descriptors are not. Also, during an open(), system file descriptors are |
1109 | preserved even if the open() fails. (Ordinary file descriptors are |
19799a22 |
1110 | closed before the open() is attempted.) The close-on-exec |
a0d0e21e |
1111 | status of a file descriptor will be decided according to the value of |
8d2a6795 |
1112 | C<$^F> when the corresponding file, pipe, or socket was opened, not the |
1113 | time of the exec(). |
a0d0e21e |
1114 | |
6e2995f4 |
1115 | =item $^H |
1116 | |
0462a1ab |
1117 | WARNING: This variable is strictly for internal use only. Its availability, |
1118 | behavior, and contents are subject to change without notice. |
1119 | |
1120 | This variable contains compile-time hints for the Perl interpreter. At the |
1121 | end of compilation of a BLOCK the value of this variable is restored to the |
1122 | value when the interpreter started to compile the BLOCK. |
1123 | |
1124 | When perl begins to parse any block construct that provides a lexical scope |
1125 | (e.g., eval body, required file, subroutine body, loop body, or conditional |
1126 | block), the existing value of $^H is saved, but its value is left unchanged. |
1127 | When the compilation of the block is completed, it regains the saved value. |
1128 | Between the points where its value is saved and restored, code that |
1129 | executes within BEGIN blocks is free to change the value of $^H. |
1130 | |
1131 | This behavior provides the semantic of lexical scoping, and is used in, |
1132 | for instance, the C<use strict> pragma. |
1133 | |
1134 | The contents should be an integer; different bits of it are used for |
1135 | different pragmatic flags. Here's an example: |
1136 | |
1137 | sub add_100 { $^H |= 0x100 } |
1138 | |
1139 | sub foo { |
1140 | BEGIN { add_100() } |
1141 | bar->baz($boon); |
1142 | } |
1143 | |
1144 | Consider what happens during execution of the BEGIN block. At this point |
1145 | the BEGIN block has already been compiled, but the body of foo() is still |
1146 | being compiled. The new value of $^H will therefore be visible only while |
1147 | the body of foo() is being compiled. |
1148 | |
1149 | Substitution of the above BEGIN block with: |
1150 | |
1151 | BEGIN { require strict; strict->import('vars') } |
1152 | |
1153 | demonstrates how C<use strict 'vars'> is implemented. Here's a conditional |
1154 | version of the same lexical pragma: |
1155 | |
1156 | BEGIN { require strict; strict->import('vars') if $condition } |
1157 | |
1158 | =item %^H |
1159 | |
0462a1ab |
1160 | The %^H hash provides the same scoping semantic as $^H. This makes it |
46e5f5f4 |
1161 | useful for implementation of lexically scoped pragmas. See L<perlpragma>. |
6e2995f4 |
1162 | |
a0d0e21e |
1163 | =item $INPLACE_EDIT |
1164 | |
1165 | =item $^I |
a054c801 |
1166 | X<$^I> X<$INPLACE_EDIT> |
a0d0e21e |
1167 | |
1168 | The current value of the inplace-edit extension. Use C<undef> to disable |
1169 | inplace editing. (Mnemonic: value of B<-i> switch.) |
1170 | |
fb73857a |
1171 | =item $^M |
a054c801 |
1172 | X<$^M> |
fb73857a |
1173 | |
19799a22 |
1174 | By default, running out of memory is an untrappable, fatal error. |
1175 | However, if suitably built, Perl can use the contents of C<$^M> |
1176 | as an emergency memory pool after die()ing. Suppose that your Perl |
0acca065 |
1177 | were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. |
19799a22 |
1178 | Then |
fb73857a |
1179 | |
19799a22 |
1180 | $^M = 'a' x (1 << 16); |
fb73857a |
1181 | |
51ee6500 |
1182 | would allocate a 64K buffer for use in an emergency. See the |
19799a22 |
1183 | F<INSTALL> file in the Perl distribution for information on how to |
0acca065 |
1184 | add custom C compilation flags when compiling perl. To discourage casual |
1185 | use of this advanced feature, there is no L<English|English> long name for |
1186 | this variable. |
fb73857a |
1187 | |
5c055ba3 |
1188 | =item $OSNAME |
6e2995f4 |
1189 | |
5c055ba3 |
1190 | =item $^O |
a054c801 |
1191 | X<$^O> X<$OSNAME> |
5c055ba3 |
1192 | |
1193 | The name of the operating system under which this copy of Perl was |
1194 | built, as determined during the configuration process. The value |
19799a22 |
1195 | is identical to C<$Config{'osname'}>. See also L<Config> and the |
1196 | B<-V> command-line switch documented in L<perlrun>. |
5c055ba3 |
1197 | |
443f6d01 |
1198 | In Windows platforms, $^O is not very helpful: since it is always |
7f510801 |
1199 | C<MSWin32>, it doesn't tell the difference between |
1200 | 95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or |
1201 | Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish |
1202 | between the variants. |
916d64a3 |
1203 | |
e2e27056 |
1204 | =item ${^OPEN} |
1205 | |
1206 | An internal variable used by PerlIO. A string in two parts, separated |
fae2c0fb |
1207 | by a C<\0> byte, the first part describes the input layers, the second |
1208 | part describes the output layers. |
e2e27056 |
1209 | |
a0d0e21e |
1210 | =item $PERLDB |
1211 | |
1212 | =item $^P |
a054c801 |
1213 | X<$^P> X<$PERLDB> |
a0d0e21e |
1214 | |
19799a22 |
1215 | The internal variable for debugging support. The meanings of the |
1216 | various bits are subject to change, but currently indicate: |
84902520 |
1217 | |
1218 | =over 6 |
1219 | |
1220 | =item 0x01 |
1221 | |
1222 | Debug subroutine enter/exit. |
1223 | |
1224 | =item 0x02 |
1225 | |
4c85b59c |
1226 | Line-by-line debugging. Causes DB::DB() subroutine to be called for each |
1227 | statement executed. Also causes saving source code lines (like 0x400). |
84902520 |
1228 | |
1229 | =item 0x04 |
1230 | |
1231 | Switch off optimizations. |
1232 | |
1233 | =item 0x08 |
1234 | |
1235 | Preserve more data for future interactive inspections. |
1236 | |
1237 | =item 0x10 |
1238 | |
1239 | Keep info about source lines on which a subroutine is defined. |
1240 | |
1241 | =item 0x20 |
1242 | |
1243 | Start with single-step on. |
1244 | |
83ee9e09 |
1245 | =item 0x40 |
1246 | |
1247 | Use subroutine address instead of name when reporting. |
1248 | |
1249 | =item 0x80 |
1250 | |
1251 | Report C<goto &subroutine> as well. |
1252 | |
1253 | =item 0x100 |
1254 | |
1255 | Provide informative "file" names for evals based on the place they were compiled. |
1256 | |
1257 | =item 0x200 |
1258 | |
1259 | Provide informative names to anonymous subroutines based on the place they |
1260 | were compiled. |
1261 | |
7619c85e |
1262 | =item 0x400 |
1263 | |
4c85b59c |
1264 | Save source code lines into C<@{"_<$filename"}>. |
7619c85e |
1265 | |
84902520 |
1266 | =back |
1267 | |
19799a22 |
1268 | Some bits may be relevant at compile-time only, some at |
1269 | run-time only. This is a new mechanism and the details may change. |
4c85b59c |
1270 | See also L<perldebguts>. |
a0d0e21e |
1271 | |
66558a10 |
1272 | =item $LAST_REGEXP_CODE_RESULT |
1273 | |
b9ac3b5b |
1274 | =item $^R |
a054c801 |
1275 | X<$^R> X<$LAST_REGEXP_CODE_RESULT> |
b9ac3b5b |
1276 | |
19799a22 |
1277 | The result of evaluation of the last successful C<(?{ code })> |
1278 | regular expression assertion (see L<perlre>). May be written to. |
b9ac3b5b |
1279 | |
66558a10 |
1280 | =item $EXCEPTIONS_BEING_CAUGHT |
1281 | |
fb73857a |
1282 | =item $^S |
a054c801 |
1283 | X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> |
fb73857a |
1284 | |
fa05a9fd |
1285 | Current state of the interpreter. |
1286 | |
1287 | $^S State |
1288 | --------- ------------------- |
1289 | undef Parsing module/eval |
1290 | true (1) Executing an eval |
1291 | false (0) Otherwise |
1292 | |
1293 | The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. |
fb73857a |
1294 | |
a0d0e21e |
1295 | =item $BASETIME |
1296 | |
1297 | =item $^T |
a054c801 |
1298 | X<$^T> X<$BASETIME> |
a0d0e21e |
1299 | |
19799a22 |
1300 | The time at which the program began running, in seconds since the |
5f05dabc |
1301 | epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, |
19799a22 |
1302 | and B<-C> filetests are based on this value. |
a0d0e21e |
1303 | |
7c36658b |
1304 | =item ${^TAINT} |
1305 | |
9aa05f58 |
1306 | Reflects if taint mode is on or off. 1 for on (the program was run with |
1307 | B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with |
18e8c5b0 |
1308 | B<-t> or B<-TU>). This variable is read-only. |
7c36658b |
1309 | |
a05d7ebb |
1310 | =item ${^UNICODE} |
1311 | |
ab9e1bb7 |
1312 | Reflects certain Unicode settings of Perl. See L<perlrun> |
1313 | documentation for the C<-C> switch for more information about |
1314 | the possible values. This variable is set during Perl startup |
1315 | and is thereafter read-only. |
fde18df1 |
1316 | |
e07ea26a |
1317 | =item ${^UTF8CACHE} |
1318 | |
1319 | This variable controls the state of the internal UTF-8 offset caching code. |
16d9fe92 |
1320 | 1 for on (the default), 0 for off, -1 to debug the caching code by checking |
1321 | all its results against linear scans, and panicking on any discrepancy. |
e07ea26a |
1322 | |
ea8eae40 |
1323 | =item ${^UTF8LOCALE} |
1324 | |
1325 | This variable indicates whether an UTF-8 locale was detected by perl at |
1326 | startup. This information is used by perl when it's in |
1327 | adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line |
1328 | switch); see L<perlrun> for more info on this. |
1329 | |
44dcb63b |
1330 | =item $PERL_VERSION |
b459063d |
1331 | |
16070b82 |
1332 | =item $^V |
a054c801 |
1333 | X<$^V> X<$PERL_VERSION> |
16070b82 |
1334 | |
1335 | The revision, version, and subversion of the Perl interpreter, represented |
a32521b7 |
1336 | as a C<version> object. |
16070b82 |
1337 | |
7d2b1222 |
1338 | This variable first appeared in perl 5.6.0; earlier versions of perl will |
a32521b7 |
1339 | see an undefined value. Before perl 5.10.0 $^V was represented as a v-string. |
7d2b1222 |
1340 | |
a32521b7 |
1341 | $^V can be used to determine whether the Perl interpreter executing a |
16070b82 |
1342 | script is in the right range of versions. (Mnemonic: use ^V for Version |
44dcb63b |
1343 | Control.) Example: |
16070b82 |
1344 | |
7d2b1222 |
1345 | warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 |
16070b82 |
1346 | |
aa2f2a36 |
1347 | To convert C<$^V> into its string representation use sprintf()'s |
1348 | C<"%vd"> conversion: |
1349 | |
1350 | printf "version is v%vd\n", $^V; # Perl's version |
1351 | |
44dcb63b |
1352 | See the documentation of C<use VERSION> and C<require VERSION> |
16070b82 |
1353 | for a convenient way to fail if the running Perl interpreter is too old. |
1354 | |
1355 | See also C<$]> for an older representation of the Perl version. |
1356 | |
a0d0e21e |
1357 | =item $WARNING |
1358 | |
1359 | =item $^W |
a054c801 |
1360 | X<$^W> X<$WARNING> |
a0d0e21e |
1361 | |
19799a22 |
1362 | The current value of the warning switch, initially true if B<-w> |
1363 | was used, false otherwise, but directly modifiable. (Mnemonic: |
4438c4b7 |
1364 | related to the B<-w> switch.) See also L<warnings>. |
1365 | |
6a818117 |
1366 | =item ${^WARNING_BITS} |
4438c4b7 |
1367 | |
1368 | The current set of warning checks enabled by the C<use warnings> pragma. |
1369 | See the documentation of C<warnings> for more details. |
a0d0e21e |
1370 | |
2a8c8378 |
1371 | =item ${^WIN32_SLOPPY_STAT} |
1372 | |
1373 | If this variable is set to a true value, then stat() on Windows will |
1374 | not try to open the file. This means that the link count cannot be |
1375 | determined and file attributes may be out of date if additional |
1376 | hardlinks to the file exist. On the other hand, not opening the file |
1377 | is considerably faster, especially for files on network drives. |
1378 | |
1379 | This variable could be set in the F<sitecustomize.pl> file to |
1380 | configure the local Perl installation to use "sloppy" stat() by |
1381 | default. See L<perlrun> for more information about site |
1382 | customization. |
1383 | |
a0d0e21e |
1384 | =item $EXECUTABLE_NAME |
1385 | |
1386 | =item $^X |
a054c801 |
1387 | X<$^X> X<$EXECUTABLE_NAME> |
a0d0e21e |
1388 | |
e71940de |
1389 | The name used to execute the current copy of Perl, from C's |
21c1191d |
1390 | C<argv[0]> or (where supported) F</proc/self/exe>. |
38e4f4ae |
1391 | |
e71940de |
1392 | Depending on the host operating system, the value of $^X may be |
1393 | a relative or absolute pathname of the perl program file, or may |
1394 | be the string used to invoke perl but not the pathname of the |
1395 | perl program file. Also, most operating systems permit invoking |
1396 | programs that are not in the PATH environment variable, so there |
a10d74f3 |
1397 | is no guarantee that the value of $^X is in PATH. For VMS, the |
1398 | value may or may not include a version number. |
38e4f4ae |
1399 | |
e71940de |
1400 | You usually can use the value of $^X to re-invoke an independent |
1401 | copy of the same perl that is currently running, e.g., |
1402 | |
1403 | @first_run = `$^X -le "print int rand 100 for 1..100"`; |
1404 | |
1405 | But recall that not all operating systems support forking or |
1406 | capturing of the output of commands, so this complex statement |
1407 | may not be portable. |
38e4f4ae |
1408 | |
e71940de |
1409 | It is not safe to use the value of $^X as a path name of a file, |
1410 | as some operating systems that have a mandatory suffix on |
1411 | executable files do not require use of the suffix when invoking |
1412 | a command. To convert the value of $^X to a path name, use the |
1413 | following statements: |
1414 | |
304dea91 |
1415 | # Build up a set of file names (not command names). |
e71940de |
1416 | use Config; |
68fb0eb7 |
1417 | $this_perl = $^X; |
1418 | if ($^O ne 'VMS') |
1419 | {$this_perl .= $Config{_exe} |
1420 | unless $this_perl =~ m/$Config{_exe}$/i;} |
e71940de |
1421 | |
1422 | Because many operating systems permit anyone with read access to |
1423 | the Perl program file to make a copy of it, patch the copy, and |
1424 | then execute the copy, the security-conscious Perl programmer |
1425 | should take care to invoke the installed copy of perl, not the |
1426 | copy referenced by $^X. The following statements accomplish |
1427 | this goal, and produce a pathname that can be invoked as a |
1428 | command or referenced as a file. |
38e4f4ae |
1429 | |
1430 | use Config; |
68fb0eb7 |
1431 | $secure_perl_path = $Config{perlpath}; |
1432 | if ($^O ne 'VMS') |
1433 | {$secure_perl_path .= $Config{_exe} |
1434 | unless $secure_perl_path =~ m/$Config{_exe}$/i;} |
a0d0e21e |
1435 | |
2d84a16a |
1436 | =item ARGV |
a054c801 |
1437 | X<ARGV> |
2d84a16a |
1438 | |
1439 | The special filehandle that iterates over command-line filenames in |
1440 | C<@ARGV>. Usually written as the null filehandle in the angle operator |
1441 | C<< <> >>. Note that currently C<ARGV> only has its magical effect |
1442 | within the C<< <> >> operator; elsewhere it is just a plain filehandle |
1443 | corresponding to the last file opened by C<< <> >>. In particular, |
1444 | passing C<\*ARGV> as a parameter to a function that expects a filehandle |
1445 | may not cause your function to automatically read the contents of all the |
1446 | files in C<@ARGV>. |
1447 | |
a0d0e21e |
1448 | =item $ARGV |
a054c801 |
1449 | X<$ARGV> |
a0d0e21e |
1450 | |
c47ff5f1 |
1451 | contains the name of the current file when reading from <>. |
a0d0e21e |
1452 | |
1453 | =item @ARGV |
a054c801 |
1454 | X<@ARGV> |
a0d0e21e |
1455 | |
19799a22 |
1456 | The array @ARGV contains the command-line arguments intended for |
14218588 |
1457 | the script. C<$#ARGV> is generally the number of arguments minus |
19799a22 |
1458 | one, because C<$ARGV[0]> is the first argument, I<not> the program's |
1459 | command name itself. See C<$0> for the command name. |
a0d0e21e |
1460 | |
5ccee41e |
1461 | =item ARGVOUT |
a054c801 |
1462 | X<ARGVOUT> |
5ccee41e |
1463 | |
1464 | The special filehandle that points to the currently open output file |
1465 | when doing edit-in-place processing with B<-i>. Useful when you have |
1466 | to do a lot of inserting and don't want to keep modifying $_. See |
1467 | L<perlrun> for the B<-i> switch. |
1468 | |
9b0e6e7a |
1469 | =item @F |
a054c801 |
1470 | X<@F> |
9b0e6e7a |
1471 | |
1472 | The array @F contains the fields of each line read in when autosplit |
1473 | mode is turned on. See L<perlrun> for the B<-a> switch. This array |
1474 | is package-specific, and must be declared or given a full package name |
1475 | if not in package main when running under C<strict 'vars'>. |
1476 | |
a0d0e21e |
1477 | =item @INC |
a054c801 |
1478 | X<@INC> |
a0d0e21e |
1479 | |
19799a22 |
1480 | The array @INC contains the list of places that the C<do EXPR>, |
1481 | C<require>, or C<use> constructs look for their library files. It |
1482 | initially consists of the arguments to any B<-I> command-line |
1483 | switches, followed by the default Perl library, probably |
1484 | F</usr/local/lib/perl>, followed by ".", to represent the current |
e48df184 |
1485 | directory. ("." will not be appended if taint checks are enabled, either by |
1486 | C<-T> or by C<-t>.) If you need to modify this at runtime, you should use |
19799a22 |
1487 | the C<use lib> pragma to get the machine-dependent library properly |
1488 | loaded also: |
a0d0e21e |
1489 | |
cb1a09d0 |
1490 | use lib '/mypath/libdir/'; |
1491 | use SomeMod; |
303f2f76 |
1492 | |
d54b56d5 |
1493 | You can also insert hooks into the file inclusion system by putting Perl |
1494 | code directly into @INC. Those hooks may be subroutine references, array |
1495 | references or blessed objects. See L<perlfunc/require> for details. |
1496 | |
314d39ce |
1497 | =item @ARG |
1498 | |
fb73857a |
1499 | =item @_ |
a054c801 |
1500 | X<@_> X<@ARG> |
fb73857a |
1501 | |
1502 | Within a subroutine the array @_ contains the parameters passed to that |
19799a22 |
1503 | subroutine. See L<perlsub>. |
fb73857a |
1504 | |
a0d0e21e |
1505 | =item %INC |
a054c801 |
1506 | X<%INC> |
a0d0e21e |
1507 | |
19799a22 |
1508 | The hash %INC contains entries for each filename included via the |
1509 | C<do>, C<require>, or C<use> operators. The key is the filename |
1510 | you specified (with module names converted to pathnames), and the |
14218588 |
1511 | value is the location of the file found. The C<require> |
87275199 |
1512 | operator uses this hash to determine whether a particular file has |
19799a22 |
1513 | already been included. |
a0d0e21e |
1514 | |
89ccab8c |
1515 | If the file was loaded via a hook (e.g. a subroutine reference, see |
1516 | L<perlfunc/require> for a description of these hooks), this hook is |
9ae8cd5b |
1517 | by default inserted into %INC in place of a filename. Note, however, |
1518 | that the hook may have set the %INC entry by itself to provide some more |
1519 | specific info. |
44f0be63 |
1520 | |
b687b08b |
1521 | =item %ENV |
1522 | |
1523 | =item $ENV{expr} |
a054c801 |
1524 | X<%ENV> |
a0d0e21e |
1525 | |
1526 | The hash %ENV contains your current environment. Setting a |
19799a22 |
1527 | value in C<ENV> changes the environment for any child processes |
1528 | you subsequently fork() off. |
a0d0e21e |
1529 | |
b687b08b |
1530 | =item %SIG |
1531 | |
1532 | =item $SIG{expr} |
a054c801 |
1533 | X<%SIG> |
a0d0e21e |
1534 | |
efbd929d |
1535 | The hash C<%SIG> contains signal handlers for signals. For example: |
a0d0e21e |
1536 | |
1537 | sub handler { # 1st argument is signal name |
fb73857a |
1538 | my($sig) = @_; |
a0d0e21e |
1539 | print "Caught a SIG$sig--shutting down\n"; |
1540 | close(LOG); |
1541 | exit(0); |
1542 | } |
1543 | |
fb73857a |
1544 | $SIG{'INT'} = \&handler; |
1545 | $SIG{'QUIT'} = \&handler; |
a0d0e21e |
1546 | ... |
19799a22 |
1547 | $SIG{'INT'} = 'DEFAULT'; # restore default action |
a0d0e21e |
1548 | $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT |
1549 | |
f648820c |
1550 | Using a value of C<'IGNORE'> usually has the effect of ignoring the |
1551 | signal, except for the C<CHLD> signal. See L<perlipc> for more about |
1552 | this special case. |
1553 | |
19799a22 |
1554 | Here are some other examples: |
a0d0e21e |
1555 | |
fb73857a |
1556 | $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) |
a0d0e21e |
1557 | $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber |
19799a22 |
1558 | $SIG{"PIPE"} = *Plumber; # somewhat esoteric |
a0d0e21e |
1559 | $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? |
1560 | |
19799a22 |
1561 | Be sure not to use a bareword as the name of a signal handler, |
1562 | lest you inadvertently call it. |
748a9306 |
1563 | |
44a8e56a |
1564 | If your system has the sigaction() function then signal handlers are |
9ce5b4ad |
1565 | installed using it. This means you get reliable signal handling. |
44a8e56a |
1566 | |
9ce5b4ad |
1567 | The default delivery policy of signals changed in Perl 5.8.0 from |
1568 | immediate (also known as "unsafe") to deferred, also known as |
1569 | "safe signals". See L<perlipc> for more information. |
45c0772f |
1570 | |
748a9306 |
1571 | Certain internal hooks can be also set using the %SIG hash. The |
a8f8344d |
1572 | routine indicated by C<$SIG{__WARN__}> is called when a warning message is |
748a9306 |
1573 | about to be printed. The warning message is passed as the first |
efbd929d |
1574 | argument. The presence of a C<__WARN__> hook causes the ordinary printing |
1575 | of warnings to C<STDERR> to be suppressed. You can use this to save warnings |
748a9306 |
1576 | in a variable, or turn warnings into fatal errors, like this: |
1577 | |
1578 | local $SIG{__WARN__} = sub { die $_[0] }; |
1579 | eval $proggie; |
1580 | |
efbd929d |
1581 | As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can |
1582 | disable warnings using the empty subroutine: |
1583 | |
1584 | local $SIG{__WARN__} = sub {}; |
1585 | |
a8f8344d |
1586 | The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception |
748a9306 |
1587 | is about to be thrown. The error message is passed as the first |
efbd929d |
1588 | argument. When a C<__DIE__> hook routine returns, the exception |
748a9306 |
1589 | processing continues as it would have in the absence of the hook, |
efbd929d |
1590 | unless the hook routine itself exits via a C<goto>, a loop exit, or a C<die()>. |
774d564b |
1591 | The C<__DIE__> handler is explicitly disabled during the call, so that you |
fb73857a |
1592 | can die from a C<__DIE__> handler. Similarly for C<__WARN__>. |
1593 | |
19799a22 |
1594 | Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called |
1595 | even inside an eval(). Do not use this to rewrite a pending exception |
efbd929d |
1596 | in C<$@>, or as a bizarre substitute for overriding C<CORE::GLOBAL::die()>. |
19799a22 |
1597 | This strange action at a distance may be fixed in a future release |
1598 | so that C<$SIG{__DIE__}> is only called if your program is about |
1599 | to exit, as was the original intent. Any other use is deprecated. |
1600 | |
1601 | C<__DIE__>/C<__WARN__> handlers are very special in one respect: |
1602 | they may be called to report (probable) errors found by the parser. |
1603 | In such a case the parser may be in inconsistent state, so any |
1604 | attempt to evaluate Perl code from such a handler will probably |
1605 | result in a segfault. This means that warnings or errors that |
1606 | result from parsing Perl should be used with extreme caution, like |
1607 | this: |
fb73857a |
1608 | |
1609 | require Carp if defined $^S; |
1610 | Carp::confess("Something wrong") if defined &Carp::confess; |
1611 | die "Something wrong, but could not load Carp to give backtrace... |
1612 | To see backtrace try starting Perl with -MCarp switch"; |
1613 | |
1614 | Here the first line will load Carp I<unless> it is the parser who |
1615 | called the handler. The second line will print backtrace and die if |
1616 | Carp was available. The third line will be executed only if Carp was |
1617 | not available. |
1618 | |
19799a22 |
1619 | See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and |
4438c4b7 |
1620 | L<warnings> for additional information. |
68dc0745 |
1621 | |
a0d0e21e |
1622 | =back |
55602bd2 |
1623 | |
1624 | =head2 Error Indicators |
a054c801 |
1625 | X<error> X<exception> |
55602bd2 |
1626 | |
19799a22 |
1627 | The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information |
1628 | about different types of error conditions that may appear during |
1629 | execution of a Perl program. The variables are shown ordered by |
1630 | the "distance" between the subsystem which reported the error and |
1631 | the Perl process. They correspond to errors detected by the Perl |
1632 | interpreter, C library, operating system, or an external program, |
1633 | respectively. |
55602bd2 |
1634 | |
1635 | To illustrate the differences between these variables, consider the |
19799a22 |
1636 | following Perl expression, which uses a single-quoted string: |
55602bd2 |
1637 | |
19799a22 |
1638 | eval q{ |
22d0716c |
1639 | open my $pipe, "/cdrom/install |" or die $!; |
1640 | my @res = <$pipe>; |
1641 | close $pipe or die "bad pipe: $?, $!"; |
19799a22 |
1642 | }; |
55602bd2 |
1643 | |
1644 | After execution of this statement all 4 variables may have been set. |
1645 | |
19799a22 |
1646 | C<$@> is set if the string to be C<eval>-ed did not compile (this |
1647 | may happen if C<open> or C<close> were imported with bad prototypes), |
1648 | or if Perl code executed during evaluation die()d . In these cases |
1649 | the value of $@ is the compile error, or the argument to C<die> |
4cb1c523 |
1650 | (which will interpolate C<$!> and C<$?>). (See also L<Fatal>, |
19799a22 |
1651 | though.) |
1652 | |
c47ff5f1 |
1653 | When the eval() expression above is executed, open(), C<< <PIPE> >>, |
19799a22 |
1654 | and C<close> are translated to calls in the C run-time library and |
1655 | thence to the operating system kernel. C<$!> is set to the C library's |
1656 | C<errno> if one of these calls fails. |
1657 | |
1658 | Under a few operating systems, C<$^E> may contain a more verbose |
1659 | error indicator, such as in this case, "CDROM tray not closed." |
14218588 |
1660 | Systems that do not support extended error messages leave C<$^E> |
19799a22 |
1661 | the same as C<$!>. |
1662 | |
1663 | Finally, C<$?> may be set to non-0 value if the external program |
1664 | F</cdrom/install> fails. The upper eight bits reflect specific |
1665 | error conditions encountered by the program (the program's exit() |
1666 | value). The lower eight bits reflect mode of failure, like signal |
1667 | death and core dump information See wait(2) for details. In |
1668 | contrast to C<$!> and C<$^E>, which are set only if error condition |
1669 | is detected, the variable C<$?> is set on each C<wait> or pipe |
1670 | C<close>, overwriting the old value. This is more like C<$@>, which |
1671 | on every eval() is always set on failure and cleared on success. |
2b92dfce |
1672 | |
19799a22 |
1673 | For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, |
1674 | and C<$?>. |
2b92dfce |
1675 | |
1676 | =head2 Technical Note on the Syntax of Variable Names |
1677 | |
19799a22 |
1678 | Variable names in Perl can have several formats. Usually, they |
1679 | must begin with a letter or underscore, in which case they can be |
1680 | arbitrarily long (up to an internal limit of 251 characters) and |
1681 | may contain letters, digits, underscores, or the special sequence |
1682 | C<::> or C<'>. In this case, the part before the last C<::> or |
1683 | C<'> is taken to be a I<package qualifier>; see L<perlmod>. |
2b92dfce |
1684 | |
1685 | Perl variable names may also be a sequence of digits or a single |
1686 | punctuation or control character. These names are all reserved for |
19799a22 |
1687 | special uses by Perl; for example, the all-digits names are used |
1688 | to hold data captured by backreferences after a regular expression |
1689 | match. Perl has a special syntax for the single-control-character |
1690 | names: It understands C<^X> (caret C<X>) to mean the control-C<X> |
1691 | character. For example, the notation C<$^W> (dollar-sign caret |
1692 | C<W>) is the scalar variable whose name is the single character |
1693 | control-C<W>. This is better than typing a literal control-C<W> |
1694 | into your program. |
2b92dfce |
1695 | |
87275199 |
1696 | Finally, new in Perl 5.6, Perl variable names may be alphanumeric |
19799a22 |
1697 | strings that begin with control characters (or better yet, a caret). |
1698 | These variables must be written in the form C<${^Foo}>; the braces |
1699 | are not optional. C<${^Foo}> denotes the scalar variable whose |
1700 | name is a control-C<F> followed by two C<o>'s. These variables are |
1701 | reserved for future special uses by Perl, except for the ones that |
1702 | begin with C<^_> (control-underscore or caret-underscore). No |
1703 | control-character name that begins with C<^_> will acquire a special |
1704 | meaning in any future version of Perl; such names may therefore be |
1705 | used safely in programs. C<$^_> itself, however, I<is> reserved. |
1706 | |
1fcb18de |
1707 | Perl identifiers that begin with digits, control characters, or |
1708 | punctuation characters are exempt from the effects of the C<package> |
1709 | declaration and are always forced to be in package C<main>; they are |
1710 | also exempt from C<strict 'vars'> errors. A few other names are also |
1711 | exempt in these ways: |
2b92dfce |
1712 | |
1713 | ENV STDIN |
1714 | INC STDOUT |
1715 | ARGV STDERR |
5b88253b |
1716 | ARGVOUT _ |
2b92dfce |
1717 | SIG |
1718 | |
1719 | In particular, the new special C<${^_XYZ}> variables are always taken |
19799a22 |
1720 | to be in package C<main>, regardless of any C<package> declarations |
747fafda |
1721 | presently in scope. |
2b92dfce |
1722 | |
19799a22 |
1723 | =head1 BUGS |
1724 | |
1725 | Due to an unfortunate accident of Perl's implementation, C<use |
1726 | English> imposes a considerable performance penalty on all regular |
1727 | expression matches in a program, regardless of whether they occur |
1728 | in the scope of C<use English>. For that reason, saying C<use |
1729 | English> in libraries is strongly discouraged. See the |
1730 | Devel::SawAmpersand module documentation from CPAN |
1577cd80 |
1731 | ( http://www.cpan.org/modules/by-module/Devel/ ) |
a054c801 |
1732 | for more information. Writing C<use English '-no_match_vars';> |
1733 | avoids the performance penalty. |
2b92dfce |
1734 | |
19799a22 |
1735 | Having to even think about the C<$^S> variable in your exception |
1736 | handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented |
1737 | invites grievous and difficult to track down errors. Avoid it |
1738 | and use an C<END{}> or CORE::GLOBAL::die override instead. |