/
perlvar.pod
2466 lines (1733 loc) · 80.5 KB
/
perlvar.pod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=head1 NAME
perlvar - Perl predefined variables
=head1 DESCRIPTION
=head2 The Syntax of Variable Names
Variable names in Perl can have several formats. Usually, they
must begin with a letter or underscore, in which case they can be
arbitrarily long (up to an internal limit of 251 characters) and
may contain letters, digits, underscores, or the special sequence
C<::> or C<'>. In this case, the part before the last C<::> or
C<'> is taken to be a I<package qualifier>; see L<perlmod>.
A Unicode letter that is not ASCII is not considered to be a letter
unless S<C<"use utf8">> is in effect, and somewhat more complicated
rules apply; see L<perldata/Identifier parsing> for details.
Perl variable names may also be a sequence of digits, a single
punctuation character, or the two-character sequence: C<^> (caret or
CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>.
These names are all reserved for
special uses by Perl; for example, the all-digits names are used
to hold data captured by backreferences after a regular expression
match.
Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
preceded by a caret. These must all be written in the form C<${^Foo}>;
the braces are not optional. C<${^Foo}> denotes the scalar variable
whose name is considered to be a control-C<F> followed by two C<o>'s.
These variables are
reserved for future special uses by Perl, except for the ones that
begin with C<^_> (caret-underscore). No
name that begins with C<^_> will acquire a special
meaning in any future version of Perl; such names may therefore be
used safely in programs. C<$^_> itself, however, I<is> reserved.
Perl identifiers that begin with digits or
punctuation characters are exempt from the effects of the C<package>
declaration and are always forced to be in package C<main>; they are
also exempt from C<strict 'vars'> errors. A few other names are also
exempt in these ways:
ENV STDIN
INC STDOUT
ARGV STDERR
ARGVOUT
SIG
In particular, the special C<${^_XYZ}> variables are always taken
to be in package C<main>, regardless of any C<package> declarations
presently in scope.
=head1 SPECIAL VARIABLES
The following names have special meaning to Perl. Most punctuation
names have reasonable mnemonics, or analogs in the shells.
Nevertheless, if you wish to use long variable names, you need only say:
use English;
at the top of your program. This aliases all the short names to the long
names in the current package. Some even have medium names, generally
borrowed from B<awk>. For more info, please see L<English>.
Before you continue, note the sort order for variables. In general, we
first list the variables in case-insensitive, almost-lexigraphical
order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
For variables with the same identifier, we list it in order of scalar,
array, hash, and bareword.
=head2 General Variables
=over 8
=item $ARG
=item $_
X<$_> X<$ARG>
The default input and pattern-searching space. The following pairs are
equivalent:
while (<>) {...} # equivalent only in while!
while (defined($_ = <>)) {...}
/^Subject:/
$_ =~ /^Subject:/
tr/a-z/A-Z/
$_ =~ tr/a-z/A-Z/
chomp
chomp($_)
Here are the places where Perl will assume C<$_> even if you don't use it:
=over 3
=item *
The following functions use C<$_> as a default argument:
abs, alarm, chomp, chop, chr, chroot,
cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
rmdir, say, sin, split (for its second
argument), sqrt, stat, study, uc, ucfirst,
unlink, unpack.
=item *
All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
See L<perlfunc/-X>
=item *
The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
when used without an C<=~> operator.
=item *
The default iterator variable in a C<foreach> loop if no other
variable is supplied.
=item *
The implicit iterator variable in the C<grep()> and C<map()> functions.
=item *
The implicit variable of C<given()>.
=item *
The default place to put the next value or input record
when a C<< <FH> >>, C<readline>, C<readdir> or C<each>
operation's result is tested by itself as the sole criterion of a C<while>
test. Outside a C<while> test, this will not happen.
=back
C<$_> is a global variable.
However, between perl v5.10.0 and v5.24.0, it could be used lexically by
writing C<my $_>. Making C<$_> refer to the global C<$_> in the same scope
was then possible with C<our $_>. This experimental feature was removed and is
now a fatal error, but you may encounter it in older code.
Mnemonic: underline is understood in certain operations.
=item @ARG
=item @_
X<@_> X<@ARG>
Within a subroutine the array C<@_> contains the parameters passed to
that subroutine. Inside a subroutine, C<@_> is the default array for
the array operators C<pop> and C<shift>.
See L<perlsub>.
=item $LIST_SEPARATOR
=item $"
X<$"> X<$LIST_SEPARATOR>
When an array or an array slice is interpolated into a double-quoted
string or a similar context such as C</.../>, its elements are
separated by this value. Default is a space. For example, this:
print "The array is: @array\n";
is equivalent to this:
print "The array is: " . join($", @array) . "\n";
Mnemonic: works in double-quoted context.
=item $PROCESS_ID
=item $PID
=item $$
X<$$> X<$PID> X<$PROCESS_ID>
The process number of the Perl running this script. Though you I<can> set
this variable, doing so is generally discouraged, although it can be
invaluable for some testing purposes. It will be reset automatically
across C<fork()> calls.
Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
would emulate POSIX semantics on Linux systems using LinuxThreads, a
partial implementation of POSIX Threads that has since been superseded
by the Native POSIX Thread Library (NPTL).
LinuxThreads is now obsolete on Linux, and caching C<getpid()>
like this made embedding perl unnecessarily complex (since you'd have
to manually update the value of $$), so now C<$$> and C<getppid()>
will always return the same values as the underlying C library.
Debian GNU/kFreeBSD systems also used LinuxThreads up until and
including the 6.0 release, but after that moved to FreeBSD thread
semantics, which are POSIX-like.
To see if your system is affected by this discrepancy check if
C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false
value. NTPL threads preserve the POSIX semantics.
Mnemonic: same as shells.
=item $PROGRAM_NAME
=item $0
X<$0> X<$PROGRAM_NAME>
Contains the name of the program being executed.
On some (but not all) operating systems assigning to C<$0> modifies
the argument area that the C<ps> program sees. On some platforms you
may have to use special C<ps> options or a different C<ps> to see the
changes. Modifying the C<$0> is more useful as a way of indicating the
current program state than it is for hiding the program you're
running.
Note that there are platform-specific limitations on the maximum
length of C<$0>. In the most extreme case it may be limited to the
space occupied by the original C<$0>.
In some platforms there may be arbitrary amount of padding, for
example space characters, after the modified name as shown by C<ps>.
In some platforms this padding may extend all the way to the original
length of the argument area, no matter what you do (this is the case
for example with Linux 2.2).
Note for BSD users: setting C<$0> does not completely remove "perl"
from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix
and the " (perl)" suffix are shown depends on your exact BSD variant
and version). This is an operating system feature, Perl cannot help it.
In multithreaded scripts Perl coordinates the threads so that any
thread may modify its copy of the C<$0> and the change becomes visible
to ps(1) (assuming the operating system plays along). Note that
the view of C<$0> the other threads have will not change since they
have their own copies of it.
If the program has been given to perl via the switches C<-e> or C<-E>,
C<$0> will contain the string C<"-e">.
On Linux as of perl v5.14.0 the legacy process name will be set with
C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as
perl has done since version 4.000. Now system utilities that read the
legacy process name such as ps, top and killall will recognize the
name you set when assigning to C<$0>. The string you supply will be
cut off at 16 bytes, this is a limitation imposed by Linux.
Mnemonic: same as B<sh> and B<ksh>.
=item $REAL_GROUP_ID
=item $GID
=item $(
X<$(> X<$GID> X<$REAL_GROUP_ID>
The real gid of this process. If you are on a machine that supports
membership in multiple groups simultaneously, gives a space separated
list of groups you are in. The first number is the one returned by
C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
the same as the first number.
However, a value assigned to C<$(> must be a single number used to
set the real gid. So the value given by C<$(> should I<not> be assigned
back to C<$(> without being forced numeric, such as by adding zero. Note
that this is different to the effective gid (C<$)>) which does take a
list.
You can change both the real gid and the effective gid at the same
time by using C<POSIX::setgid()>. Changes
to C<$(> require a check to C<$!>
to detect any possible errors after an attempted change.
Mnemonic: parentheses are used to I<group> things. The real gid is the
group you I<left>, if you're running setgid.
=item $EFFECTIVE_GROUP_ID
=item $EGID
=item $)
X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
The effective gid of this process. If you are on a machine that
supports membership in multiple groups simultaneously, gives a space
separated list of groups you are in. The first number is the one
returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
one of which may be the same as the first number.
Similarly, a value assigned to C<$)> must also be a space-separated
list of numbers. The first number sets the effective gid, and
the rest (if any) are passed to C<setgroups()>. To get the effect of an
empty list for C<setgroups()>, just repeat the new effective gid; that is,
to force an effective gid of 5 and an effectively empty C<setgroups()>
list, say C< $) = "5 5" >.
You can change both the effective gid and the real gid at the same
time by using C<POSIX::setgid()> (use only a single numeric argument).
Changes to C<$)> require a check to C<$!> to detect any possible errors
after an attempted change.
C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
and C<$)> can be swapped only on machines supporting C<setregid()>.
Mnemonic: parentheses are used to I<group> things. The effective gid
is the group that's I<right> for you, if you're running setgid.
=item $REAL_USER_ID
=item $UID
=item $<
X<< $< >> X<$UID> X<$REAL_USER_ID>
The real uid of this process. You can change both the real uid and the
effective uid at the same time by using C<POSIX::setuid()>. Since
changes to C<< $< >> require a system call, check C<$!> after a change
attempt to detect any possible errors.
Mnemonic: it's the uid you came I<from>, if you're running setuid.
=item $EFFECTIVE_USER_ID
=item $EUID
=item $>
X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
The effective uid of this process. For example:
$< = $>; # set real to effective uid
($<,$>) = ($>,$<); # swap real and effective uids
You can change both the effective uid and the real uid at the same
time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
to C<$!> to detect any possible errors after an attempted change.
C<< $< >> and C<< $> >> can be swapped only on machines
supporting C<setreuid()>.
Mnemonic: it's the uid you went I<to>, if you're running setuid.
=item $SUBSCRIPT_SEPARATOR
=item $SUBSEP
=item $;
X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
The subscript separator for multidimensional array emulation. If you
refer to a hash element as
$foo{$x,$y,$z}
it really means
$foo{join($;, $x, $y, $z)}
But don't put
@foo{$x,$y,$z} # a slice--note the @
which means
($foo{$x},$foo{$y},$foo{$z})
Default is "\034", the same as SUBSEP in B<awk>. If your keys contain
binary data there might not be any safe value for C<$;>.
Consider using "real" multidimensional arrays as described
in L<perllol>.
Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
=item $a
=item $b
X<$a> X<$b>
Special package variables when using C<sort()>, see L<perlfunc/sort>.
Because of this specialness C<$a> and C<$b> don't need to be declared
(using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
be able to use them in the C<sort()> comparison block or function.
=item %ENV
X<%ENV>
The hash C<%ENV> contains your current environment. Setting a
value in C<ENV> changes the environment for any child processes
you subsequently C<fork()> off.
As of v5.18.0, both keys and values stored in C<%ENV> are stringified.
my $foo = 1;
$ENV{'bar'} = \$foo;
if( ref $ENV{'bar'} ) {
say "Pre 5.18.0 Behaviour";
} else {
say "Post 5.18.0 Behaviour";
}
Previously, only child processes received stringified values:
my $foo = 1;
$ENV{'bar'} = \$foo;
# Always printed 'non ref'
system($^X, '-e',
q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
This happens because you can't really share arbitrary data structures with
foreign processes.
=item $OLD_PERL_VERSION
=item $]
X<$]> X<$OLD_PERL_VERSION>
The revision, version, and subversion of the Perl interpreter, represented
as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001".
This variable can be used to determine whether the Perl interpreter
executing a script is in the right range of versions:
warn "No PerlIO!\n" if "$]" < 5.008;
When comparing C<$]>, numeric comparison operators should be used, but the
variable should be stringified first to avoid issues where its original
numeric value is inaccurate.
See also the documentation of C<use VERSION> and C<require VERSION>
for a convenient way to fail if the running Perl interpreter is too old.
See L</$^V> for a representation of the Perl version as a L<version>
object, which allows more flexible string comparisons.
The main advantage of C<$]> over C<$^V> is that it works the same on any
version of Perl. The disadvantages are that it can't easily be compared
to versions in other formats (e.g. literal v-strings, "v1.2.3" or
version objects) and numeric comparisons are subject to the binary
floating point representation; it's good for numeric literal version
checks and bad for comparing to a variable that hasn't been
sanity-checked.
The C<$OLD_PERL_VERSION> form was added in Perl v5.20.0 for historical
reasons but its use is discouraged. (If your reason to use C<$]> is to
run code on old perls then referring to it as C<$OLD_PERL_VERSION> would
be self-defeating.)
Mnemonic: Is this version of perl in the right bracket?
=item $SYSTEM_FD_MAX
=item $^F
X<$^F> X<$SYSTEM_FD_MAX>
The maximum system file descriptor, ordinarily 2. System file
descriptors are passed to C<exec()>ed processes, while higher file
descriptors are not. Also, during an
C<open()>, system file descriptors are
preserved even if the C<open()> fails (ordinary file descriptors are
closed before the C<open()> is attempted). The close-on-exec
status of a file descriptor will be decided according to the value of
C<$^F> when the corresponding file, pipe, or socket was opened, not the
time of the C<exec()>.
=item @F
X<@F>
The array C<@F> contains the fields of each line read in when autosplit
mode is turned on. See L<perlrun|perlrun/-a> for the B<-a> switch. This
array is package-specific, and must be declared or given a full package
name if not in package main when running under C<strict 'vars'>.
=item @INC
X<@INC>
The array C<@INC> contains the list of places that the C<do EXPR>,
C<require>, or C<use> constructs look for their library files. It
initially consists of the arguments to any B<-I> command-line
switches, followed by the default Perl library, probably
F</usr/local/lib/perl>.
Prior to Perl 5.26, C<.> -which represents the current directory, was included
in C<@INC>; it has been removed. This change in behavior is documented
in L<C<PERL_USE_UNSAFE_INC>|perlrun/PERL_USE_UNSAFE_INC> and it is
not recommended that C<.> be re-added to C<@INC>.
If you need to modify C<@INC> at runtime, you should use the C<use lib> pragma
to get the machine-dependent library properly loaded as well:
use lib '/mypath/libdir/';
use SomeMod;
You can also insert hooks into the file inclusion system by putting Perl
code directly into C<@INC>. Those hooks may be subroutine references,
array references or blessed objects. See L<perlfunc/require> for details.
=item %INC
X<%INC>
The hash C<%INC> contains entries for each filename included via the
C<do>, C<require>, or C<use> operators. The key is the filename
you specified (with module names converted to pathnames), and the
value is the location of the file found. The C<require>
operator uses this hash to determine whether a particular file has
already been included.
If the file was loaded via a hook (e.g. a subroutine reference, see
L<perlfunc/require> for a description of these hooks), this hook is
by default inserted into C<%INC> in place of a filename. Note, however,
that the hook may have set the C<%INC> entry by itself to provide some more
specific info.
=item $INPLACE_EDIT
=item $^I
X<$^I> X<$INPLACE_EDIT>
The current value of the inplace-edit extension. Use C<undef> to disable
inplace editing.
Mnemonic: value of B<-i> switch.
=item @ISA
X<@ISA>
Each package contains a special array called C<@ISA> which contains a list
of that class's parent classes, if any. This array is simply a list of
scalars, each of which is a string that corresponds to a package name. The
array is examined when Perl does method resolution, which is covered in
L<perlobj>.
To load packages while adding them to C<@ISA>, see the L<parent> pragma. The
discouraged L<base> pragma does this as well, but should not be used except
when compatibility with the discouraged L<fields> pragma is required.
=item $^M
X<$^M>
By default, running out of memory is an untrappable, fatal error.
However, if suitably built, Perl can use the contents of C<$^M>
as an emergency memory pool after C<die()>ing. Suppose that your Perl
were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
Then
$^M = 'a' x (1 << 16);
would allocate a 64K buffer for use in an emergency. See the
F<INSTALL> file in the Perl distribution for information on how to
add custom C compilation flags when compiling perl. To discourage casual
use of this advanced feature, there is no L<English|English> long name for
this variable.
This variable was added in Perl 5.004.
=item $OSNAME
=item $^O
X<$^O> X<$OSNAME>
The name of the operating system under which this copy of Perl was
built, as determined during the configuration process. For examples
see L<perlport/PLATFORMS>.
The value is identical to C<$Config{'osname'}>. See also L<Config>
and the B<-V> command-line switch documented in L<perlrun|perlrun/-V>.
In Windows platforms, C<$^O> is not very helpful: since it is always
C<MSWin32>, it doesn't tell the difference between
95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
between the variants.
This variable was added in Perl 5.003.
=item %SIG
X<%SIG>
The hash C<%SIG> contains signal handlers for signals. For example:
sub handler { # 1st argument is signal name
my($sig) = @_;
print "Caught a SIG$sig--shutting down\n";
close(LOG);
exit(0);
}
$SIG{'INT'} = \&handler;
$SIG{'QUIT'} = \&handler;
...
$SIG{'INT'} = 'DEFAULT'; # restore default action
$SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
Using a value of C<'IGNORE'> usually has the effect of ignoring the
signal, except for the C<CHLD> signal. See L<perlipc> for more about
this special case. Using an empty string or C<undef> as the value has
the same effect as C<'DEFAULT'>.
Here are some other examples:
$SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not
# recommended)
$SIG{"PIPE"} = \&Plumber; # just fine; assume current
# Plumber
$SIG{"PIPE"} = *Plumber; # somewhat esoteric
$SIG{"PIPE"} = Plumber(); # oops, what did Plumber()
# return??
Be sure not to use a bareword as the name of a signal handler,
lest you inadvertently call it.
Using a string that doesn't correspond to any existing function or a
glob that doesn't contain a code slot is equivalent to C<'IGNORE'>,
but a warning is emitted when the handler is being called (the warning
is not emitted for the internal hooks described below).
If your system has the C<sigaction()> function then signal handlers
are installed using it. This means you get reliable signal handling.
The default delivery policy of signals changed in Perl v5.8.0 from
immediate (also known as "unsafe") to deferred, also known as "safe
signals". See L<perlipc> for more information.
Certain internal hooks can be also set using the C<%SIG> hash. The
routine indicated by C<$SIG{__WARN__}> is called when a warning
message is about to be printed. The warning message is passed as the
first argument. The presence of a C<__WARN__> hook causes the
ordinary printing of warnings to C<STDERR> to be suppressed. You can
use this to save warnings in a variable, or turn warnings into fatal
errors, like this:
local $SIG{__WARN__} = sub { die $_[0] };
eval $proggie;
As the C<'IGNORE'> hook is not supported by C<__WARN__>, its effect is
the same as using C<'DEFAULT'>. You can disable warnings using the
empty subroutine:
local $SIG{__WARN__} = sub {};
The routine indicated by C<$SIG{__DIE__}> is called when a fatal
exception is about to be thrown. The error message is passed as the
first argument. When a C<__DIE__> hook routine returns, the exception
processing continues as it would have in the absence of the hook,
unless the hook routine itself exits via a C<goto &sub>, a loop exit,
or a C<die()>. The C<__DIE__> handler is explicitly disabled during
the call, so that you can die from a C<__DIE__> handler. Similarly
for C<__WARN__>.
The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
never intended to happen this way, but an implementation glitch made
this possible. This used to be deprecated, as it allowed strange action
at a distance like rewriting a pending exception in C<$@>. Plans to
rectify this have been scrapped, as users found that rewriting a
pending exception is actually a useful feature, and not a bug.
The C<$SIG{__DIE__}> doesn't support C<'IGNORE'>; it has the same
effect as C<'DEFAULT'>.
C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
may be called to report (probable) errors found by the parser. In such
a case the parser may be in inconsistent state, so any attempt to
evaluate Perl code from such a handler will probably result in a
segfault. This means that warnings or errors that result from parsing
Perl should be used with extreme caution, like this:
require Carp if defined $^S;
Carp::confess("Something wrong") if defined &Carp::confess;
die "Something wrong, but could not load Carp to give "
. "backtrace...\n\t"
. "To see backtrace try starting Perl with -MCarp switch";
Here the first line will load C<Carp> I<unless> it is the parser who
called the handler. The second line will print backtrace and die if
C<Carp> was available. The third line will be executed only if C<Carp> was
not available.
Having to even think about the C<$^S> variable in your exception
handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
invites grievous and difficult to track down errors. Avoid it
and use an C<END{}> or CORE::GLOBAL::die override instead.
See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
L<warnings> for additional information.
=item $BASETIME
=item $^T
X<$^T> X<$BASETIME>
The time at which the program began running, in seconds since the
epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
and B<-C> filetests are based on this value.
=item $PERL_VERSION
=item $^V
X<$^V> X<$PERL_VERSION>
=for comment
These are documented in the generated file lib/Config.pod. This looks
like as good a place as any to give notice that they are documented.
The revision, version, and subversion of the Perl interpreter,
represented as a L<version> object.
This variable first appeared in perl v5.6.0; earlier versions of perl
will see an undefined value. Before perl v5.10.0 C<$^V> was represented
as a v-string rather than a L<version> object.
C<$^V> can be used to determine whether the Perl interpreter executing
a script is in the right range of versions. For example:
warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
While version objects overload stringification, to portably convert
C<$^V> into its string representation, use C<sprintf()>'s C<"%vd">
conversion, which works for both v-strings or version objects:
printf "version is v%vd\n", $^V; # Perl's version
See the documentation of C<use VERSION> and C<require VERSION>
for a convenient way to fail if the running Perl interpreter is too old.
See also C<L</$]>> for a decimal representation of the Perl version.
The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or
later, it overloads operators, allowing easy comparison against other
version representations (e.g. decimal, literal v-string, "v1.2.3", or
objects). The disadvantage is that prior to v5.10.0, it was only a
literal v-string, which can't be easily printed or compared, whereas
the behavior of C<$]> is unchanged on all versions of Perl.
Mnemonic: use ^V for a version object.
=item $EXECUTABLE_NAME
=item $^X
X<$^X> X<$EXECUTABLE_NAME>
The name used to execute the current copy of Perl, from C's
C<argv[0]> or (where supported) F</proc/self/exe>.
Depending on the host operating system, the value of C<$^X> may be
a relative or absolute pathname of the perl program file, or may
be the string used to invoke perl but not the pathname of the
perl program file. Also, most operating systems permit invoking
programs that are not in the PATH environment variable, so there
is no guarantee that the value of C<$^X> is in PATH. For VMS, the
value may or may not include a version number.
You usually can use the value of C<$^X> to re-invoke an independent
copy of the same perl that is currently running, e.g.,
@first_run = `$^X -le "print int rand 100 for 1..100"`;
But recall that not all operating systems support forking or
capturing of the output of commands, so this complex statement
may not be portable.
It is not safe to use the value of C<$^X> as a path name of a file,
as some operating systems that have a mandatory suffix on
executable files do not require use of the suffix when invoking
a command. To convert the value of C<$^X> to a path name, use the
following statements:
# Build up a set of file names (not command names).
use Config;
my $this_perl = $^X;
if ($^O ne 'VMS') {
$this_perl .= $Config{_exe}
unless $this_perl =~ m/$Config{_exe}$/i;
}
Because many operating systems permit anyone with read access to
the Perl program file to make a copy of it, patch the copy, and
then execute the copy, the security-conscious Perl programmer
should take care to invoke the installed copy of perl, not the
copy referenced by C<$^X>. The following statements accomplish
this goal, and produce a pathname that can be invoked as a
command or referenced as a file.
use Config;
my $secure_perl_path = $Config{perlpath};
if ($^O ne 'VMS') {
$secure_perl_path .= $Config{_exe}
unless $secure_perl_path =~ m/$Config{_exe}$/i;
}
=back
=head2 Variables related to regular expressions
Most of the special variables related to regular expressions are side
effects. Perl sets these variables when it has a successful match, so
you should check the match result before using them. For instance:
if( /P(A)TT(ER)N/ ) {
print "I found $1 and $2\n";
}
These variables are read-only and dynamically-scoped, unless we note
otherwise.
The dynamic nature of the regular expression variables means that
their value is limited to the block that they are in, as demonstrated
by this bit of code:
my $outer = 'Wallace and Grommit';
my $inner = 'Mutt and Jeff';
my $pattern = qr/(\S+) and (\S+)/;
sub show_n { print "\$1 is $1; \$2 is $2\n" }
{
OUTER:
show_n() if $outer =~ m/$pattern/;
INNER: {
show_n() if $inner =~ m/$pattern/;
}
show_n();
}
The output shows that while in the C<OUTER> block, the values of C<$1>
and C<$2> are from the match against C<$outer>. Inside the C<INNER>
block, the values of C<$1> and C<$2> are from the match against
C<$inner>, but only until the end of the block (i.e. the dynamic
scope). After the C<INNER> block completes, the values of C<$1> and
C<$2> return to the values for the match against C<$outer> even though
we have not made another match:
$1 is Wallace; $2 is Grommit
$1 is Mutt; $2 is Jeff
$1 is Wallace; $2 is Grommit
=head3 Performance issues
Traditionally in Perl, any use of any of the three variables C<$`>, C<$&>
or C<$'> (or their C<use English> equivalents) anywhere in the code, caused
all subsequent successful pattern matches to make a copy of the matched
string, in case the code might subsequently access one of those variables.
This imposed a considerable performance penalty across the whole program,
so generally the use of these variables has been discouraged.
In Perl 5.6.0 the C<@-> and C<@+> dynamic arrays were introduced that
supply the indices of successful matches. So you could for example do
this:
$str =~ /pattern/;
print $`, $&, $'; # bad: performance hit
print # good: no performance hit
substr($str, 0, $-[0]),
substr($str, $-[0], $+[0]-$-[0]),
substr($str, $+[0]);
In Perl 5.10.0 the C</p> match operator flag and the C<${^PREMATCH}>,
C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed
you to suffer the penalties only on patterns marked with C</p>.
In Perl 5.18.0 onwards, perl started noting the presence of each of the
three variables separately, and only copied that part of the string
required; so in
$`; $&; "abcdefgh" =~ /d/
perl would only copy the "abcd" part of the string. That could make a big
difference in something like
$str = 'x' x 1_000_000;
$&; # whoops
$str =~ /x/g # one char copied a million times, not a million chars
In Perl 5.20.0 a new copy-on-write system was enabled by default, which
finally fixes all performance issues with these three variables, and makes
them safe to use anywhere.
The C<Devel::NYTProf> and C<Devel::FindAmpersand> modules can help you
find uses of these problematic match variables in your code.
=over 8
=item $<I<digits>> ($1, $2, ...)
X<$1> X<$2> X<$3> X<$I<digits>>
Contains the subpattern from the corresponding set of capturing
parentheses from the last successful pattern match, not counting patterns
matched in nested blocks that have been exited already.
Note there is a distinction between a capture buffer which matches
the empty string a capture buffer which is optional. Eg, C<(x?)> and
C<(x)?> The latter may be undef, the former not.
These variables are read-only and dynamically-scoped.
Mnemonic: like \digits.
=item @{^CAPTURE}
X<@{^CAPTURE}> X<@^CAPTURE>
An array which exposes the contents of the capture buffers, if any, of
the last successful pattern match, not counting patterns matched
in nested blocks that have been exited already.
Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index
is equivalent to $2, etc.
if ("foal"=~/(.)(.)(.)(.)/) {
print join "-", @{^CAPTURE};
}
should output "f-o-a-l".
See also L<<< /$<I<digits>> ($1, $2, ...) >>>, L</%{^CAPTURE}> and
L</%{^CAPTURE_ALL}>.
Note that unlike most other regex magic variables there is no single
letter equivalent to C<@{^CAPTURE}>.
This variable was added in 5.25.7
=item $MATCH
=item $&
X<$&> X<$MATCH>
The string matched by the last successful pattern match (not counting
any matches hidden within a BLOCK or C<eval()> enclosed by the current
BLOCK).
See L</Performance issues> above for the serious performance implications
of using this variable (even once) in your code.
This variable is read-only and dynamically-scoped.
Mnemonic: like C<&> in some editors.
=item ${^MATCH}
X<${^MATCH}>
This is similar to C<$&> (C<$MATCH>) except that it does not incur the
performance penalty associated with that variable.
See L</Performance issues> above.
In Perl v5.18 and earlier, it is only guaranteed
to return a defined value when the pattern was compiled or executed with
the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
C<${^MATCH}> does the same thing as C<$MATCH>.
This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
=item $PREMATCH
=item $`
X<$`> X<$PREMATCH> X<${^PREMATCH}>
The string preceding whatever was matched by the last successful
pattern match, not counting any matches hidden within a BLOCK or C<eval>
enclosed by the current BLOCK.
See L</Performance issues> above for the serious performance implications
of using this variable (even once) in your code.
This variable is read-only and dynamically-scoped.
Mnemonic: C<`> often precedes a quoted string.
=item ${^PREMATCH}
X<$`> X<${^PREMATCH}>
This is similar to C<$`> ($PREMATCH) except that it does not incur the
performance penalty associated with that variable.
See L</Performance issues> above.
In Perl v5.18 and earlier, it is only guaranteed
to return a defined value when the pattern was compiled or executed with
the C</p> modifier. In Perl v5.20, the C</p> modifier does nothing, so
C<${^PREMATCH}> does the same thing as C<$PREMATCH>.