{ "mode": "man", "parameter": "perlvar", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perlvar/1/json", "generated": "2026-10-04T15:39:39Z", "sections": { "NAME": { "content": "perlvar - Perl predefined variables\n", "subsections": [] }, "DESCRIPTION": { "content": "", "subsections": [ { "name": "The Syntax of Variable Names", "content": "Variable names in Perl can have several formats. Usually, they must begin with a letter or\nunderscore, in which case they can be arbitrarily long (up to an internal limit of 251\ncharacters) and may contain letters, digits, underscores, or the special sequence \"::\" or\n\"'\". In this case, the part before the last \"::\" or \"'\" is taken to be a package qualifier;\nsee perlmod. A Unicode letter that is not ASCII is not considered to be a letter unless\n\"use utf8\" is in effect, and somewhat more complicated rules apply; see \"Identifier parsing\"\nin perldata for details.\n\nPerl variable names may also be a sequence of digits, a single punctuation character, or the\ntwo-character sequence: \"^\" (caret or CIRCUMFLEX ACCENT) followed by any one of the\ncharacters \"[][A-Z^?\\]\". These names are all reserved for special uses by Perl; for\nexample, the all-digits names are used to hold data captured by backreferences after a\nregular expression match.\n\nSince Perl v5.6.0, Perl variable names may also be alphanumeric strings preceded by a caret.\nThese must all be written using the demarcated variable form using curly braces such as\n\"${^Foo}\"; the braces are not optional. \"${^Foo}\" denotes the scalar variable whose name is\nconsidered to be a control-\"F\" followed by two \"o\"'s. (See \"Demarcated variable names using\nbraces\" in perldata for more information on this form of spelling a variable name or\nspecifying access to an element of an array or a hash). These variables are reserved for\nfuture special uses by Perl, except for the ones that begin with \"^\" (caret-underscore). No\nname that begins with \"^\" will acquire a special meaning in any future version of Perl; such\nnames may therefore be used safely in programs. $^ itself, however, is reserved.\n\nNote that you also must use the demarcated form to access subscripts of variables of this\ntype when interpolating, for instance to access the first element of the \"@{^CAPTURE}\"\nvariable inside of a double quoted string you would write \"${^CAPTURE[0]}\" and NOT\n\"${^CAPTURE}[0]\" which would mean to reference a scalar variable named \"${^CAPTURE}\" and not\nindex 0 of the magic \"@{^CAPTURE}\" array which is populated by the regex engine.\n\nPerl identifiers that begin with digits or punctuation characters are exempt from the effects\nof the \"package\" declaration and are always forced to be in package \"main\"; they are also\nexempt from \"strict 'vars'\" errors. A few other names are also exempt in these ways:\n\nENV STDIN\nINC STDOUT\nARGV STDERR\nARGVOUT\nSIG\n\nIn particular, the special \"${^XYZ}\" variables are always taken to be in package \"main\",\nregardless of any \"package\" declarations presently in scope.\n" } ] }, "SPECIAL VARIABLES": { "content": "The following names have special meaning to Perl. Most punctuation names have reasonable\nmnemonics, or analogs in the shells. Nevertheless, if you wish to use long variable names,\nyou need only say:\n\nuse English;\n\nat the top of your program. This aliases all the short names to the long names in the\ncurrent package. Some even have medium names, generally borrowed from awk. For more info,\nplease see English.\n\nBefore you continue, note the sort order for variables. In general, we first list the\nvariables in case-insensitive, almost-lexigraphical order (ignoring the \"{\" or \"^\" preceding\nwords, as in \"${^UNICODE}\" or $^T), although $ and @ move up to the top of the pile. For\nvariables with the same identifier, we list it in order of scalar, array, hash, and bareword.\n", "subsections": [ { "name": "General Variables", "content": "$ARG\n$ The default input and pattern-searching space. The following pairs are equivalent:\n\nwhile (<>) {...} # equivalent only in while!\nwhile (defined($ = <>)) {...}\n\n/^Subject:/\n$ =~ /^Subject:/\n\ntr/a-z/A-Z/\n$ =~ tr/a-z/A-Z/\n\nchomp\nchomp($)\n\nHere are the places where Perl will assume $ even if you don't use it:\n\n• The following functions use $ as a default argument:\n\nabs, alarm, chomp, chop, chr, chroot, cos, defined, eval, evalbytes, exp, fc,\nglob, hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,\nprintf, quotemeta, readlink, readpipe, ref, require, reverse (in scalar context\nonly), rmdir, say, sin, split (for its second argument), sqrt, stat, study, uc,\nucfirst, unlink, unpack.\n\n• All file tests (\"-f\", \"-d\") except for \"-t\", which defaults to STDIN. See \"-X\" in\nperlfunc\n\n• The pattern matching operations \"m//\", \"s///\" and \"tr///\" (aka \"y///\") when used\nwithout an \"=~\" operator.\n\n• The default iterator variable in a \"foreach\" loop if no other variable is\nsupplied.\n\n• The implicit iterator variable in the grep() and map() functions.\n\n• The implicit variable of given().\n\n• The default place to put the next value or input record when a \"\", \"readline\",\n\"readdir\" or \"each\" operation's result is tested by itself as the sole criterion\nof a \"while\" test. Outside a \"while\" test, this will not happen.\n\n$ is a global variable.\n\nHowever, between perl v5.10.0 and v5.24.0, it could be used lexically by writing \"my\n$\". Making $ refer to the global $ in the same scope was then possible with \"our\n$\". This experimental feature was removed and is now a fatal error, but you may\nencounter it in older code.\n\nMnemonic: underline is understood in certain operations.\n\n@ARG\n@ Within a subroutine the array @ contains the parameters passed to that subroutine.\nInside a subroutine, @ is the default array for the array operators \"pop\" and\n\"shift\".\n\nSee perlsub.\n\n$LISTSEPARATOR\n$\" When an array or an array slice is interpolated into a double-quoted string or a\nsimilar context such as \"/.../\", its elements are separated by this value. Default\nis a space. For example, this:\n\nprint \"The array is: @array\\n\";\n\nis equivalent to this:\n\nprint \"The array is: \" . join($\", @array) . \"\\n\";\n\nMnemonic: works in double-quoted context.\n\n$PROCESSID\n$PID\n$$ The process number of the Perl running this script. Though you can set this\nvariable, doing so is generally discouraged, although it can be invaluable for some\ntesting purposes. It will be reset automatically across fork() calls.\n\nNote for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl would emulate\nPOSIX semantics on Linux systems using LinuxThreads, a partial implementation of\nPOSIX Threads that has since been superseded by the Native POSIX Thread Library\n(NPTL).\n\nLinuxThreads is now obsolete on Linux, and caching getpid() like this made embedding\nperl unnecessarily complex (since you'd have to manually update the value of $$), so\nnow $$ and getppid() will always return the same values as the underlying C library.\n\nDebian GNU/kFreeBSD systems also used LinuxThreads up until and including the 6.0\nrelease, but after that moved to FreeBSD thread semantics, which are POSIX-like.\n\nTo see if your system is affected by this discrepancy check if \"getconf\nGNULIBPTHREADVERSION | grep -q NPTL\" returns a false value. NTPL threads preserve\nthe POSIX semantics.\n\nMnemonic: same as shells.\n\n$PROGRAMNAME\n$0 Contains the name of the program being executed.\n\nOn some (but not all) operating systems assigning to $0 modifies the argument area\nthat the \"ps\" program sees. On some platforms you may have to use special \"ps\"\noptions or a different \"ps\" to see the changes. Modifying the $0 is more useful as a\nway of indicating the current program state than it is for hiding the program you're\nrunning.\n\nNote that there are platform-specific limitations on the maximum length of $0. In\nthe most extreme case it may be limited to the space occupied by the original $0.\n\nIn some platforms there may be arbitrary amount of padding, for example space\ncharacters, after the modified name as shown by \"ps\". In some platforms this padding\nmay extend all the way to the original length of the argument area, no matter what\nyou do (this is the case for example with Linux 2.2).\n\nNote for BSD users: setting $0 does not completely remove \"perl\" from the ps(1)\noutput. For example, setting $0 to \"foobar\" may result in \"perl: foobar (perl)\"\n(whether both the \"perl: \" prefix and the \" (perl)\" suffix are shown depends on your\nexact BSD variant and version). This is an operating system feature, Perl cannot\nhelp it.\n\nIn multithreaded scripts Perl coordinates the threads so that any thread may modify\nits copy of the $0 and the change becomes visible to ps(1) (assuming the operating\nsystem plays along). Note that the view of $0 the other threads have will not change\nsince they have their own copies of it.\n\nIf the program has been given to perl via the switches \"-e\" or \"-E\", $0 will contain\nthe string \"-e\".\n\nOn Linux as of perl v5.14.0 the legacy process name will be set with prctl(2), in\naddition to altering the POSIX name via \"argv[0]\" as perl has done since version\n4.000. Now system utilities that read the legacy process name such as ps, top and\nkillall will recognize the name you set when assigning to $0. The string you supply\nwill be cut off at 16 bytes, this is a limitation imposed by Linux.\n\nWide characters are invalid in $0 values. For historical reasons, though, Perl\naccepts them and encodes them to UTF-8. When this happens a wide-character warning is\ntriggered.\n\nMnemonic: same as sh and ksh.\n\n$REALGROUPID\n$GID\n$( The real gid of this process. If you are on a machine that supports membership in\nmultiple groups simultaneously, gives a space separated list of groups you are in.\nThe first number is the one returned by getgid(), and the subsequent ones by\ngetgroups(), one of which may be the same as the first number.\n\nHowever, a value assigned to $( must be a single number used to set the real gid. So\nthe value given by $( should not be assigned back to $( without being forced numeric,\nsuch as by adding zero. Note that this is different to the effective gid ($)) which\ndoes take a list.\n\nYou can change both the real gid and the effective gid at the same time by using\nPOSIX::setgid(). Changes to $( require a check to $! to detect any possible errors\nafter an attempted change.\n\nMnemonic: parentheses are used to group things. The real gid is the group you left,\nif you're running setgid.\n\n$EFFECTIVEGROUPID\n$EGID\n$) The effective gid of this process. If you are on a machine that supports membership\nin multiple groups simultaneously, gives a space separated list of groups you are in.\nThe first number is the one returned by getegid(), and the subsequent ones by\ngetgroups(), one of which may be the same as the first number.\n\nSimilarly, a value assigned to $) must also be a space-separated list of numbers.\nThe first number sets the effective gid, and the rest (if any) are passed to\nsetgroups(). To get the effect of an empty list for setgroups(), just repeat the new\neffective gid; that is, to force an effective gid of 5 and an effectively empty\nsetgroups() list, say \" $) = \"5 5\" \".\n\nYou can change both the effective gid and the real gid at the same time by using\nPOSIX::setgid() (use only a single numeric argument). Changes to $) require a check\nto $! to detect any possible errors after an attempted change.\n\n$<, $>, $( and $) can be set only on machines that support the corresponding\nset[re][ug]id() routine. $( and $) can be swapped only on machines supporting\nsetregid().\n\nMnemonic: parentheses are used to group things. The effective gid is the group\nthat's right for you, if you're running setgid.\n\n$REALUSERID\n$UID\n$< The real uid of this process. You can change both the real uid and the effective uid\nat the same time by using POSIX::setuid(). Since changes to $< require a system\ncall, check $! after a change attempt to detect any possible errors.\n\nMnemonic: it's the uid you came from, if you're running setuid.\n\n$EFFECTIVEUSERID\n$EUID\n$> The effective uid of this process. For example:\n\n$< = $>; # set real to effective uid\n($<,$>) = ($>,$<); # swap real and effective uids\n\nYou can change both the effective uid and the real uid at the same time by using\nPOSIX::setuid(). Changes to $> require a check to $! to detect any possible errors\nafter an attempted change.\n\n$< and $> can be swapped only on machines supporting setreuid().\n\nMnemonic: it's the uid you went to, if you're running setuid.\n\n$SUBSCRIPTSEPARATOR\n$SUBSEP\n$; The subscript separator for multidimensional array emulation. If you refer to a hash\nelement as\n\n$foo{$x,$y,$z}\n\nit really means\n\n$foo{join($;, $x, $y, $z)}\n\nBut don't put\n\n@foo{$x,$y,$z} # a slice--note the @\n\nwhich means\n\n($foo{$x},$foo{$y},$foo{$z})\n\nDefault is \"\\034\", the same as SUBSEP in awk. If your keys contain binary data there\nmight not be any safe value for $;.\n\nConsider using \"real\" multidimensional arrays as described in perllol.\n\nMnemonic: comma (the syntactic subscript separator) is a semi-semicolon.\n\n$a\n$b Special package variables when using sort(), see \"sort\" in perlfunc. Because of this\nspecialness $a and $b don't need to be declared (using \"use vars\", or our()) even\nwhen using the \"strict 'vars'\" pragma. Don't lexicalize them with \"my $a\" or \"my $b\"\nif you want to be able to use them in the sort() comparison block or function.\n\n%ENV The hash %ENV contains your current environment. Setting a value in \"ENV\" changes\nthe environment for any child processes you subsequently fork() off.\n\nAs of v5.18.0, both keys and values stored in %ENV are stringified.\n\nmy $foo = 1;\n$ENV{'bar'} = \\$foo;\nif( ref $ENV{'bar'} ) {\nsay \"Pre 5.18.0 Behaviour\";\n} else {\nsay \"Post 5.18.0 Behaviour\";\n}\n\nPreviously, only child processes received stringified values:\n\nmy $foo = 1;\n$ENV{'bar'} = \\$foo;\n\n# Always printed 'non ref'\nsystem($^X, '-e',\nq/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);\n\nThis happens because you can't really share arbitrary data structures with foreign\nprocesses.\n\n$OLDPERLVERSION\n$] The revision, version, and subversion of the Perl interpreter, represented as a\ndecimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY is the\nsubversion / 1e6. For example, Perl v5.10.1 would be \"5.010001\".\n\nThis variable can be used to determine whether the Perl interpreter executing a\nscript is in the right range of versions:\n\nwarn \"No PerlIO!\\n\" if \"$]\" < 5.008;\n\nWhen comparing $], numeric comparison operators should be used, but the variable\nshould be stringified first to avoid issues where its original numeric value is\ninaccurate.\n\nSee also the documentation of \"use VERSION\" and \"require VERSION\" for a convenient\nway to fail if the running Perl interpreter is too old.\n\nSee \"$^V\" for a representation of the Perl version as a version object, which allows\nmore flexible string comparisons.\n\nThe main advantage of $] over $^V is that it works the same on any version of Perl.\nThe disadvantages are that it can't easily be compared to versions in other formats\n(e.g. literal v-strings, \"v1.2.3\" or version objects) and numeric comparisons are\nsubject to the binary floating point representation; it's good for numeric literal\nversion checks and bad for comparing to a variable that hasn't been sanity-checked.\n\nThe $OLDPERLVERSION form was added in Perl v5.20.0 for historical reasons but its\nuse is discouraged. (If your reason to use $] is to run code on old perls then\nreferring to it as $OLDPERLVERSION would be self-defeating.)\n\nMnemonic: Is this version of perl in the right bracket?\n\n$SYSTEMFDMAX\n$^F The maximum system file descriptor, ordinarily 2. System file descriptors are passed\nto exec()ed processes, while higher file descriptors are not. Also, during an\nopen(), system file descriptors are preserved even if the open() fails (ordinary file\ndescriptors are closed before the open() is attempted). The close-on-exec status of\na file descriptor will be decided according to the value of $^F when the\ncorresponding file, pipe, or socket was opened, not the time of the exec().\n\n@F The array @F contains the fields of each line read in when autosplit mode is turned\non. See perlrun for the -a switch. This array is package-specific, and must be\ndeclared or given a full package name if not in package main when running under\n\"strict 'vars'\".\n\n@INC The array @INC contains the list of places that the \"do EXPR\", \"require\", or \"use\"\nconstructs look for their library files. It initially consists of the arguments to\nany -I command-line switches, followed by the default Perl library, probably\n/usr/local/lib/perl. Prior to Perl 5.26, \".\" -which represents the current\ndirectory, was included in @INC; it has been removed. This change in behavior is\ndocumented in \"PERLUSEUNSAFEINC\" and it is not recommended that \".\" be re-added to\n@INC. If you need to modify @INC at runtime, you should use the \"use lib\" pragma to\nget the machine-dependent library properly loaded as well:\n\nuse lib '/mypath/libdir/';\nuse SomeMod;\n\nYou can also insert hooks into the file inclusion system by putting Perl code\ndirectly into @INC. Those hooks may be subroutine references, array references or\nblessed objects. See \"require\" in perlfunc for details.\n\n%INC The hash %INC contains entries for each filename included via the \"do\", \"require\", or\n\"use\" operators. The key is the filename you specified (with module names converted\nto pathnames), and the value is the location of the file found. The \"require\"\noperator uses this hash to determine whether a particular file has already been\nincluded.\n\nIf the file was loaded via a hook (e.g. a subroutine reference, see \"require\" in\nperlfunc for a description of these hooks), this hook is by default inserted into\n%INC in place of a filename. Note, however, that the hook may have set the %INC\nentry by itself to provide some more specific info.\n\n$INC As of 5.37.7 when an @INC hook is executed the index of the @INC array that holds the\nhook will be localized into the $INC variable. When the hook returns the integer\nsuccessor of its value will be used to determine the next index in @INC that will be\nchecked, thus if it is set to -1 (or \"undef\") the traversal over the @INC array will\nbe restarted from its beginning.\n\nNormally traversal through the @INC array is from beginning to end (\"0 .. $#INC\"),\nand if the @INC array is modified by the hook the iterator may be left in a state\nwhere newly added entries are skipped. Changing this value allows an @INC hook to\nrewrite the @INC array and tell Perl where to continue afterwards. See \"require\" in\nperlfunc for details on @INC hooks.\n\n$INPLACEEDIT\n$^I The current value of the inplace-edit extension. Use \"undef\" to disable inplace\nediting.\n\nMnemonic: value of -i switch.\n\n@ISA Each package contains a special array called @ISA which contains a list of that\nclass's parent classes, if any. This array is simply a list of scalars, each of which\nis a string that corresponds to a package name. The array is examined when Perl does\nmethod resolution, which is covered in perlobj.\n\nTo load packages while adding them to @ISA, see the parent pragma. The discouraged\nbase pragma does this as well, but should not be used except when compatibility with\nthe discouraged fields pragma is required.\n\n$^M By default, running out of memory is an untrappable, fatal error. However, if\nsuitably built, Perl can use the contents of $^M as an emergency memory pool after\ndie()ing. Suppose that your Perl were compiled with \"-DPERLEMERGENCYSBRK\" and used\nPerl's malloc. Then\n\n$^M = 'a' x (1 << 16);\n\nwould allocate a 64K buffer for use in an emergency. See the INSTALL file in the\nPerl distribution for information on how to add custom C compilation flags when\ncompiling perl. To discourage casual use of this advanced feature, there is no\nEnglish long name for this variable.\n\nThis variable was added in Perl 5.004.\n\n${^MAXNESTEDEVALBEGINBLOCKS}\nThis variable determines the maximum number \"eval EXPR\"/\"BEGIN\" or \"require\"/\"BEGIN\"\nblock nesting that is allowed. This means it also controls the maximum nesting of\n\"use\" statements as well.\n\nThe default of 1000 should be sufficiently large for normal working purposes, and if\nyou must raise it then you should be conservative with your choice or you may\nencounter segfaults from exhaustion of the C stack. It seems unlikely that real code\nhas a use depth above 1000, but we have left this configurable just in case.\n\nWhen set to 0 then \"BEGIN\" blocks inside of \"eval EXPR\" or \"require EXPR\" are\nforbidden entirely and will trigger an exception which will terminate the compilation\nand in the case of \"require\" will throw an exception, or in the case of \"eval\" return\nthe error in $@ as usual.\n\nConsider the code\n\nperl -le'sub f { eval \"BEGIN { f() }\"; } f()'\n\neach invocation of f() will consume considerable C stack, and this variable is used\nto cause code like this to die instead of exhausting the C stack and triggering a\nsegfault. Needless to say code like this is unusual, it is unlikely you will actually\nneed to raise the setting. However it may be useful to set it to 0 for a limited\ntime period to prevent BEGIN{} blocks from being executed during an \"eval EXPR\".\n\nNote that setting this to 1 would NOT affect code like this:\n\nBEGIN { $n += 1; BEGIN { $n += 2; BEGIN { $n += 4 } } }\n\nThe reason is that BEGIN blocks are executed immediately after they are completed,\nthus the innermost will execute before the ones which contain it have even finished\ncompiling, and the depth will not go above 1. In fact the above code is equivalent to\n\nBEGIN { $n+=4 }\nBEGIN { $n+=2 }\nBEGIN { $n+=1 }\n\nwhich makes it obvious why a ${^MAXEVALBEGINDEPTH} of 1 would not block this code.\n\nOnly \"BEGIN\"'s executed inside of an \"eval\" or \"require\" (possibly via \"use\") are\naffected.\n\n$OSNAME\n$^O The name of the operating system under which this copy of Perl was built, as\ndetermined during the configuration process. For examples see \"PLATFORMS\" in\nperlport.\n\nThe value is identical to $Config{'osname'}. See also Config and the -V command-line\nswitch documented in perlrun.\n\nIn Windows platforms, $^O is not very helpful: since it is always \"MSWin32\", it\ndoesn't tell the difference between 95/98/ME/NT/2000/XP/CE/.NET. Use\nWin32::GetOSName() or Win32::GetOSVersion() (see Win32 and perlport) to distinguish\nbetween the variants.\n\nThis variable was added in Perl 5.003.\n\n%SIG The hash %SIG contains signal handlers for signals. For example:\n\nsub handler { # 1st argument is signal name\nmy($sig) = @;\nprint \"Caught a SIG$sig--shutting down\\n\";\nclose(LOG);\nexit(0);\n}\n\n$SIG{'INT'} = \\&handler;\n$SIG{'QUIT'} = \\&handler;\n...\n$SIG{'INT'} = 'DEFAULT'; # restore default action\n$SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT\n\nUsing a value of 'IGNORE' usually has the effect of ignoring the signal, except for\nthe \"CHLD\" signal. See perlipc for more about this special case. Using an empty\nstring or \"undef\" as the value has the same effect as 'DEFAULT'.\n\nHere are some other examples:\n\n$SIG{\"PIPE\"} = \"Plumber\"; # assumes main::Plumber (not\n# recommended)\n$SIG{\"PIPE\"} = \\&Plumber; # just fine; assume current\n# Plumber\n$SIG{\"PIPE\"} = *Plumber; # somewhat esoteric\n$SIG{\"PIPE\"} = Plumber(); # oops, what did Plumber()\n# return??\n\nBe sure not to use a bareword as the name of a signal handler, lest you inadvertently\ncall it.\n\nUsing a string that doesn't correspond to any existing function or a glob that\ndoesn't contain a code slot is equivalent to 'IGNORE', but a warning is emitted when\nthe handler is being called (the warning is not emitted for the internal hooks\ndescribed below).\n\nIf your system has the sigaction() function then signal handlers are installed using\nit. This means you get reliable signal handling.\n\nThe default delivery policy of signals changed in Perl v5.8.0 from immediate (also\nknown as \"unsafe\") to deferred, also known as \"safe signals\". See perlipc for more\ninformation.\n\nCertain internal hooks can be also set using the %SIG hash. The routine indicated by\n$SIG{WARN} is called when a warning message is about to be printed. The warning\nmessage is passed as the first argument. The presence of a \"WARN\" hook causes\nthe ordinary printing of warnings to \"STDERR\" to be suppressed. You can use this to\nsave warnings in a variable, or turn warnings into fatal errors, like this:\n\nlocal $SIG{WARN} = sub { die $[0] };\neval $proggie;\n\nAs the 'IGNORE' hook is not supported by \"WARN\", its effect is the same as using\n'DEFAULT'. You can disable warnings using the empty subroutine:\n\nlocal $SIG{WARN} = sub {};\n\nThe routine indicated by $SIG{DIE} is called when a fatal exception is about to\nbe thrown. The error message is passed as the first argument. When a \"DIE\" hook\nroutine returns, the exception processing continues as it would have in the absence\nof the hook, unless the hook routine itself exits via a \"goto &sub\", a loop exit, or\na die(). The \"DIE\" handler is explicitly disabled during the call, so that you\ncan die from a \"DIE\" handler. Similarly for \"WARN\".\n\nThe $SIG{DIE} hook is called even inside an eval(). It was never intended to\nhappen this way, but an implementation glitch made this possible. This used to be\ndeprecated, as it allowed strange action at a distance like rewriting a pending\nexception in $@. Plans to rectify this have been scrapped, as users found that\nrewriting a pending exception is actually a useful feature, and not a bug.\n\nThe $SIG{DIE} doesn't support 'IGNORE'; it has the same effect as 'DEFAULT'.\n\n\"DIE\"/\"WARN\" handlers are very special in one respect: they may be called to\nreport (probable) errors found by the parser. In such a case the parser may be in\ninconsistent state, so any attempt to evaluate Perl code from such a handler will\nprobably result in a segfault. This means that warnings or errors that result from\nparsing Perl should be used with extreme caution, like this:\n\nrequire Carp if defined $^S;\nCarp::confess(\"Something wrong\") if defined &Carp::confess;\ndie \"Something wrong, but could not load Carp to give \"\n. \"backtrace...\\n\\t\"\n. \"To see backtrace try starting Perl with -MCarp switch\";\n\nHere the first line will load \"Carp\" unless it is the parser who called the handler.\nThe second line will print backtrace and die if \"Carp\" was available. The third line\nwill be executed only if \"Carp\" was not available.\n\nHaving to even think about the $^S variable in your exception handlers is simply\nwrong. $SIG{DIE} as currently implemented invites grievous and difficult to\ntrack down errors. Avoid it and use an \"END{}\" or CORE::GLOBAL::die override\ninstead.\n\nSee \"die\" in perlfunc, \"warn\" in perlfunc, \"eval\" in perlfunc, and warnings for\nadditional information.\n\n%{^HOOK}\nThis hash contains coderefs which are called when various perl keywords which are\nhard or impossible to wrap are called. The keys of this hash are named after the\nkeyword that is being hooked, followed by two underbars and then a phase term; either\n\"before\" or \"after\".\n\nPerl will throw an error if you attempt modify a key which is not documented to\nexist, or if you attempt to store anything other than a code reference or undef in\nthe hash. If you wish to use an object to implement a hook you can use currying to\nembed the object into an anonymous code reference.\n\nCurrently there is only one keyword which can be hooked, \"require\", but it is\nexpected that in future releases there will be additional keywords with hook support.\n\nrequirebefore\nThe routine indicated by \"${^HOOK}{requirebefore}\" is called by \"require\"\nbefore it checks %INC, looks up @INC, calls INC hooks, or compiles any code. It\nis called with a single argument, the filename for the item being required\n(package names are converted to paths). It may alter this filename to change\nwhat file is loaded. If the hook dies during execution then it will block the\nrequire from executing.\n\nIn order to make it easy to perform an action with shared state both before and\nafter the require keyword was executed the \"requirebefore\" hook may return a\n\"post-action\" coderef which will in turn be executed when the \"require\"\ncompletes. This coderef will be executed regardless as to whether the require\ncompleted succesfully or threw an exception. It will be called with the filename\nthat was required. You can check %INC to determine if the require was\nsuccessful. Any other return from the \"requirebefore\" hook will be silently\nignored.\n\n\"requirebefore\" hooks are called in FIFO order, and if the hook returns a code\nreference those code references will be called in FILO order. In other words if\nA requires B requires C, then \"requirebefore\" will be called first for A, then\nB and then C, and the post-action code reference will executed first for C, then\nB and then finally A.\n\nWell behaved code should ensure that when setting up a \"requirebefore\" hook\nthat any prior installed hook will be called, and that their return value, if a\ncode reference, will be called as well. See \"require\" in perlfunc for an example\nimplementation.\n\nrequireafter\nThe routine indicated by \"${^HOOK}{requireafter}\" is called by \"require\" after\nthe require completes. It is called with a single argument, the filename for the\nitem being required (package names are converted to paths). It is executed when\nthe \"require\" completes, either via exception or via completion of the require\nstatement, and you can check %INC to determine if the require was successful.\n\nThe \"requireafter\" hook is called for each required file in FILO order. In\nother words if A requires B requires C, then \"requireafter\" will be called\nfirst for C, then B and then A.\n\n$BASETIME\n$^T The time at which the program began running, in seconds since the epoch (beginning of\n1970). The values returned by the -M, -A, and -C filetests are based on this value.\n\n$PERLVERSION\n$^V The revision, version, and subversion of the Perl interpreter, represented as a\nversion object.\n\nThis variable first appeared in perl v5.6.0; earlier versions of perl will see an\nundefined value. Before perl v5.10.0 $^V was represented as a v-string rather than a\nversion object.\n\n$^V can be used to determine whether the Perl interpreter executing a script is in\nthe right range of versions. For example:\n\nwarn \"Hashes not randomized!\\n\" if !$^V or $^V lt v5.8.1\n\nWhile version objects overload stringification, to portably convert $^V into its\nstring representation, use sprintf()'s \"%vd\" conversion, which works for both\nv-strings or version objects:\n\nprintf \"version is v%vd\\n\", $^V; # Perl's version\n\nSee the documentation of \"use VERSION\" and \"require VERSION\" for a convenient way to\nfail if the running Perl interpreter is too old.\n\nSee also \"$]\" for a decimal representation of the Perl version.\n\nThe main advantage of $^V over $] is that, for Perl v5.10.0 or later, it overloads\noperators, allowing easy comparison against other version representations (e.g.\ndecimal, literal v-string, \"v1.2.3\", or objects). The disadvantage is that prior to\nv5.10.0, it was only a literal v-string, which can't be easily printed or compared,\nwhereas the behavior of $] is unchanged on all versions of Perl.\n\nMnemonic: use ^V for a version object.\n\n$EXECUTABLENAME\n$^X The name used to execute the current copy of Perl, from C's \"argv[0]\" or (where\nsupported) /proc/self/exe.\n\nDepending on the host operating system, the value of $^X may be a relative or\nabsolute pathname of the perl program file, or may be the string used to invoke perl\nbut not the pathname of the perl program file. Also, most operating systems permit\ninvoking programs that are not in the PATH environment variable, so there is no\nguarantee that the value of $^X is in PATH. For VMS, the value may or may not\ninclude a version number.\n\nYou usually can use the value of $^X to re-invoke an independent copy of the same\nperl that is currently running, e.g.,\n\n@firstrun = `$^X -le \"print int rand 100 for 1..100\"`;\n\nBut recall that not all operating systems support forking or capturing of the output\nof commands, so this complex statement may not be portable.\n\nIt is not safe to use the value of $^X as a path name of a file, as some operating\nsystems that have a mandatory suffix on executable files do not require use of the\nsuffix when invoking a command. To convert the value of $^X to a path name, use the\nfollowing statements:\n\n# Build up a set of file names (not command names).\nuse Config;\nmy $thisperl = $^X;\nif ($^O ne 'VMS') {\n$thisperl .= $Config{exe}\nunless $thisperl =~ m/$Config{exe}$/i;\n}\n\nBecause many operating systems permit anyone with read access to the Perl program\nfile to make a copy of it, patch the copy, and then execute the copy, the security-\nconscious Perl programmer should take care to invoke the installed copy of perl, not\nthe copy referenced by $^X. The following statements accomplish this goal, and\nproduce a pathname that can be invoked as a command or referenced as a file.\n\nuse Config;\nmy $secureperlpath = $Config{perlpath};\nif ($^O ne 'VMS') {\n$secureperlpath .= $Config{exe}\nunless $secureperlpath =~ m/$Config{exe}$/i;\n}\n" }, { "name": "Variables related to regular expressions", "content": "Most of the special variables related to regular expressions are side effects. Perl sets\nthese variables when it has completed a match successfully, so you should check the match\nresult before using them. For instance:\n\nif( /P(A)TT(ER)N/ ) {\nprint \"I found $1 and $2\\n\";\n}\n\nThese variables are read-only and behave similarly to a dynamically scoped variable, with\nonly a few exceptions which are explicitly documented as behaving otherwise. See the\nfollowing section for more details.\n\nScoping Rules of Regex Variables\n\nRegular expression variables allow the programmer to access the state of the most recent\nsuccessful regex match in the current dynamic scope.\n\nThe variables themselves are global and unscoped, but the data they access is scoped\nsimilarly to dynamically scoped variables, in that every successful match behaves as though\nit localizes a global state object to the current block or file scope. (See \"Compound\nStatements\" in perlsyn for more details on dynamic scoping and the \"local\" keyword.)\n\nA successful match includes any successful match performed by the search and replace operator\n\"s///\" as well as those performed by the \"m//\" operator.\n\nConsider the following code:\n\nmy @state;\nsub matchit {\npush @state, $1; # pushes \"baz\"\nmy $str = shift;\n$str =~ /(zat)/; # matches \"zat\"\npush @state, $1; # pushes \"zat\"\n}\n\n{\n$str = \"foo bar baz blorp zat\";\n$str =~ /(foo)/; # matches \"foo\"\npush @state, $1; # pushes \"foo\"\n{\n$str =~ /(pizza)/; # does NOT match\npush @state, $1; # pushes \"foo\"\n$str =~ /(bar)/; # matches \"bar\"\npush @state, $1; # pushes \"bar\"\n$str =~ /(baz)/; # matches \"baz\"\nmatchit($str); # see above\npush @state, $1; # pushes \"baz\"\n}\n$str =~ s/noodles/rice/; # does NOT match\npush @state, $1; # pushes \"foo\"\n$str =~ s/(blorp)/zwoop/; # matches \"blorp\"\npush @state, $1; # pushes \"blorp\"\n}\n# the following prints \"foo, foo, bar, baz, zat, baz, foo, blorp\"\nprint join \",\", @state;\n\nNotice that each successful match in the exact same scope overrides the match context of the\nprevious successful match, but that unsuccessful matches do not. Also note that in an inner\nnested scope the previous state from an outer dynamic scope persists until it has been\noverriden by another successful match, but that when the inner nested scope exits whatever\nmatch context was in effect before the inner successful match is restored when the scope\nconcludes.\n\nIt is a known issue that \"goto LABEL\" may interact poorly with the dynamically scoped match\ncontext. This may not be fixable, and is considered to be one of many good reasons to avoid\n\"goto LABEL\".\n\nPerformance issues\n\nTraditionally in Perl, any use of any of the three variables \"$`\", $& or \"$'\" (or their \"use\nEnglish\" equivalents) anywhere in the code, caused all subsequent successful pattern matches\nto make a copy of the matched string, in case the code might subsequently access one of those\nvariables. This imposed a considerable performance penalty across the whole program, so\ngenerally the use of these variables has been discouraged.\n\nIn Perl 5.6.0 the \"@-\" and \"@+\" dynamic arrays were introduced that supply the indices of\nsuccessful matches. So you could for example do this:\n\n$str =~ /pattern/;\n\nprint $`, $&, $'; # bad: performance hit\n\nprint # good: no performance hit\nsubstr($str, 0, $-[0]),\nsubstr($str, $-[0], $+[0]-$-[0]),\nsubstr($str, $+[0]);\n\nIn Perl 5.10.0 the \"/p\" match operator flag and the \"${^PREMATCH}\", \"${^MATCH}\", and\n\"${^POSTMATCH}\" variables were introduced, that allowed you to suffer the penalties only on\npatterns marked with \"/p\".\n\nIn Perl 5.18.0 onwards, perl started noting the presence of each of the three variables\nseparately, and only copied that part of the string required; so in\n\n$`; $&; \"abcdefgh\" =~ /d/\n\nperl would only copy the \"abcd\" part of the string. That could make a big difference in\nsomething like\n\n$str = 'x' x 1000000;\n$&; # whoops\n$str =~ /x/g # one char copied a million times, not a million chars\n\nIn Perl 5.20.0 a new copy-on-write system was enabled by default, which finally fixes most of\nthe performance issues with these three variables, and makes them safe to use anywhere.\n\nThe \"Devel::NYTProf\" and \"Devel::FindAmpersand\" modules can help you find uses of these\nproblematic match variables in your code.\n\n$ ($1, $2, ...)\nContains the subpattern from the corresponding set of capturing parentheses from the\nlast successful pattern match in the current dynamic scope. (See \"Scoping Rules of\nRegex Variables\".)\n\nNote there is a distinction between a capture buffer which matches the empty string a\ncapture buffer which is optional. Eg, \"(x?)\" and \"(x)?\" The latter may be undef, the\nformer not.\n\nThese variables are read-only.\n\nMnemonic: like \\digits.\n\n@{^CAPTURE}\nAn array which exposes the contents of the capture buffers, if any, of the last\nsuccessful pattern match, not counting patterns matched in nested blocks that have\nbeen exited already.\n\nNote that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index is equivalent\nto $2, etc.\n\nif (\"foal\"=~/(.)(.)(.)(.)/) {\nprint join \"-\", @{^CAPTURE};\n}\n\nshould output \"f-o-a-l\".\n\nSee also \"$ ($1, $2, ...)\", \"%{^CAPTURE}\" and \"%{^CAPTUREALL}\".\n\nNote that unlike most other regex magic variables there is no single letter\nequivalent to \"@{^CAPTURE}\". Also be aware that when interpolating subscripts of this\narray you must use the demarcated variable form, for instance\n\nprint \"${^CAPTURE[0]}\"\n\nsee \"Demarcated variable names using braces\" in perldata for more information on this\nform and its uses.\n\nThis variable was added in 5.25.7\n\n$MATCH\n$& The string matched by the last successful pattern match. (See \"Scoping Rules of\nRegex Variables\".)\n\nSee \"Performance issues\" above for the serious performance implications of using this\nvariable (even once) in your code.\n\nThis variable is read-only, and its value is dynamically scoped.\n\nMnemonic: like \"&\" in some editors.\n\n${^MATCH}\nIt is only guaranteed to return a defined value when the pattern was compiled or\nexecuted with the \"/p\" modifier.\n\nThis is similar to $& ($MATCH) except that to use it you must use the \"/p\" modifier\nwhen executing the pattern, and it does not incur and performance penalty associated\nwith that variable.\n\nSee \"Performance issues\" above.\n\nThis variable was added in Perl v5.10.0.\n\nThis variable is read-only, and its value is dynamically scoped.\n\n$PREMATCH\n$` The string preceding whatever was matched by the last successful pattern match. (See\n\"Scoping Rules of Regex Variables\").\n\nSee \"Performance issues\" above for the serious performance implications of using this\nvariable (even once) in your code.\n\nThis variable is read-only, and its value is dynamically scoped.\n\nMnemonic: \"`\" often precedes a quoted string.\n\n${^PREMATCH}\nIt is only guaranteed to return a defined value when the pattern was executed with\nthe \"/p\" modifier.\n\nThis is similar to \"$`\" ($PREMATCH) except that to use it you must use the \"/p\"\nmodifier when executing the pattern, and it does not incur and performance penalty\nassociated with that variable.\n\nSee \"Performance issues\" above.\n\nThis variable was added in Perl v5.10.0.\n\nThis variable is read-only, and its value is dynamically scoped.\n\n$POSTMATCH\n$' The string following whatever was matched by the last successful pattern match. (See\n\"Scoping Rules of Regex Variables\"). Example:\n\nlocal $ = 'abcdefghi';\n/def/;\nprint \"$`:$&:$'\\n\"; # prints abc:def:ghi\n\nSee \"Performance issues\" above for the serious performance implications of using this\nvariable (even once) in your code.\n\nThis variable is read-only, and its value is dynamically scoped.\n\nMnemonic: \"'\" often follows a quoted string.\n\n${^POSTMATCH}\nIt is only guaranteed to return a defined value when the pattern was compiled or\nexecuted with the \"/p\" modifier.\n\nThis is similar to \"$'\" ($POSTMATCH) except that to use it you must use the \"/p\"\nmodifier when executing the pattern, and it does not incur and performance penalty\nassociated with that variable.\n\nSee \"Performance issues\" above.\n\nThis variable was added in Perl v5.10.0.\n\nThis variable is read-only, and its value is dynamically scoped.\n\n$LASTPARENMATCH\n$+ The text matched by the highest used capture group of the last successful search\npattern. (See \"Scoping Rules of Regex Variables\"). It is logically equivalent to the\nhighest numbered capture variable ($1, $2, ...) which has a defined value.\n\nThis is useful if you don't know which one of a set of alternative patterns matched.\nFor example:\n\n/Version: (.*)|Revision: (.*)/ && ($rev = $+);\n\nThis variable is read-only, and its value is dynamically scoped.\n\nMnemonic: be positive and forward looking.\n\n$LASTSUBMATCHRESULT\n$^N The text matched by the used group most-recently closed (i.e. the group with the\nrightmost closing parenthesis) of the last successful match. (See \"Scoping Rules of\nRegex Variables\").\n\nThis is subtly different from $+. For example in\n\n\"ab\" =~ /^((.)(.))$/\n\nwe have\n\n$1,$^N have the value \"ab\"\n$2 has the value \"a\"\n$3,$+ have the value \"b\"\n\nThis is primarily used inside \"(?{...})\" blocks for examining text recently matched.\nFor example, to effectively capture text to a variable (in addition to $1, $2, etc.),\nreplace \"(...)\" with\n\n(?:(...)(?{ $var = $^N }))\n\nBy setting and then using $var in this way relieves you from having to worry about\nexactly which numbered set of parentheses they are.\n\nThis variable is read-only, and its value is dynamically scoped.\n\nThis variable was added in Perl v5.8.0.\n\nMnemonic: the (possibly) Nested parenthesis that most recently closed.\n\n@LASTMATCHEND\n@+ This array holds the offsets of the ends of the last successful match and any\nmatching capture buffers that the pattern contains. (See \"Scoping Rules of Regex\nVariables\")\n\nThe number of elements it contains will be one more than the number of capture\nbuffers in the pattern, regardless of which capture buffers actually matched. You can\nuse this to determine how many capture buffers there are in the pattern. (As opposed\nto \"@-\" which may have fewer elements.)\n\n$+[0] is the offset into the string of the end of the entire match. This is the same\nvalue as what the \"pos\" function returns when called on the variable that was matched\nagainst. The nth element of this array holds the offset of the nth submatch, so $+[1]\nis the offset past where $1 ends, $+[2] the offset past where $2 ends, and so on. You\ncan use $#+ to determine how many subgroups were in the last successful match. See\nthe examples given for the \"@-\" variable.\n\nThis variable is read-only, and its value is dynamically scoped.\n\nThis variable was added in Perl v5.6.0.\n\n%{^CAPTURE}\n%LASTPARENMATCH\n%+ Similar to \"@+\", the \"%+\" hash allows access to the named capture buffers, should\nthey exist, in the last successful match in the currently active dynamic scope. (See\n\"Scoping Rules of Regex Variables\").\n\nFor example, $+{foo} is equivalent to $1 after the following match:\n\n'foo' =~ /(?foo)/;\n\nThe keys of the \"%+\" hash list only the names of buffers that have captured (and that\nare thus associated to defined values).\n\nIf multiple distinct capture groups have the same name, then $+{NAME} will refer to\nthe leftmost defined group in the match.\n\nThe underlying behaviour of \"%+\" is provided by the Tie::Hash::NamedCapture module.\n\nNote: \"%-\" and \"%+\" are tied views into a common internal hash associated with the\nlast successful regular expression. Therefore mixing iterative access to them via\n\"each\" may have unpredictable results. Likewise, if the last successful match\nchanges, then the results may be surprising.\n\nThis variable was added in Perl v5.10.0. The \"%{^CAPTURE}\" alias was added in 5.25.7.\n\nThis variable is read-only, and its value is dynamically scoped.\n\n@LASTMATCHSTART\n@- This array holds the offsets of the beginnings of the last successful match and any\ncapture buffers it contains. (See \"Scoping Rules of Regex Variables\").\n\nThe number of elements it contains will be one more than the number of the highest\ncapture buffers (also called a subgroup) that actually matched something. (As opposed\nto \"@+\" which may have fewer elements.)\n\n\"$-[0]\" is the offset of the start of the last successful match. \"$-[n]\" is the\noffset of the start of the substring matched by n-th subpattern, or undef if the\nsubpattern did not match.\n\nThus, after a match against $, $& coincides with \"substr $, $-[0], $+[0] - $-[0]\".\nSimilarly, \"$n\" coincides with \"substr $, $-[n], $+[n] - $-[n]\" if \"$-[n]\" is\ndefined, and $+ coincides with \"substr $, $-[$#-], $+[$#-] - $-[$#-]\". One can use\n\"$#-\" to find the last matched subgroup in the last successful match. Contrast with\n$#+, the number of subgroups in the regular expression.\n\n\"$-[0]\" is the offset into the string of the beginning of the entire match. The nth\nelement of this array holds the offset of the nth submatch, so \"$-[1]\" is the offset\nwhere $1 begins, \"$-[2]\" the offset where $2 begins, and so on.\n\nAfter a match against some variable $var:\n\n\"$`\" is the same as \"substr($var, 0, $-[0])\"\n$& is the same as \"substr($var, $-[0], $+[0] - $-[0])\"\n\"$'\" is the same as \"substr($var, $+[0])\"\n$1 is the same as \"substr($var, $-[1], $+[1] - $-[1])\"\n$2 is the same as \"substr($var, $-[2], $+[2] - $-[2])\"\n$3 is the same as \"substr($var, $-[3], $+[3] - $-[3])\"\n\nThis variable is read-only, and its value is dynamically scoped.\n\nThis variable was added in Perl v5.6.0.\n\n%{^CAPTUREALL}\n%- Similar to \"%+\", this variable allows access to the named capture groups in the last\nsuccessful match in the currently active dynamic scope. (See \"Scoping Rules of Regex\nVariables\"). To each capture group name found in the regular expression, it\nassociates a reference to an array containing the list of values captured by all\nbuffers with that name (should there be several of them), in the order where they\nappear.\n\nHere's an example:\n\nif ('1234' =~ /(?1)(?2)(?3)(?4)/) {\nforeach my $bufname (sort keys %-) {\nmy $ary = $-{$bufname};\nforeach my $idx (0..$#$ary) {\nprint \"\\$-{$bufname}[$idx] : \",\n(defined($ary->[$idx])\n? \"'$ary->[$idx]'\"\n: \"undef\"),\n\"\\n\";\n}\n}\n}\n\nwould print out:\n\n$-{A}[0] : '1'\n$-{A}[1] : '3'\n$-{B}[0] : '2'\n$-{B}[1] : '4'\n\nThe keys of the \"%-\" hash correspond to all buffer names found in the regular\nexpression.\n\nThe behaviour of \"%-\" is implemented via the Tie::Hash::NamedCapture module.\n\nNote: \"%-\" and \"%+\" are tied views into a common internal hash associated with the\nlast successful regular expression. Therefore mixing iterative access to them via\n\"each\" may have unpredictable results. Likewise, if the last successful match\nchanges, then the results may be surprising. See \"Scoping Rules of Regex Variables\".\n\nThis variable was added in Perl v5.10.0. The \"%{^CAPTUREALL}\" alias was added in\n5.25.7.\n\nThis variable is read-only, and its value is dynamically scoped.\n\n${^LASTSUCCESSFULPATTERN}\nThe last successful pattern that matched in the current scope. The empty pattern\ndefaults to matching to this. For instance:\n\nif (m/foo/ || m/bar/) {\ns//BLAH/;\n}\n\nand\n\nif (m/foo/ || m/bar/) {\ns/${^LASTSUCCESSFULPATTERN}/BLAH/;\n}\n\nare equivalent.\n\nYou can use this to debug which pattern matched last, or to match with it again.\n\nAdded in Perl 5.37.10.\n\n$LASTREGEXPCODERESULT\n$^R The result of evaluation of the last successful \"(?{ code })\" regular expression\nassertion (see perlre).\n\nThis variable may be written to, and its value is scoped normally, unlike most other\nregex variables.\n\nThis variable was added in Perl 5.005.\n\n${^RECOMPILERECURSIONLIMIT}\nThe current value giving the maximum number of open but unclosed parenthetical groups\nthere may be at any point during a regular expression compilation. The default is\ncurrently 1000 nested groups. You may adjust it depending on your needs and the\namount of memory available.\n\nThis variable was added in Perl v5.30.0.\n\n${^REDEBUGFLAGS}\nThe current value of the regex debugging flags. Set to 0 for no debug output even\nwhen the \"re 'debug'\" module is loaded. See re for details.\n\nThis variable was added in Perl v5.10.0.\n\n${^RETRIEMAXBUF}\nControls how certain regex optimisations are applied and how much memory they\nutilize. This value by default is 65536 which corresponds to a 512kB temporary\ncache. Set this to a higher value to trade memory for speed when matching large\nalternations. Set it to a lower value if you want the optimisations to be as\nconservative of memory as possible but still occur, and set it to a negative value to\nprevent the optimisation and conserve the most memory. Under normal situations this\nvariable should be of no interest to you.\n\nThis variable was added in Perl v5.10.0.\n" }, { "name": "Variables related to filehandles", "content": "Variables that depend on the currently selected filehandle may be set by calling an\nappropriate object method on the \"IO::Handle\" object, although this is less efficient than\nusing the regular built-in variables. (Summary lines below for this contain the word\nHANDLE.) First you must say\n\nuse IO::Handle;\n\nafter which you may use either\n\nmethod HANDLE EXPR\n\nor more safely,\n\nHANDLE->method(EXPR)\n\nEach method returns the old value of the \"IO::Handle\" attribute. The methods each take an\noptional EXPR, which, if supplied, specifies the new value for the \"IO::Handle\" attribute in\nquestion. If not supplied, most methods do nothing to the current value--except for\nautoflush(), which will assume a 1 for you, just to be different.\n\nBecause loading in the \"IO::Handle\" class is an expensive operation, you should learn how to\nuse the regular built-in variables.\n\nA few of these variables are considered \"read-only\". This means that if you try to assign to\nthis variable, either directly or indirectly through a reference, you'll raise a run-time\nexception.\n\nYou should be very careful when modifying the default values of most special variables\ndescribed in this document. In most cases you want to localize these variables before\nchanging them, since if you don't, the change may affect other modules which rely on the\ndefault values of the special variables that you have changed. This is one of the correct\nways to read the whole file at once:\n\nopen my $fh, \"<\", \"foo\" or die $!;\nlocal $/; # enable localized slurp mode\nmy $content = <$fh>;\nclose $fh;\n\nBut the following code is quite bad:\n\nopen my $fh, \"<\", \"foo\" or die $!;\nundef $/; # enable slurp mode\nmy $content = <$fh>;\nclose $fh;\n\nsince some other module, may want to read data from some file in the default \"line mode\", so\nif the code we have just presented has been executed, the global value of $/ is now changed\nfor any other code running inside the same Perl interpreter.\n\nUsually when a variable is localized you want to make sure that this change affects the\nshortest scope possible. So unless you are already inside some short \"{}\" block, you should\ncreate one yourself. For example:\n\nmy $content = '';\nopen my $fh, \"<\", \"foo\" or die $!;\n{\nlocal $/;\n$content = <$fh>;\n}\nclose $fh;\n\nHere is an example of how your own code can go broken:\n\nfor ( 1..3 ){\n$\\ = \"\\r\\n\";\nnastybreak();\nprint \"$\";\n}\n\nsub nastybreak {\n$\\ = \"\\f\";\n# do something with $\n}\n\nYou probably expect this code to print the equivalent of\n\n\"1\\r\\n2\\r\\n3\\r\\n\"\n\nbut instead you get:\n\n\"1\\f2\\f3\\f\"\n\nWhy? Because nastybreak() modifies \"$\\\" without localizing it first. The value you set in\nnastybreak() is still there when you return. The fix is to add local() so the value doesn't\nleak out of nastybreak():\n\nlocal $\\ = \"\\f\";\n\nIt's easy to notice the problem in such a short example, but in more complicated code you are\nlooking for trouble if you don't localize changes to the special variables.\n\n$ARGV Contains the name of the current file when reading from \"<>\".\n\n@ARGV The array @ARGV contains the command-line arguments intended for the script. $#ARGV\nis generally the number of arguments minus one, because $ARGV[0] is the first\nargument, not the program's command name itself. See \"$0\" for the command name.\n\nARGV The special filehandle that iterates over command-line filenames in @ARGV. Usually\nwritten as the null filehandle in the angle operator \"<>\". Note that currently\n\"ARGV\" only has its magical effect within the \"<>\" operator; elsewhere it is just a\nplain filehandle corresponding to the last file opened by \"<>\". In particular,\npassing \"\\*ARGV\" as a parameter to a function that expects a filehandle may not cause\nyour function to automatically read the contents of all the files in @ARGV.\n\nARGVOUT The special filehandle that points to the currently open output file when doing edit-\nin-place processing with -i. Useful when you have to do a lot of inserting and don't\nwant to keep modifying $. See perlrun for the -i switch.\n\nIO::Handle->outputfieldseparator( EXPR )\n$OUTPUTFIELDSEPARATOR\n$OFS\n$, The output field separator for the print operator. If defined, this value is printed\nbetween each of print's arguments. Default is \"undef\".\n\nYou cannot call outputfieldseparator() on a handle, only as a static method. See\nIO::Handle.\n\nMnemonic: what is printed when there is a \",\" in your print statement.\n\nHANDLE->inputlinenumber( EXPR )\n$INPUTLINENUMBER\n$NR\n$. Current line number for the last filehandle accessed.\n\nEach filehandle in Perl counts the number of lines that have been read from it.\n(Depending on the value of $/, Perl's idea of what constitutes a line may not match\nyours.) When a line is read from a filehandle (via readline() or \"<>\"), or when\ntell() or seek() is called on it, $. becomes an alias to the line counter for that\nfilehandle.\n\nYou can adjust the counter by assigning to $., but this will not actually move the\nseek pointer. Localizing $. will not localize the filehandle's line count. Instead,\nit will localize perl's notion of which filehandle $. is currently aliased to.\n\n$. is reset when the filehandle is closed, but not when an open filehandle is\nreopened without an intervening close(). For more details, see \"I/O Operators\" in\nperlop. Because \"<>\" never does an explicit close, line numbers increase across\n\"ARGV\" files (but see examples in \"eof\" in perlfunc).\n\nYou can also use \"HANDLE->inputlinenumber(EXPR)\" to access the line counter for a\ngiven filehandle without having to worry about which handle you last accessed.\n\nMnemonic: many programs use \".\" to mean the current line number.\n\nIO::Handle->inputrecordseparator( EXPR )\n$INPUTRECORDSEPARATOR\n$RS\n$/ The input record separator, newline by default. This influences Perl's idea of what\na \"line\" is. Works like awk's RS variable, including treating empty lines as a\nterminator if set to the null string (an empty line cannot contain any spaces or\ntabs). You may set it to a multi-character string to match a multi-character\nterminator, or to \"undef\" to read through the end of file. Setting it to \"\\n\\n\"\nmeans something slightly different than setting to \"\", if the file contains\nconsecutive empty lines. Setting to \"\" will treat two or more consecutive empty\nlines as a single empty line. Setting to \"\\n\\n\" will blindly assume that the next\ninput character belongs to the next paragraph, even if it's a newline.\n\nlocal $/; # enable \"slurp\" mode\nlocal $ = ; # whole file now here\ns/\\n[ \\t]+/ /g;\n\nRemember: the value of $/ is a string, not a regex. awk has to be better for\nsomething. :-)\n\nSetting $/ to an empty string -- the so-called paragraph mode -- merits special\nattention. When $/ is set to \"\" and the entire file is read in with that setting,\nany sequence of one or more consecutive newlines at the beginning of the file is\ndiscarded. With the exception of the final record in the file, each sequence of\ncharacters ending in two or more newlines is treated as one record and is read in to\nend in exactly two newlines. If the last record in the file ends in zero or one\nconsecutive newlines, that record is read in with that number of newlines. If the\nlast record ends in two or more consecutive newlines, it is read in with two newlines\nlike all preceding records.\n\nSuppose we wrote the following string to a file:\n\nmy $string = \"\\n\\n\\n\";\n$string .= \"alpha beta\\ngamma delta\\n\\n\\n\";\n$string .= \"epsilon zeta eta\\n\\n\";\n$string .= \"theta\\n\";\n\nmy $file = 'simplefile.txt';\nopen my $OUT, '>', $file or die;\nprint $OUT $string;\nclose $OUT or die;\n\nNow we read that file in paragraph mode:\n\nlocal $/ = \"\"; # paragraph mode\nopen my $IN, '<', $file or die;\nmy @records = <$IN>;\nclose $IN or die;\n\n@records will consist of these 3 strings:\n\n(\n\"alpha beta\\ngamma delta\\n\\n\",\n\"epsilon zeta eta\\n\\n\",\n\"theta\\n\",\n)\n\nSetting $/ to a reference to an integer, scalar containing an integer, or scalar\nthat's convertible to an integer will attempt to read records instead of lines, with\nthe maximum record size being the referenced integer number of characters. So this:\n\nlocal $/ = \\32768; # or \\\"32768\", or \\$varcontaining32768\nopen my $fh, \"<\", $myfile or die $!;\nlocal $ = <$fh>;\n\nwill read a record of no more than 32768 characters from $fh. If you're not reading\nfrom a record-oriented file (or your OS doesn't have record-oriented files), then\nyou'll likely get a full chunk of data with every read. If a record is larger than\nthe record size you've set, you'll get the record back in pieces. Trying to set the\nrecord size to zero or less is deprecated and will cause $/ to have the value of\n\"undef\", which will cause reading in the (rest of the) whole file.\n\nAs of 5.19.9 setting $/ to any other form of reference will throw a fatal exception.\nThis is in preparation for supporting new ways to set $/ in the future.\n\nOn VMS only, record reads bypass PerlIO layers and any associated buffering, so you\nmust not mix record and non-record reads on the same filehandle. Record mode mixes\nwith line mode only when the same buffering layer is in use for both modes.\n\nYou cannot call inputrecordseparator() on a handle, only as a static method. See\nIO::Handle.\n\nSee also \"Newlines\" in perlport. Also see \"$.\".\n\nMnemonic: / delimits line boundaries when quoting poetry.\n\nIO::Handle->outputrecordseparator( EXPR )\n$OUTPUTRECORDSEPARATOR\n$ORS\n$\\ The output record separator for the print operator. If defined, this value is\nprinted after the last of print's arguments. Default is \"undef\".\n\nYou cannot call outputrecordseparator() on a handle, only as a static method. See\nIO::Handle.\n\nMnemonic: you set \"$\\\" instead of adding \"\\n\" at the end of the print. Also, it's\njust like $/, but it's what you get \"back\" from Perl.\n\nHANDLE->autoflush( EXPR )\n$OUTPUTAUTOFLUSH\n$| If set to nonzero, forces a flush right away and after every write or print on the\ncurrently selected output channel. Default is 0 (regardless of whether the channel\nis really buffered by the system or not; $| tells you only whether you've asked Perl\nexplicitly to flush after each write). STDOUT will typically be line buffered if\noutput is to the terminal and block buffered otherwise. Setting this variable is\nuseful primarily when you are outputting to a pipe or socket, such as when you are\nrunning a Perl program under rsh and want to see the output as it's happening. This\nhas no effect on input buffering. See \"getc\" in perlfunc for that. See \"select\" in\nperlfunc on how to select the output channel. See also IO::Handle.\n\nMnemonic: when you want your pipes to be piping hot.\n\n${^LASTFH}\nThis read-only variable contains a reference to the last-read filehandle. This is\nset by \"\", \"readline\", \"tell\", \"eof\" and \"seek\". This is the same handle\nthat $. and \"tell\" and \"eof\" without arguments use. It is also the handle used when\nPerl appends \", line 1\" to an error or warning message.\n\nThis variable was added in Perl v5.18.0.\n\nVariables related to formats\n\nThe special variables for formats are a subset of those for filehandles. See perlform for\nmore information about Perl's formats.\n\n$ACCUMULATOR\n$^A The current value of the write() accumulator for format() lines. A format contains\nformline() calls that put their result into $^A. After calling its format, write()\nprints out the contents of $^A and empties. So you never really see the contents of\n$^A unless you call formline() yourself and then look at it. See perlform and\n\"formline PICTURE,LIST\" in perlfunc.\n\nIO::Handle->formatformfeed(EXPR)\n$FORMATFORMFEED\n$^L What formats output as a form feed. The default is \"\\f\".\n\nYou cannot call formatformfeed() on a handle, only as a static method. See\nIO::Handle.\n\nHANDLE->formatpagenumber(EXPR)\n$FORMATPAGENUMBER\n$% The current page number of the currently selected output channel.\n\nMnemonic: \"%\" is page number in nroff.\n\nHANDLE->formatlinesleft(EXPR)\n$FORMATLINESLEFT\n$- The number of lines left on the page of the currently selected output channel.\n\nMnemonic: linesonpage - linesprinted.\n\nIO::Handle->formatlinebreakcharacters EXPR\n$FORMATLINEBREAKCHARACTERS\n$: The current set of characters after which a string may be broken to fill continuation\nfields (starting with \"^\") in a format. The default is \" \\n-\", to break on a space,\nnewline, or a hyphen.\n\nYou cannot call formatlinebreakcharacters() on a handle, only as a static method.\nSee IO::Handle.\n\nMnemonic: a \"colon\" in poetry is a part of a line.\n\nHANDLE->formatlinesperpage(EXPR)\n$FORMATLINESPERPAGE\n$= The current page length (printable lines) of the currently selected output channel.\nThe default is 60.\n\nMnemonic: = has horizontal lines.\n\nHANDLE->formattopname(EXPR)\n$FORMATTOPNAME\n$^ The name of the current top-of-page format for the currently selected output channel.\nThe default is the name of the filehandle with \"TOP\" appended. For example, the\ndefault format top name for the \"STDOUT\" filehandle is \"STDOUTTOP\".\n\nMnemonic: points to top of page.\n\nHANDLE->formatname(EXPR)\n$FORMATNAME\n$~ The name of the current report format for the currently selected output channel. The\ndefault format name is the same as the filehandle name. For example, the default\nformat name for the \"STDOUT\" filehandle is just \"STDOUT\".\n\nMnemonic: brother to $^.\n" }, { "name": "Error Variables", "content": "The variables $@, $!, $^E, and $? contain information about different types of error\nconditions that may appear during execution of a Perl program. The variables are shown\nordered by the \"distance\" between the subsystem which reported the error and the Perl\nprocess. They correspond to errors detected by the Perl interpreter, C library, operating\nsystem, or an external program, respectively.\n\nTo illustrate the differences between these variables, consider the following Perl\nexpression, which uses a single-quoted string. After execution of this statement, perl may\nhave set all four special error variables:\n\neval q{\nopen my $pipe, \"/cdrom/install |\" or die $!;\nmy @res = <$pipe>;\nclose $pipe or die \"bad pipe: $?, $!\";\n};\n\nWhen perl executes the eval() expression, it translates the open(), \"\", and \"close\"\ncalls in the C run-time library and thence to the operating system kernel. perl sets $! to\nthe C library's \"errno\" if one of these calls fails.\n\n$@ is set if the string to be \"eval\"-ed did not compile (this may happen if \"open\" or \"close\"\nwere imported with bad prototypes), or if Perl code executed during evaluation die()d. In\nthese cases the value of $@ is the compile error, or the argument to \"die\" (which will\ninterpolate $! and $?). (See also Fatal, though.)\n\nUnder a few operating systems, $^E may contain a more verbose error indicator, such as in\nthis case, \"CDROM tray not closed.\" Systems that do not support extended error messages\nleave $^E the same as $!.\n\nFinally, $? may be set to a non-0 value if the external program /cdrom/install fails. The\nupper eight bits reflect specific error conditions encountered by the program (the program's\nexit() value). The lower eight bits reflect mode of failure, like signal death and core dump\ninformation. See wait(2) for details. In contrast to $! and $^E, which are set only if an\nerror condition is detected, the variable $? is set on each \"wait\" or pipe \"close\",\noverwriting the old value. This is more like $@, which on every eval() is always set on\nfailure and cleared on success.\n\nFor more details, see the individual descriptions at $@, $!, $^E, and $?.\n\n${^CHILDERRORNATIVE}\nThe native status returned by the last pipe close, backtick (``) command, successful\ncall to wait() or waitpid(), or from the system() operator. On POSIX-like systems\nthis value can be decoded with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG,\nWIFSTOPPED, and WSTOPSIG functions provided by the POSIX module.\n\nUnder VMS this reflects the actual VMS exit status; i.e. it is the same as $? when\nthe pragma \"use vmsish 'status'\" is in effect.\n\nThis variable was added in Perl v5.10.0.\n\n$EXTENDEDOSERROR\n$^E Error information specific to the current operating system. At the moment, this\ndiffers from \"$!\" under only VMS, OS/2, and Win32 (and for MacPerl). On all other\nplatforms, $^E is always just the same as $!.\n\nUnder VMS, $^E provides the VMS status value from the last system error. This is\nmore specific information about the last system error than that provided by $!. This\nis particularly important when $! is set to EVMSERR.\n\nUnder OS/2, $^E is set to the error code of the last call to OS/2 API either via CRT,\nor directly from perl.\n\nUnder Win32, $^E always returns the last error information reported by the Win32 call\nGetLastError() which describes the last error from within the Win32 API. Most\nWin32-specific code will report errors via $^E. ANSI C and Unix-like calls set\n\"errno\" and so most portable Perl code will report errors via $!.\n\nCaveats mentioned in the description of \"$!\" generally apply to $^E, also.\n\nThis variable was added in Perl 5.003.\n\nMnemonic: Extra error explanation.\n\n$EXCEPTIONSBEINGCAUGHT\n$^S Current state of the interpreter.\n\n$^S State\n--------- -------------------------------------\nundef Parsing module, eval, or main program\ntrue (1) Executing an eval or try block\nfalse (0) Otherwise\n\nThe first state may happen in $SIG{DIE} and $SIG{WARN} handlers.\n\nThe English name $EXCEPTIONSBEINGCAUGHT is slightly misleading, because the \"undef\"\nvalue does not indicate whether exceptions are being caught, since compilation of the\nmain program does not catch exceptions.\n\nThis variable was added in Perl 5.004.\n\n$WARNING\n$^W The current value of the warning switch, initially true if -w was used, false\notherwise, but directly modifiable.\n\nSee also warnings.\n\nMnemonic: related to the -w switch.\n\n${^WARNINGBITS}\nThe current set of warning checks enabled by the \"use warnings\" pragma. It has the\nsame scoping as the $^H and \"%^H\" variables. The exact values are considered\ninternal to the warnings pragma and may change between versions of Perl.\n\nEach time a statement completes being compiled, the current value of\n\"${^WARNINGBITS}\" is stored with that statement, and can later be retrieved via\n\"(caller($level))[9]\".\n\nThis variable was added in Perl v5.6.0.\n\n$OSERROR\n$ERRNO\n$! When referenced, $! retrieves the current value of the C \"errno\" integer variable.\nIf $! is assigned a numerical value, that value is stored in \"errno\". When\nreferenced as a string, $! yields the system error string corresponding to \"errno\".\n\nMany system or library calls set \"errno\" if they fail, to indicate the cause of\nfailure. They usually do not set \"errno\" to zero if they succeed and may set \"errno\"\nto a non-zero value on success. This means \"errno\", hence $!, is meaningful only\nimmediately after a failure:\n\nif (open my $fh, \"<\", $filename) {\n# Here $! is meaningless.\n...\n}\nelse {\n# ONLY here is $! meaningful.\n...\n# Already here $! might be meaningless.\n}\n# Since here we might have either success or failure,\n# $! is meaningless.\n\nHere, meaningless means that $! may be unrelated to the outcome of the open()\noperator. Assignment to $! is similarly ephemeral. It can be used immediately\nbefore invoking the die() operator, to set the exit value, or to inspect the system\nerror string corresponding to error n, or to restore $! to a meaningful state.\n\nPerl itself may set \"errno\" to a non-zero on failure even if no system call is\nperformed.\n\nMnemonic: What just went bang?\n\n%OSERROR\n%ERRNO\n%! Each element of \"%!\" has a true value only if $! is set to that value. For example,\n$!{ENOENT} is true if and only if the current value of $! is \"ENOENT\"; that is, if\nthe most recent error was \"No such file or directory\" (or its moral equivalent: not\nall operating systems give that exact error, and certainly not all languages). The\nspecific true value is not guaranteed, but in the past has generally been the numeric\nvalue of $!. To check if a particular key is meaningful on your system, use \"exists\n$!{thekey}\"; for a list of legal keys, use \"keys %!\". See Errno for more\ninformation, and also see \"$!\".\n\nThis variable was added in Perl 5.005.\n\n$CHILDERROR\n$? The status returned by the last pipe close, backtick (``) command, successful call to\nwait() or waitpid(), or from the system() operator. This is just the 16-bit status\nword returned by the traditional Unix wait() system call (or else is made up to look\nlike it). Thus, the exit value of the subprocess is really ($? >> 8), and \"$? & 127\"\ngives which signal, if any, the process died from, and \"$? & 128\" reports whether\nthere was a core dump.\n\nAdditionally, if the \"herrno\" variable is supported in C, its value is returned via\n$? if any \"gethost*()\" function fails.\n\nIf you have installed a signal handler for \"SIGCHLD\", the value of $? will usually be\nwrong outside that handler.\n\nInside an \"END\" subroutine $? contains the value that is going to be given to exit().\nYou can modify $? in an \"END\" subroutine to change the exit status of your program.\nFor example:\n\nEND {\n$? = 1 if $? == 255; # die would make it 255\n}\n\nUnder VMS, the pragma \"use vmsish 'status'\" makes $? reflect the actual VMS exit\nstatus, instead of the default emulation of POSIX status; see \"$?\" in perlvms for\ndetails.\n\nMnemonic: similar to sh and ksh.\n\n$EVALERROR\n$@ The Perl error from the last \"eval\" operator, i.e. the last exception that was\ncaught. For \"eval BLOCK\", this is either a runtime error message or the string or\nreference \"die\" was called with. The \"eval STRING\" form also catches syntax errors\nand other compile time exceptions.\n\nIf no error occurs, \"eval\" sets $@ to the empty string.\n\nWarning messages are not collected in this variable. You can, however, set up a\nroutine to process warnings by setting $SIG{WARN} as described in \"%SIG\".\n\nMnemonic: Where was the error \"at\"?\n" }, { "name": "Variables related to the interpreter state", "content": "These variables provide information about the current interpreter state.\n\n$COMPILING\n$^C The current value of the flag associated with the -c switch. Mainly of use with\n-MO=... to allow code to alter its behavior when being compiled, such as for example\nto \"AUTOLOAD\" at compile time rather than normal, deferred loading. Setting \"$^C =\n1\" is similar to calling \"B::minusc\".\n\nThis variable was added in Perl v5.6.0.\n\n$DEBUGGING\n$^D The current value of the debugging flags. May be read or set. Like its command-line\nequivalent, you can use numeric or symbolic values, e.g. \"$^D = 10\" or \"$^D = \"st\"\".\nSee \"-Dnumber\" in perlrun. The contents of this variable also affects the debugger\noperation. See \"Debugger Internals\" in perldebguts.\n\nMnemonic: value of -D switch.\n\n${^GLOBALPHASE}\nThe current phase of the perl interpreter.\n\nPossible values are:\n\nCONSTRUCT\nThe \"PerlInterpreter*\" is being constructed via \"perlconstruct\". This value\nis mostly there for completeness and for use via the underlying C variable\n\"PLphase\". It's not really possible for Perl code to be executed unless\nconstruction of the interpreter is finished.\n\nSTART This is the global compile-time. That includes, basically, every \"BEGIN\"\nblock executed directly or indirectly from during the compile-time of the\ntop-level program.\n\nThis phase is not called \"BEGIN\" to avoid confusion with \"BEGIN\"-blocks, as\nthose are executed during compile-time of any compilation unit, not just the\ntop-level program. A new, localised compile-time entered at run-time, for\nexample by constructs as \"eval \"use SomeModule\"\" are not global interpreter\nphases, and therefore aren't reflected by \"${^GLOBALPHASE}\".\n\nCHECK Execution of any \"CHECK\" blocks.\n\nINIT Similar to \"CHECK\", but for \"INIT\"-blocks, not \"CHECK\" blocks.\n\nRUN The main run-time, i.e. the execution of \"PLmainroot\".\n\nEND Execution of any \"END\" blocks.\n\nDESTRUCT\nGlobal destruction.\n\nAlso note that there's no value for UNITCHECK-blocks. That's because those are run\nfor each compilation unit individually, and therefore is not a global interpreter\nphase.\n\nNot every program has to go through each of the possible phases, but transition from\none phase to another can only happen in the order described in the above list.\n\nAn example of all of the phases Perl code can see:\n\nBEGIN { print \"compile-time: ${^GLOBALPHASE}\\n\" }\n\nINIT { print \"init-time: ${^GLOBALPHASE}\\n\" }\n\nCHECK { print \"check-time: ${^GLOBALPHASE}\\n\" }\n\n{\npackage Print::Phase;\n\nsub new {\nmy ($class, $time) = @;\nreturn bless \\$time, $class;\n}\n\nsub DESTROY {\nmy $self = shift;\nprint \"$$self: ${^GLOBALPHASE}\\n\";\n}\n}\n\nprint \"run-time: ${^GLOBALPHASE}\\n\";\n\nmy $runtime = Print::Phase->new(\n\"lexical variables are garbage collected before END\"\n);\n\nEND { print \"end-time: ${^GLOBALPHASE}\\n\" }\n\nour $destruct = Print::Phase->new(\n\"package variables are garbage collected after END\"\n);\n\nThis will print out\n\ncompile-time: START\ncheck-time: CHECK\ninit-time: INIT\nrun-time: RUN\nlexical variables are garbage collected before END: RUN\nend-time: END\npackage variables are garbage collected after END: DESTRUCT\n\nThis variable was added in Perl 5.14.0.\n\n$^H WARNING: This variable is strictly for internal use only. Its availability,\nbehavior, and contents are subject to change without notice.\n\nThis variable contains compile-time hints for the Perl interpreter. At the end of\ncompilation of a BLOCK the value of this variable is restored to the value when the\ninterpreter started to compile the BLOCK.\n\nEach time a statement completes being compiled, the current value of $^H is stored\nwith that statement, and can later be retrieved via \"(caller($level))[8]\". See\n\"caller EXPR\" in perlfunc.\n\nWhen perl begins to parse any block construct that provides a lexical scope (e.g.,\neval body, required file, subroutine body, loop body, or conditional block), the\nexisting value of $^H is saved, but its value is left unchanged. When the\ncompilation of the block is completed, it regains the saved value. Between the\npoints where its value is saved and restored, code that executes within BEGIN blocks\nis free to change the value of $^H.\n\nThis behavior provides the semantic of lexical scoping, and is used in, for instance,\nthe \"use strict\" pragma.\n\nThe contents should be an integer; different bits of it are used for different\npragmatic flags. Here's an example:\n\nsub add100 { $^H |= 0x100 }\n\nsub foo {\nBEGIN { add100() }\nbar->baz($boon);\n}\n\nConsider what happens during execution of the BEGIN block. At this point the BEGIN\nblock has already been compiled, but the body of foo() is still being compiled. The\nnew value of $^H will therefore be visible only while the body of foo() is being\ncompiled.\n\nSubstitution of \"BEGIN { add100() }\" block with:\n\nBEGIN { require strict; strict->import('vars') }\n\ndemonstrates how \"use strict 'vars'\" is implemented. Here's a conditional version of\nthe same lexical pragma:\n\nBEGIN {\nrequire strict; strict->import('vars') if $condition\n}\n\nThis variable was added in Perl 5.003.\n\n%^H The \"%^H\" hash provides the same scoping semantics as $^H. This makes it useful for\nimplementing lexically scoped pragmas. See perlpragma. All the entries are\nstringified when accessed at runtime, so only simple values can be accommodated.\nThis means no references to objects, for example.\n\nEach time a statement completes being compiled, the current value of \"%^H\" is stored\nwith that statement, and can later be retrieved via \"(caller($level))[10]\". See\n\"caller EXPR\" in perlfunc.\n\nWhen putting items into \"%^H\", in order to avoid conflicting with other users of the\nhash there is a convention regarding which keys to use. A module should use only\nkeys that begin with the module's name (the name of its main package) and a \"/\"\ncharacter. For example, a module \"Foo::Bar\" should use keys such as \"Foo::Bar/baz\".\n\nThis variable was added in Perl v5.6.0.\n\n${^OPEN}\nAn internal variable used by PerlIO. A string in two parts, separated by a \"\\0\"\nbyte, the first part describes the input layers, the second part describes the output\nlayers.\n\nThis is the mechanism that applies the lexical effects of the open pragma, and the\nmain program scope effects of the \"io\" or \"D\" options for the -C command-line switch\nand PERLUNICODE environment variable.\n\nThe functions accept(), open(), pipe(), readpipe() (as well as the related \"qx\" and\n`STRING` operators), socket(), socketpair(), and sysopen() are affected by the\nlexical value of this variable. The implicit \"ARGV\" handle opened by readline() (or\nthe related \"<>\" and \"<<>>\" operators) on passed filenames is also affected (but not\nif it opens \"STDIN\"). If this variable is not set, these functions will set the\ndefault layers as described in \"Defaults and how to override them\" in PerlIO.\n\nopen() ignores this variable (and the default layers) when called with 3 arguments\nand explicit layers are specified. Indirect calls to these functions via modules\nlike IO::Handle are not affected as they occur in a different lexical scope.\nDirectory handles such as opened by opendir() are not currently affected.\n\nThis variable was added in Perl v5.8.0.\n\n$PERLDB\n$^P The internal variable for debugging support. The meanings of the various bits are\nsubject to change, but currently indicate:\n\n0x01 Debug subroutine enter/exit.\n\n0x02 Line-by-line debugging. Causes DB::DB() subroutine to be called for each\nstatement executed. Also causes saving source code lines (like 0x400).\n\n0x04 Switch off optimizations.\n\n0x08 Preserve more data for future interactive inspections.\n\n0x10 Keep info about source lines on which a subroutine is defined.\n\n0x20 Start with single-step on.\n\n0x40 Use subroutine address instead of name when reporting.\n\n0x80 Report \"goto &subroutine\" as well.\n\n0x100 Provide informative \"file\" names for evals based on the place they were\ncompiled.\n\n0x200 Provide informative names to anonymous subroutines based on the place they were\ncompiled.\n\n0x400 Save source code lines into \"@{\"<$filename\"}\".\n\n0x800 When saving source, include evals that generate no subroutines.\n\n0x1000\nWhen saving source, include source that did not compile.\n\nSome bits may be relevant at compile-time only, some at run-time only. This is a new\nmechanism and the details may change. See also perldebguts.\n\n${^TAINT}\nReflects if taint mode is on or off. 1 for on (the program was run with -T), 0 for\noff, -1 when only taint warnings are enabled (i.e. with -t or -TU).\n\nNote: if your perl was built without taint support (see perlsec), then \"${^TAINT}\"\nwill always be 0, even if the program was run with -T).\n\nThis variable is read-only.\n\nThis variable was added in Perl v5.8.0.\n\n${^SAFELOCALES}\nReflects if safe locale operations are available to this perl (when the value is 1)\nor not (the value is 0). This variable is always 1 if the perl has been compiled\nwithout threads. It is also 1 if this perl is using thread-safe locale operations.\nNote that an individual thread may choose to use the global locale (generally unsafe)\nby calling \"switchtogloballocale\" in perlapi. This variable currently is still\nset to 1 in such threads.\n\nThis variable is read-only.\n\nThis variable was added in Perl v5.28.0.\n\n${^UNICODE}\nReflects certain Unicode settings of Perl. See perlrun documentation for the \"-C\"\nswitch for more information about the possible values.\n\nThis variable is set during Perl startup and is thereafter read-only.\n\nThis variable was added in Perl v5.8.2.\n\n${^UTF8CACHE}\nThis variable controls the state of the internal UTF-8 offset caching code. 1 for on\n(the default), 0 for off, -1 to debug the caching code by checking all its results\nagainst linear scans, and panicking on any discrepancy.\n\nThis variable was added in Perl v5.8.9. It is subject to change or removal without\nnotice, but is currently used to avoid recalculating the boundaries of multi-byte\nUTF-8-encoded characters.\n\n${^UTF8LOCALE}\nThis variable indicates whether a UTF-8 locale was detected by perl at startup. This\ninformation is used by perl when it's in adjust-utf8ness-to-locale mode (as when run\nwith the \"-CL\" command-line switch); see perlrun for more info on this.\n\nThis variable was added in Perl v5.8.8.\n" }, { "name": "Deprecated and removed variables", "content": "Deprecating a variable announces the intent of the perl maintainers to eventually remove the\nvariable from the language. It may still be available despite its status. Using a\ndeprecated variable triggers a warning.\n\nOnce a variable is removed, its use triggers an error telling you the variable is\nunsupported.\n\nSee perldiag for details about error messages.\n\n$# $# was a variable that could be used to format printed numbers. After a deprecation\ncycle, its magic was removed in Perl v5.10.0 and using it now triggers a warning: \"$#\nis no longer supported\".\n\nThis is not the sigil you use in front of an array name to get the last index, like\n$#array. That's still how you get the last index of an array in Perl. The two have\nnothing to do with each other.\n\nDeprecated in Perl 5.\n\nRemoved in Perl v5.10.0.\n\n$* $* was a variable that you could use to enable multiline matching. After a\ndeprecation cycle, its magic was removed in Perl v5.10.0. Using it now triggers a\nwarning: \"$* is no longer supported\". You should use the \"/s\" and \"/m\" regexp\nmodifiers instead.\n\nDeprecated in Perl 5.\n\nRemoved in Perl v5.10.0.\n\n$[ This variable stores the index of the first element in an array, and of the first\ncharacter in a substring. The default is 0, but you could theoretically set it to 1\nto make Perl behave more like awk (or Fortran) when subscripting and when evaluating\nthe index() and substr() functions.\n\nAs of release 5 of Perl, assignment to $[ is treated as a compiler directive, and\ncannot influence the behavior of any other file. (That's why you can only assign\ncompile-time constants to it.) Its use is highly discouraged.\n\nPrior to Perl v5.10.0, assignment to $[ could be seen from outer lexical scopes in\nthe same file, unlike other compile-time directives (such as strict). Using local()\non it would bind its value strictly to a lexical block. Now it is always lexically\nscoped.\n\nAs of Perl v5.16.0, it is implemented by the arybase module.\n\nAs of Perl v5.30.0, or under \"use v5.16\", or \"no feature \"arraybase\"\", $[ no longer\nhas any effect, and always contains 0. Assigning 0 to it is permitted, but any other\nvalue will produce an error.\n\nMnemonic: [ begins subscripts.\n\nDeprecated in Perl v5.12.0.\n\n${^ENCODING}\nThis variable is no longer supported.\n\nIt used to hold the object reference to the \"Encode\" object that was used to convert\nthe source code to Unicode.\n\nIts purpose was to allow your non-ASCII Perl scripts not to have to be written in\nUTF-8; this was useful before editors that worked on UTF-8 encoded text were common,\nbut that was long ago. It caused problems, such as affecting the operation of other\nmodules that weren't expecting it, causing general mayhem.\n\nIf you need something like this functionality, it is recommended that use you a\nsimple source filter, such as Filter::Encoding.\n\nIf you are coming here because code of yours is being adversely affected by someone's\nuse of this variable, you can usually work around it by doing this:\n\nlocal ${^ENCODING};\n\nnear the beginning of the functions that are getting broken. This undefines the\nvariable during the scope of execution of the including function.\n\nThis variable was added in Perl 5.8.2 and removed in 5.26.0. Setting it to anything\nother than \"undef\" was made fatal in Perl 5.28.0.\n\n${^WIN32SLOPPYSTAT}\nThis variable no longer has any function.\n\nThis variable was added in Perl v5.10.0 and removed in Perl v5.34.0.\n\nperl v5.38.2 2026-08-18 PERLVAR(1)" } ] } }, "summary": "perlvar - Perl predefined variables", "flags": [], "examples": [], "see_also": [] }