EditPageHistoryDiffInfoLikePages

Annotated edit history of perlvar(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	PERLVAR
		2	!!!PERLVAR
		3	NAME
		4	DESCRIPTION
		5	BUGS
		6	----
		7	!!NAME
		8
		9
		10	perlvar - Perl predefined variables
		11	!!DESCRIPTION
		12
		13
		14	__Predefined Names__
		15
		16
		17	The following names have special meaning to Perl. Most
		18	punctuation names have reasonable mnemonics, or analogs in
		19	the shells. Nevertheless, if you wish to use long variable
		20	names, you need only say
		21
		22
		23	use English;
		24	at the top of your program. This will alias all the short names to the long names in the current package. Some even have medium names, generally borrowed from __awk__.
		25
		26
		27	If you don't mind the performance hit, variables that depend
		28	on the currently selected filehandle may instead be set by
		29	calling an appropriate object method on the IO::Handle
		30	object. (Summary lines below for this contain the word
		31	HANDLE .) First you must say
		32
		33
		34	use IO::Handle;
		35	after which you may use either
		36
		37
		38	method HANDLE EXPR
		39	or more safely,
		40
		41
		42	HANDLE-
		43	Each method returns the old value of the IO::Handle attribute. The methods each take an optional EXPR , which if supplied specifies the new value for the IO::Handle attribute in question. If not supplied, most methods do nothing to the current value--except for ''autoflush()'', which will assume a 1 for you, just to be different. Because loading in the IO::Handle class is an expensive operation, you should learn how to use the regular built-in variables.
		44
		45
		46	A few of these variables are considered ``read-only''. This
		47	means that if you try to assign to this variable, either
		48	directly or indirectly through a reference, you'll raise a
		49	run-time exception.
		50
		51
		52	The following list is ordered by scalar variables first,
		53	then the arrays, then the hashes.
		54
		55
		56	$ARG
		57
		58
		59	$_
		60
		61
		62	The default input and pattern-searching space. The following
		63	pairs are equivalent:
		64
		65
		66	while (
		67	/^Subject:/
		68	$_ =~ /^Subject:/
		69	tr/a-z/A-Z/
		70	$_ =~ tr/a-z/A-Z/
		71	chomp
		72	chomp($_)
		73	Here are the places where Perl will assume $_ even if you don't use it:
		74
		75
		76	Various unary functions, including functions like
		77	''ord()'' and ''int()'', as well as the all file tests
		78	(-f, -d) except for -t, which
		79	defaults to STDIN .
		80
		81
		82	Various list functions like ''print()'' and
		83	''unlink()''.
		84
		85
		86	The pattern matching operations m//, s///,
		87	and tr/// when used without an =~
		88	operator.
		89
		90
		91	The default iterator variable in a foreach loop if
		92	no other variable is supplied.
		93
		94
		95	The implicit iterator variable in the ''grep()'' and
		96	''map()'' functions.
		97
		98
		99	The default place to put an input record when a
		100	operation's result is tested by itself
		101	as the sole criterion of a while test. Outside a
		102	while test, this will not happen.
		103
		104
		105	(Mnemonic: underline is understood in certain
		106	operations.)
		107
		108
		109	$digits''''
		110
		111
		112	Contains the subpattern from the corresponding set of
		113	capturing parentheses from the last pattern match, not
		114	counting patterns matched in nested blocks that have been
		115	exited already. (Mnemonic: like digits.) These variables are
		116	all read-only and dynamically scoped to the current
		117	BLOCK .
		118
		119
		120	$MATCH
		121
		122
		123	$
		124
		125
		126	The string matched by the last successful pattern match (not
		127	counting any matches hidden within a BLOCK or
		128	''eval()'' enclosed by the current BLOCK
		129	). (Mnemonic: like
		130	BLOCK .
		131
		132
		133	The use of this variable anywhere in a program imposes a
		134	considerable performance penalty on all regular expression
		135	matches. See BUGS .
		136
		137
		138	$PREMATCH
		139
		140
		141	$`
		142
		143
		144	The string preceding whatever was matched by the last
		145	successful pattern match (not counting any matches hidden
		146	within a BLOCK or eval enclosed by the
		147	current BLOCK ). (Mnemonic: ` often
		148	precedes a quoted string.) This variable is
		149	read-only.
		150
		151
		152	The use of this variable anywhere in a program imposes a
		153	considerable performance penalty on all regular expression
		154	matches. See BUGS .
		155
		156
		157	$POSTMATCH
		158
		159
		160	$'
		161
		162
		163	The string following whatever was matched by the last
		164	successful pattern match (not counting any matches hidden
		165	within a BLOCK or ''eval()'' enclosed by
		166	the current BLOCK ). (Mnemonic: '
		167	often follows a quoted string.) Example:
		168
		169
		170	$_ = 'abcdefghi';
		171	/def/;
		172	print
		173	This variable is read-only and dynamically scoped to the current BLOCK .
		174
		175
		176	The use of this variable anywhere in a program imposes a
		177	considerable performance penalty on all regular expression
		178	matches. See BUGS .
		179
		180
		181	$LAST_PAREN_MATCH
		182
		183
		184	$+
		185
		186
		187	The last bracket matched by the last search pattern. This is
		188	useful if you don't know which one of a set of alternative
		189	patterns matched. For example:
		190
		191
		192	/Version: (.*)Revision: (.*)/
		193	(Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK .
		194
		195
		196	@LAST_MATCH_END
		197
		198
		199	@+
		200
		201
		202	This array holds the offsets of the ends of the last
		203	successful submatches in the currently active dynamic scope.
		204	$+[[0] is the offset into the string of the end of
		205	the entire match. This is the same value as what the
		206	pos function returns when called on the variable
		207	that was matched against. The ''n''th element of this
		208	array holds the offset of the ''n''th submatch, so
		209	$+[[1] is the offset past where $1 ends,
		210	$+[[2] the offset past where $2 ends, and
		211	so on. You can use $#+ to determine how many
		212	subgroups were in the last successful match. See the
		213	examples given for the @- variable.
		214
		215
		216	$MULTILINE_MATCHING
		217
		218
		219	$*
		220
		221
		222	Set to a non-zero integer value to do multi-line matching
		223	within a string, 0 (or undefined) to tell Perl that it can
		224	assume that strings contain a single line, for the purpose
		225	of optimizing pattern matches. Pattern matches on strings
		226	containing multiple newlines can produce confusing results
		227	when $* is 0 or undefined. Default is undefined.
		228	(Mnemonic: * matches multiple things.) This variable
		229	influences the interpretation of only ^ and
		230	$. A literal newline can be searched for even when
		231	$* == 0.
		232
		233
		234	Use of $* is deprecated in modern Perl, supplanted
		235	by the /s and /m modifiers on pattern
		236	matching.
		237
		238
		239	Assigning a non-numerical value to $* triggers a
		240	warning (and makes $* act if $* == 0),
		241	while assigning a numerical value to $* makes that
		242	an implicit int is applied on the
		243	value.
		244
		245
		246	input_line_number HANDLE EXPR
		247
		248
		249	$INPUT_LINE_NUMBER
		250
		251
		252	$NR
		253
		254
		255	$.
		256
		257
		258	The current input record number for the last file handle
		259	from which you just ''read()'' (or called a seek
		260	or tell on). The value may be different from the
		261	actual physical line number in the file, depending on what
		262	notion of ``line'' is in effect--see $/ on how to
		263	change that. An explicit close on a filehandle resets the
		264	line number. Because never does an
		265	explicit close, line numbers increase across
		266	ARGV files (but see examples in ``eof'' in
		267	perlfunc). Consider this variable read-only: setting it does
		268	not reposition the seek pointer; you'll have to do that on
		269	your own. Localizing $. has the effect of also
		270	localizing Perl's notion of ``the last read filehandle''.
		271	(Mnemonic: many programs use ``.'' to mean the current line
		272	number.)
		273
		274
		275	input_record_separator HANDLE
		276	EXPR
		277
		278
		279	$INPUT_RECORD_SEPARATOR
		280
		281
		282	$RS
		283
		284
		285	$/
		286
		287
		288	The input record separator, newline by default. This
		289	influences Perl's idea of what a ``line'' is. Works like
		290	__awk__'s RS variable, including treating
		291	empty lines as a terminator if set to the null string. (An
		292	empty line cannot contain any spaces or tabs.) You may set
		293	it to a multi-character string to match a multi-character
		294	terminator, or to undef to read through the end of
		295	file. Setting it to means something
		296	slightly different than setting to , if
		297	the file contains consecutive empty lines. Setting to
		298	will treat two or more consecutive
		299	empty lines as a single empty line. Setting to
		300	will blindly assume that the next
		301	input character belongs to the next paragraph, even if it's
		302	a newline. (Mnemonic: / delimits line boundaries when
		303	quoting poetry.)
		304
		305
		306	undef $/; # enable
		307	Remember: the value of $/ is a string, not a regex. __awk__ has to be better for something. :-)
		308
		309
		310	Setting $/ to a reference to an integer, scalar
		311	containing an integer, or scalar that's convertible to an
		312	integer will attempt to read records instead of lines, with
		313	the maximum record size being the referenced integer. So
		314	this:
		315
		316
		317	$/ = 32768; # or
		318	will read a record of no more than 32768 bytes from FILE . If you're not reading from a record-oriented file (or your OS doesn't have record-oriented files), then you'll likely get a full chunk of data with every read. If a record is larger than the record size you've set, you'll get the record back in pieces.
		319
		320
		321	On VMS , record reads are done with the
		322	equivalent of sysread, so it's best not to mix
		323	record and non-record reads on the same file. (This is
		324	unlikely to be a problem, because any file you'd want to
		325	read in record mode is probably unusable in line mode.)
		326	Non-VMS systems do normal I/O, so it's safe to mix record
		327	and non-record reads of a file.
		328
		329
		330	See also ``Newlines'' in perlport. Also see
		331	$..
		332
		333
		334	autoflush HANDLE EXPR
		335
		336
		337	$OUTPUT_AUTOFLUSH
		338
		339
		340	$
		341
		342
		343	If set to nonzero, forces a flush right away and after every
		344	write or print on the currently selected output channel.
		345	Default is 0 (regardless of whether the channel is really
		346	buffered by the system or not; $ tells you only
		347	whether you've asked Perl explicitly to flush after each
		348	write). STDOUT will typically be line
		349	buffered if output is to the terminal and block buffered
		350	otherwise. Setting this variable is useful primarily when
		351	you are outputting to a pipe or socket, such as when you are
		352	running a Perl program under __rsh__ and want to see the
		353	output as it's happening. This has no effect on input
		354	buffering. See ``getc'' in perlfunc for that. (Mnemonic:
		355	when you want your pipes to be piping hot.)
		356
		357
		358	output_field_separator HANDLE
		359	EXPR
		360
		361
		362	$OUTPUT_FIELD_SEPARATOR
		363
		364
		365	$OFS
		366
		367
		368	$,
		369
		370
		371	The output field separator for the print operator.
		372	Ordinarily the print operator simply prints out its
		373	arguments without further adornment. To get behavior more
		374	like __awk__, set this variable as you would set
		375	__awk__'s OFS variable to specify what is
		376	printed between fields. (Mnemonic: what is printed when
		377	there is a ``,'' in your print statement.)
		378
		379
		380	output_record_separator HANDLE
		381	EXPR
		382
		383
		384	$OUTPUT_RECORD_SEPARATOR
		385
		386
		387	$ORS
		388
		389
		390	$\
		391
		392
		393	The output record separator for the print operator.
		394	Ordinarily the print operator simply prints out its
		395	arguments as is, with no trailing newline or other
		396	end-of-record string added. To get behavior more like
		397	__awk__, set this variable as you would set __awk__'s
		398	ORS variable to specify what is printed at
		399	the end of the print. (Mnemonic: you set $\ instead
		400	of adding ``n'' at the end of the print. Also, it's just
		401	like $/, but it's what you get ``back'' from
		402	Perl.)
		403
		404
		405	$LIST_SEPARATOR
		406
		407
		408	$
		409
		410
		411	This is like $, except that it applies to array and
		412	slice values interpolated into a double-quoted string (or
		413	similar interpreted string). Default is a space. (Mnemonic:
		414	obvious, I think.)
		415
		416
		417	$SUBSCRIPT_SEPARATOR
		418
		419
		420	$SUBSEP
		421
		422
		423	$;
		424
		425
		426	The subscript separator for multidimensional array
		427	emulation. If you refer to a hash element as
		428
		429
		430	$foo{$a,$b,$c}
		431	it really means
		432
		433
		434	$foo{join($;, $a, $b, $c)}
		435	But don't put
		436
		437
		438	@foo{$a,$b,$c} # a slice--note the @
		439	which means
		440
		441
		442	($foo{$a},$foo{$b},$foo{$c})
		443	Default is ``034'', the same as SUBSEP in __awk__. If your keys contain binary data there might not be any safe value for $;. (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. Yeah, I know, it's pretty lame, but $, is already taken for something more important.)
		444
		445
		446	Consider using ``real'' multidimensional arrays as described
		447	in perllol.
		448
		449
		450	$OFMT
		451
		452
		453	$#
		454
		455
		456	The output format for printed numbers. This variable is a
		457	half-hearted attempt to emulate __awk__'s
		458	OFMT variable. There are times, however, when
		459	__awk__ and Perl have differing notions of what counts as
		460	numeric. The initial value is __n''g
		461	''n'' is the value of the macro DBL_DIG
		462	from your system's ''float.h''. This is different from
		463	__awk__'s default OFMT setting of
		464	``%.6g'', so you need to set $# explicitly to get
		465	__awk__'s value. (Mnemonic: # is the number
		466	sign.)
		467
		468
		469	Use of $# is deprecated.
		470
		471
		472	format_page_number HANDLE EXPR
		473
		474
		475	$FORMAT_PAGE_NUMBER
		476
		477
		478	$%
		479
		480
		481	The current page number of the currently selected output
		482	channel. Used with formats. (Mnemonic: % is page number in
		483	__nroff__.)
		484
		485
		486	format_lines_per_page HANDLE
		487	EXPR
		488
		489
		490	$FORMAT_LINES_PER_PAGE
		491
		492
		493	$=
		494
		495
		496	The current page length (printable lines) of the currently
		497	selected output channel. Default is 60. Used with formats.
		498	(Mnemonic: = has horizontal lines.)
		499
		500
		501	format_lines_left HANDLE EXPR
		502
		503
		504	$FORMAT_LINES_LEFT
		505
		506
		507	$-
		508
		509
		510	The number of lines left on the page of the currently
		511	selected output channel. Used with formats. (Mnemonic:
		512	lines_on_page - lines_printed.)
		513
		514
		515	@LAST_MATCH_START
		516
		517
		518	@-
		519
		520
		521	$-[[0] is the offset of the start of the last successful
		522	match. $-[[''n''] is the offset of the
		523	start of the substring matched by ''n''-th subpattern, or
		524	undef if the subpattern did not match.
		525
		526
		527	Thus after a match against $_, $
		528	substr $_, $-[[0], $+[[0] - $-[[0]. Similarly,
		529	$''n'' coincides with substr $_,
		530	$-[[''n''], $+[[''n''] -
		531	$-[[''n''] if $-[[''n'']
		532	is defined, and $+ coincides with substr $_, $-[[$#-],
		533	$+[[$#-]. One can use $#- to find the last
		534	matched subgroup in the last successful match. Contrast with
		535	$#+, the number of subgroups in the regular
		536	expression. Compare with @+.
		537
		538
		539	This array holds the offsets of the beginnings of the last
		540	successful submatches in the currently active dynamic scope.
		541	$-[[0] is the offset into the string of the
		542	beginning of the entire match. The ''n''th element of
		543	this array holds the offset of the ''n''th submatch, so
		544	$+[[1] is the offset where $1 begins,
		545	$+[[2] the offset where $2 begins, and so
		546	on. You can use $#- to determine how many subgroups
		547	were in the last successful match. Compare with the
		548	@+ variable.
		549
		550
		551	After a match against some variable
		552	$var:
		553
		554
		555	$` is the same as substr($var, 0,
		556	$-[[0])
		557
		558
		559	$ is the same as substr($var, $-[[0], $+[[0]
		560	- $-[[0])
		561
		562
		563	$' is the same as substr($var,
		564	$+[[0])
		565
		566
		567	$1 is the same as substr($var, $-[[1], $+[[1] -
		568	$-[[1])
		569
		570
		571	$2 is the same as substr($var, $-[[2], $+[[2] -
		572	$-[[2])
		573
		574
		575	$3 is the same as substr $var, $-[[3], $+[[3] -
		576	$-[[3])
		577
		578
		579	format_name HANDLE EXPR
		580
		581
		582	$FORMAT_NAME
		583
		584
		585	$~
		586
		587
		588	The name of the current report format for the currently
		589	selected output channel. Default is the name of the
		590	filehandle. (Mnemonic: brother to $^.)
		591
		592
		593	format_top_name HANDLE EXPR
		594
		595
		596	$FORMAT_TOP_NAME
		597
		598
		599	$^
		600
		601
		602	The name of the current top-of-page format for the currently
		603	selected output channel. Default is the name of the
		604	filehandle with _TOP appended. (Mnemonic: points to top of
		605	page.)
		606
		607
		608	format_line_break_characters HANDLE
		609	EXPR
		610
		611
		612	$FORMAT_LINE_BREAK_CHARACTERS
		613
		614
		615	$:
		616
		617
		618	The current set of characters after which a string may be
		619	broken to fill continuation fields (starting with ^) in a
		620	format. Default is `` n-'', to break on whitespace or
		621	hyphens. (Mnemonic: a ``colon'' in poetry is a part of a
		622	line.)
		623
		624
		625	format_formfeed HANDLE EXPR
		626
		627
		628	$FORMAT_FORMFEED
		629
		630
		631	$^L
		632
		633
		634	What formats output as a form feed. Default is
		635	f.
		636
		637
		638	$ACCUMULATOR
		639
		640
		641	$^A
		642
		643
		644	The current value of the ''write()'' accumulator for
		645	''format()'' lines. A format contains ''formline()''
		646	calls that put their result into $^A. After calling
		647	its format, ''write()'' prints out the contents of
		648	$^A and empties. So you never really see the
		649	contents of $^A unless you call ''formline()''
		650	yourself and then look at it. See perlform and
		651	``''formline()'''' in perlfunc.
		652
		653
		654	$CHILD_ERROR
		655
		656
		657	$?
		658
		659
		660	The status returned by the last pipe close, backtick
		661	(``) command, successful call to ''wait()'' or
		662	''waitpid()'', or from the ''system()'' operator. This
		663	is just the 16-bit status word returned by the ''wait()''
		664	system call (or else is made up to look like it). Thus, the
		665	exit value of the subprocess is really ($?
		666	), and $? gives which signal, if
		667	any, the process died from, and $?
		668	reports whether there was a core dump. (Mnemonic: similar to
		669	__sh__ and __ksh__.)
		670
		671
		672	Additionally, if the h_errno variable is supported
		673	in C, its value is returned via $? if any
		674	gethost*() function fails.
		675
		676
		677	If you have installed a signal handler for SIGCHLD,
		678	the value of $? will usually be wrong outside that
		679	handler.
		680
		681
		682	Inside an END subroutine $? contains the
		683	value that is going to be given to exit(). You can
		684	modify $? in an END subroutine to change
		685	the exit status of your program. For example:
		686
		687
		688	END {
		689	$? = 1 if $? == 255; # die would make it 255
		690	}
		691	Under VMS , the pragma use vmsish 'status' makes $? reflect the actual VMS exit status, instead of the default emulation of POSIX status.
		692
		693
		694	Also see ``Error Indicators''.
		695
		696
		697	$OS_ERROR
		698
		699
		700	$ERRNO
		701
		702
		703	$!
		704
		705
		706	If used numerically, yields the current value of the C
		707	errno variable, with all the usual caveats. (This
		708	means that you shouldn't depend on the value of $!
		709	to be anything in particular unless you've gotten a specific
		710	error return indicating a system error.) If used an a
		711	string, yields the corresponding system error string. You
		712	can assign a number to $! to set ''errno'' if,
		713	for instance, you want to return the
		714	string for error ''n'', or you want to set the exit value
		715	for the ''die()'' operator. (Mnemonic: What just went
		716	bang?)
		717
		718
		719	Also see ``Error Indicators''.
		720
		721
		722	$EXTENDED_OS_ERROR
		723
		724
		725	$^E
		726
		727
		728	Error information specific to the current operating system.
		729	At the moment, this differs from $! under only
		730	VMS , OS/2 , and Win32 (and
2	perry	731	for !MacPerl). On all other platforms, $^E is always
1	perry	732	just the same as $!.
		733
		734
		735	Under VMS , $^E provides the
		736	VMS status value from the last system error.
		737	This is more specific information about the last system
		738	error than that provided by $!. This is
		739	particularly important when $! is set to
		740	__EVMSERR__ .
		741
		742
		743	Under OS/2 , $^E is set to the error
		744	code of the last call to OS/2 API either via
		745	CRT , or directly from perl.
		746
		747
		748	Under Win32, $^E always returns the last error
		749	information reported by the Win32 call
2	perry	750	!GetLastError() which describes the last error from
1	perry	751	within the Win32 API . Most Win32-specific
		752	code will report errors via $^E.
		753	ANSI C and Unix-like calls set errno
		754	and so most portable Perl code will report errors via
		755	$!.
		756
		757
		758	Caveats mentioned in the description of $!
		759	generally apply to $^E, also. (Mnemonic: Extra
		760	error explanation.)
		761
		762
		763	Also see ``Error Indicators''.
		764
		765
		766	$EVAL_ERROR
		767
		768
		769	$@
		770
		771
		772	The Perl syntax error message from the last ''eval()''
		773	operator. If null, the last ''eval()'' parsed and
		774	executed correctly (although the operations you invoked may
		775	have failed in the normal fashion). (Mnemonic: Where was the
		776	syntax error ``at''?)
		777
		778
		779	Warning messages are not collected in this variable. You
		780	can, however, set up a routine to process warnings by
		781	setting $SIG{__WARN__} as described
		782	below.
		783
		784
		785	Also see ``Error Indicators''.
		786
		787
		788	$PROCESS_ID
		789
		790
		791	$PID
		792
		793
		794	$$
		795
		796
		797	The process number of the Perl running this script. You
		798	should consider this variable read-only, although it will be
		799	altered across ''fork()'' calls. (Mnemonic: same as
		800	shells.)
		801
		802
		803	$REAL_USER_ID
		804
		805
		806	$UID
		807
		808
		809	$
		810
		811
		812	The real uid of this process. (Mnemonic: it's the uid you
		813	came ''from'', if you're running setuid.)
		814
		815
		816	$EFFECTIVE_USER_ID
		817
		818
		819	$EUID
		820
		821
		822	$
		823
		824
		825	The effective uid of this process. Example:
		826
		827
		828	$
		829	(Mnemonic: it's the uid you went ''to'', if you're running setuid.) $ and $ can be swapped only on machines supporting ''setreuid()''.
		830
		831
		832	$REAL_GROUP_ID
		833
		834
		835	$GID
		836
		837
		838	$(
		839
		840
		841	The real gid of this process. If you are on a machine that
		842	supports membership in multiple groups simultaneously, gives
		843	a space separated list of groups you are in. The first
		844	number is the one returned by ''getgid()'', and the
		845	subsequent ones by ''getgroups()'', one of which may be
		846	the same as the first number.
		847
		848
		849	However, a value assigned to $( must be a single
		850	number used to set the real gid. So the value given by
		851	$( should ''not'' be assigned back to
		852	$( without being forced numeric, such as by adding
		853	zero.
		854
		855
		856	(Mnemonic: parentheses are used to ''group'' things. The
		857	real gid is the group you ''left'', if you're running
		858	setgid.)
		859
		860
		861	$EFFECTIVE_GROUP_ID
		862
		863
		864	$EGID
		865
		866
		867	$)
		868
		869
		870	The effective gid of this process. If you are on a machine
		871	that supports membership in multiple groups simultaneously,
		872	gives a space separated list of groups you are in. The first
		873	number is the one returned by ''getegid()'', and the
		874	subsequent ones by ''getgroups()'', one of which may be
		875	the same as the first number.
		876
		877
		878	Similarly, a value assigned to $) must also be a
		879	space-separated list of numbers. The first number sets the
		880	effective gid, and the rest (if any) are passed to
		881	''setgroups()''. To get the effect of an empty list for
		882	''setgroups()'', just repeat the new effective gid; that
		883	is, to force an effective gid of 5 and an effectively empty
		884	''setgroups()'' list, say $) =
		885	.
		886
		887
		888	(Mnemonic: parentheses are used to ''group'' things. The
		889	effective gid is the group that's ''right'' for you, if
		890	you're running setgid.)
		891
		892
		893	$, $, $( and $)
		894	can be set only on machines that support the corresponding
		895	''set[[re][[ug]id()'' routine. $( and $)
		896	can be swapped only on machines supporting
		897	''setregid()''.
		898
		899
		900	$PROGRAM_NAME
		901
		902
		903	$0
		904
		905
		906	Contains the name of the program being executed. On some
		907	operating systems assigning to $0 modifies the
		908	argument area that the __ps__ program sees. This is more
		909	useful as a way of indicating the current program state than
		910	it is for hiding the program you're running. (Mnemonic: same
		911	as __sh__ and __ksh__.)
		912
		913
		914	Note for BSD users: setting $0 does
		915	not completely remove ``perl'' from the ps(1) output.
		916	For example, setting $0 to
		917	will result in
		918	. This is an operating system
		919	feature.
		920
		921
		922	$[[
		923
		924
		925	The index of the first element in an array, and of the first
		926	character in a substring. Default is 0, but you could
		927	theoretically set it to 1 to make Perl behave more like
		928	__awk__ (or Fortran) when subscripting and when
		929	evaluating the ''index()'' and ''substr()'' functions.
		930	(Mnemonic: [[ begins subscripts.)
		931
		932
		933	As of release 5 of Perl, assignment to $[[ is
		934	treated as a compiler directive, and cannot influence the
		935	behavior of any other file. Its use is highly
		936	discouraged.
		937
		938
		939	$]
		940
		941
		942	The version + patchlevel / 1000 of the Perl interpreter.
		943	This variable can be used to determine whether the Perl
		944	interpreter executing a script is in the right range of
		945	versions. (Mnemonic: Is this version of perl in the right
		946	bracket?) Example:
		947
		948
		949	warn
		950	See also the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.
		951
		952
		953	The use of this variable is deprecated. The floating point
		954	representation can sometimes lead to inaccurate numeric
		955	comparisons. See $^V for a more modern
		956	representation of the Perl version that allows accurate
		957	string comparisons.
		958
		959
		960	$COMPILING
		961
		962
		963	$^C
		964
		965
		966	The current value of the flag associated with the __-c__
		967	switch. Mainly of use with __-MO=...__ to allow code to
		968	alter its behavior when being compiled, such as for example
		969	to AUTOLOAD at compile time rather than
		970	normal, deferred loading. See perlcc. Setting $^C =
		971	1 is similar to calling
		972	B::minus_c.
		973
		974
		975	$DEBUGGING
		976
		977
		978	$^D
		979
		980
		981	The current value of the debugging flags. (Mnemonic: value
		982	of __-D__ switch.)
		983
		984
		985	$SYSTEM_FD_MAX
		986
		987
		988	$^F
		989
		990
		991	The maximum system file descriptor, ordinarily 2. System
		992	file descriptors are passed to ''exec()''ed processes,
		993	while higher file descriptors are not. Also, during an
		994	''open()'', system file descriptors are preserved even if
		995	the ''open()'' fails. (Ordinary file descriptors are
		996	closed before the ''open()'' is attempted.) The
		997	close-on-exec status of a file descriptor will be decided
		998	according to the value of $^F when the
		999	corresponding file, pipe, or socket was opened, not the time
		1000	of the ''exec()''.
		1001
		1002
		1003	$^H
		1004
		1005
		1006	WARNING: This variable is strictly for
		1007	internal use only. Its availability, behavior, and contents
		1008	are subject to change without notice.
		1009
		1010
		1011	This variable contains compile-time hints for the Perl
		1012	interpreter. At the end of compilation of a
		1013	BLOCK the value of this variable is restored
		1014	to the value when the interpreter started to compile the
		1015	BLOCK .
		1016
		1017
		1018	When perl begins to parse any block construct that provides
		1019	a lexical scope (e.g., eval body, required file, subroutine
		1020	body, loop body, or conditional block), the existing value
		1021	of $^H is saved, but its value is left unchanged. When the
		1022	compilation of the block is completed, it regains the saved
		1023	value. Between the points where its value is saved and
		1024	restored, code that executes within BEGIN
		1025	blocks is free to change the value of $^H.
		1026
		1027
		1028	This behavior provides the semantic of lexical scoping, and
		1029	is used in, for instance, the use strict
		1030	pragma.
		1031
		1032
		1033	The contents should be an integer; different bits of it are
		1034	used for different pragmatic flags. Here's an
		1035	example:
		1036
		1037
		1038	sub add_100 { $^H = 0x100 }
		1039	sub foo {
		1040	BEGIN { add_100() }
		1041	bar-
		1042	Consider what happens during execution of the BEGIN block. At this point the BEGIN block has already been compiled, but the body of ''foo()'' is still being compiled. The new value of $^H will therefore be visible only while the body of ''foo()'' is being compiled.
		1043
		1044
		1045	Substitution of the above BEGIN block
		1046	with:
		1047
		1048
		1049	BEGIN { require strict; strict-
		1050	demonstrates how use strict 'vars' is implemented. Here's a conditional version of the same lexical pragma:
		1051
		1052
		1053	BEGIN { require strict; strict-
		1054
		1055
		1056	%^H
		1057
		1058
		1059	WARNING: This variable is strictly for
		1060	internal use only. Its availability, behavior, and contents
		1061	are subject to change without notice.
		1062
		1063
		1064	The %^H hash provides the same scoping semantic as $^H. This
		1065	makes it useful for implementation of lexically scoped
		1066	pragmas.
		1067
		1068
		1069	$INPLACE_EDIT
		1070
		1071
		1072	$^I
		1073
		1074
		1075	The current value of the inplace-edit extension. Use
		1076	undef to disable inplace editing. (Mnemonic: value
		1077	of __-i__ switch.)
		1078
		1079
		1080	$^M
		1081
		1082
		1083	By default, running out of memory is an untrappable, fatal
		1084	error. However, if suitably built, Perl can use the contents
		1085	of $^M as an emergency memory pool after
		1086	''die()''ing. Suppose that your Perl were compiled with
		1087	-DPERL_EMERGENCY_SBRK and used Perl's malloc.
		1088	Then
		1089
		1090
		1091	$^M = 'a' x (1
		1092	would allocate a 64K buffer for use in an emergency. See the ''INSTALL'' file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced feature, there is no English long name for this variable.
		1093
		1094
		1095	$OSNAME
		1096
		1097
		1098	$^O
		1099
		1100
		1101	The name of the operating system under which this copy of
		1102	Perl was built, as determined during the configuration
		1103	process. The value is identical to
		1104	$Config{'osname'}. See also Config and the
		1105	__-V__ command-line switch documented in
		1106	perlrun.
		1107
		1108
		1109	$PERLDB
		1110
		1111
		1112	$^P
		1113
		1114
		1115	The internal variable for debugging support. The meanings of
		1116	the various bits are subject to change, but currently
		1117	indicate:
		1118
		1119
		1120	0x01
		1121
		1122
		1123	Debug subroutine enter/exit.
		1124
		1125
		1126	0x02
		1127
		1128
		1129	Line-by-line debugging.
		1130
		1131
		1132	0x04
		1133
		1134
		1135	Switch off optimizations.
		1136
		1137
		1138	0x08
		1139
		1140
		1141	Preserve more data for future interactive
		1142	inspections.
		1143
		1144
		1145	0x10
		1146
		1147
		1148	Keep info about source lines on which a subroutine is
		1149	defined.
		1150
		1151
		1152	0x20
		1153
		1154
		1155	Start with single-step on.
		1156
		1157
		1158	0x40
		1159
		1160
		1161	Use subroutine address instead of name when
		1162	reporting.
		1163
		1164
		1165	0x80
		1166
		1167
		1168	Report goto as well.
		1169
		1170
		1171	0x100
		1172
		1173
		1174	Provide informative ``file'' names for evals based on the
		1175	place they were compiled.
		1176
		1177
		1178	0x200
		1179
		1180
		1181	Provide informative names to anonymous subroutines based on
		1182	the place they were compiled.
		1183
		1184
		1185	Some bits may be relevant at compile-time only, some at
		1186	run-time only. This is a new mechanism and the details may
		1187	change.
		1188
		1189
		1190	$LAST_REGEXP_CODE_RESULT
		1191
		1192
		1193	$^R
		1194
		1195
		1196	The result of evaluation of the last successful (?{ code
		1197	}) regular expression assertion (see perlre). May be
		1198	written to.
		1199
		1200
		1201	$EXCEPTIONS_BEING_CAUGHT
		1202
		1203
		1204	$^S
		1205
		1206
		1207	Current state of the interpreter. Undefined if parsing of
		1208	the current module/eval is not finished (may happen in
		1209	$SIG{__DIE__} and $SIG{__WARN__}
		1210	handlers). True if inside an ''eval()'', otherwise
		1211	false.
		1212
		1213
		1214	$BASETIME
		1215
		1216
		1217	$^T
		1218
		1219
		1220	The time at which the program began running, in seconds
		1221	since the epoch (beginning of 1970). The values returned by
		1222	the __-M__, __-A__, and __-C__ filetests are based
		1223	on this value.
		1224
		1225
		1226	$PERL_VERSION
		1227
		1228
		1229	$^V
		1230
		1231
		1232	The revision, version, and subversion of the Perl
		1233	interpreter, represented as a string composed of characters
		1234	with those ordinals. Thus in Perl v5.6.0 it equals
		1235	chr(5) . chr(6) . chr(0) and will return true for
		1236	$^V eq v5.6.0. Note that the characters in this
		1237	string value can potentially be in Unicode
		1238	range.
		1239
		1240
		1241	This can be used to determine whether the Perl interpreter
		1242	executing a script is in the right range of versions.
		1243	(Mnemonic: use ^V for Version Control.)
		1244	Example:
		1245
		1246
		1247	warn
		1248	See the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.
		1249
		1250
		1251	See also $] for an older representation of the Perl
		1252	version.
		1253
		1254
		1255	$WARNING
		1256
		1257
		1258	$^W
		1259
		1260
		1261	The current value of the warning switch, initially true if
		1262	__-w__ was used, false otherwise, but directly
		1263	modifiable. (Mnemonic: related to the __-w__ switch.) See
		1264	also warnings.
		1265
		1266
		1267	${^WARNING_BITS}
		1268
		1269
		1270	The current set of warning checks enabled by the use
		1271	warnings pragma. See the documentation of
		1272	warnings for more details.
		1273
		1274
		1275	${^WIDE_SYSTEM_CALLS}
		1276
		1277
		1278	Global flag that enables system calls made by Perl to use
		1279	wide character APIs native to the system, if available. This
		1280	is currently only implemented on the Windows
		1281	platform.
		1282
		1283
		1284	This can also be enabled from the command line using the
		1285	-C switch.
		1286
		1287
		1288	The initial value is typically 0 for compatibility
		1289	with Perl versions earlier than 5.6, but may be
		1290	automatically set to 1 by Perl if the system
		1291	provides a user-settable default (e.g.,
		1292	$ENV{LC_CTYPE}).
		1293
		1294
		1295	The bytes pragma always overrides the effect of
		1296	this flag in the current lexical scope. See
		1297	bytes.
		1298
		1299
		1300	$EXECUTABLE_NAME
		1301
		1302
		1303	$^X
		1304
		1305
		1306	The name that the Perl binary itself was executed as, from
		1307	C's argv[[0]. This may not be a full pathname, nor
		1308	even necessarily in your path.
		1309
		1310
		1311	$ARGV
		1312
		1313
		1314	contains the name of the current file when reading from
		1315
		1316
		1317	@ARGV
		1318
		1319
		1320	The array @ARGV contains the command-line arguments
		1321	intended for the script. $#ARGV is generally the
		1322	number of arguments minus one, because $ARGV[[0] is
		1323	the first argument, ''not'' the program's command name
		1324	itself. See $0 for the command name.
		1325
		1326
		1327	@INC
		1328
		1329
		1330	The array @INC contains the list of places that the
		1331	do EXPR, require, or use
		1332	constructs look for their library files. It initially
		1333	consists of the arguments to any __-I__ command-line
		1334	switches, followed by the default Perl library, probably
		1335	''/usr/local/lib/perl'', followed by ``.'', to represent
		1336	the current directory. If you need to modify this at
		1337	runtime, you should use the use lib pragma to get
		1338	the machine-dependent library properly loaded
		1339	also:
		1340
		1341
		1342	use lib '/mypath/libdir/';
2	perry	1343	use !SomeMod;
1	perry	1344
		1345
		1346	@_
		1347
		1348
		1349	Within a subroutine the array @_ contains the
		1350	parameters passed to that subroutine. See
		1351	perlsub.
		1352
		1353
		1354	%INC
		1355
		1356
		1357	The hash %INC contains entries for each filename
		1358	included via the do, require, or
		1359	use operators. The key is the filename you
		1360	specified (with module names converted to pathnames), and
		1361	the value is the location of the file found. The
		1362	require operator uses this hash to determine
		1363	whether a particular file has already been
		1364	included.
		1365
		1366
		1367	%ENV
		1368
		1369
		1370	$ENV{expr}
		1371
		1372
		1373	The hash %ENV contains your current environment.
		1374	Setting a value in ENV changes the environment for
		1375	any child processes you subsequently ''fork()''
		1376	off.
		1377
		1378
		1379	%SIG
		1380
		1381
		1382	$SIG{expr}
		1383
		1384
		1385	The hash %SIG contains signal handlers for signals.
		1386	For example:
		1387
		1388
		1389	sub handler { # 1st argument is signal name
		1390	my($sig) = @_;
		1391	print
		1392	$SIG{'INT'} =
		1393	Using a value of 'IGNORE' usually has the effect of ignoring the signal, except for the CHLD signal. See perlipc for more about this special case.
		1394
		1395
		1396	Here are some other examples:
		1397
		1398
		1399	$SIG{
		1400	Be sure not to use a bareword as the name of a signal handler, lest you inadvertently call it.
		1401
		1402
		1403	If your system has the ''sigaction()'' function then
		1404	signal handlers are installed using it. This means you get
		1405	reliable signal handling. If your system has the
		1406	SA_RESTART flag it is used when signals
		1407	handlers are installed. This means that system calls for
		1408	which restarting is supported continue rather than returning
		1409	when a signal arrives. If you want your system calls to be
		1410	interrupted by signal delivery then do something like
		1411	this:
		1412
		1413
		1414	use POSIX ':signal_h';
		1415	my $alarm = 0;
2	perry	1416	sigaction SIGALRM, new POSIX::!SigAction sub { $alarm = 1 }
1	perry	1417	or die
		1418	See POSIX .
		1419
		1420
		1421	Certain internal hooks can be also set using the
		1422	%SIG hash. The routine indicated by
		1423	$SIG{__WARN__} is called when a warning message is
		1424	about to be printed. The warning message is passed as the
		1425	first argument. The presence of a __WARN__ hook causes the
		1426	ordinary printing of warnings to STDERR to be
		1427	suppressed. You can use this to save warnings in a variable,
		1428	or turn warnings into fatal errors, like this:
		1429
		1430
		1431	local $SIG{__WARN__} = sub { die $_[[0] };
		1432	eval $proggie;
		1433	The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __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 goto, a loop exit, or a ''die()''. The __DIE__ handler is explicitly disabled during the call, so that you can die from a __DIE__ handler. Similarly for __WARN__.
		1434
		1435
		1436	Due to an implementation glitch, the $SIG{__DIE__}
		1437	hook is called even inside an ''eval()''. Do not use this
		1438	to rewrite a pending exception in $@, or as a
		1439	bizarre substitute for overriding
		1440	''CORE::GLOBAL::die()''. This strange action at a
		1441	distance may be fixed in a future release so that
		1442	$SIG{__DIE__} is only called if your program is
		1443	about to exit, as was the original intent. Any other use is
		1444	deprecated.
		1445
		1446
		1447	__DIE__/__WARN__ handlers are very special
		1448	in one respect: they may be called to report (probable)
		1449	errors found by the parser. In such a case the parser may be
		1450	in inconsistent state, so any attempt to evaluate Perl code
		1451	from such a handler will probably result in a segfault. This
		1452	means that warnings or errors that result from parsing Perl
		1453	should be used with extreme caution, like this:
		1454
		1455
		1456	require Carp if defined $^S;
		1457	Carp::confess(
		1458	Here the first line will load Carp ''unless'' it is the parser who called the handler. The second line will print backtrace and die if Carp was available. The third line will be executed only if Carp was not available.
		1459
		1460
		1461	See ``die'' in perlfunc, ``warn'' in perlfunc, ``eval'' in
		1462	perlfunc, and warnings for additional
		1463	information.
		1464
		1465
		1466	__Error Indicators__
		1467
		1468
		1469	The variables $@, $!, $^E, and
		1470	$? contain information about different types of
		1471	error conditions that may appear during execution of a Perl
		1472	program. The variables are shown ordered by the ``distance''
		1473	between the subsystem which reported the error and the Perl
		1474	process. They correspond to errors detected by the Perl
		1475	interpreter, C library, operating system, or an external
		1476	program, respectively.
		1477
		1478
		1479	To illustrate the differences between these variables,
		1480	consider the following Perl expression, which uses a
		1481	single-quoted string:
		1482
		1483
		1484	eval q{
		1485	open PIPE,
		1486	After execution of this statement all 4 variables may have been set.
		1487
		1488
		1489	$@ is set if the string to be eval-ed did
		1490	not compile (this may happen if open or
		1491	close were imported with bad prototypes), or if
		1492	Perl code executed during evaluation ''die()''d . In
		1493	these cases the value of $@ is the compile error, or the
		1494	argument to die (which will interpolate $!
		1495	and $?!). (See also Fatal, though.)
		1496
		1497
		1498	When the ''eval()'' expression above is executed,
		1499	''open()'', , and close are
		1500	translated to calls in the C run-time library and thence to
		1501	the operating system kernel. $! is set to the C
		1502	library's errno if one of these calls
		1503	fails.
		1504
		1505
		1506	Under a few operating systems, $^E may contain a
		1507	more verbose error indicator, such as in this case, ``
		1508	CDROM tray not closed.'' Systems that do not
		1509	support extended error messages leave $^E the same
		1510	as $!.
		1511
		1512
		1513	Finally, $? may be set to non-0 value if the
		1514	external program ''/cdrom/install'' fails. The upper
		1515	eight bits reflect specific error conditions encountered by
		1516	the program (the program's ''exit()'' value). The lower
		1517	eight bits reflect mode of failure, like signal death and
		1518	core dump information See wait(2) for details. In
		1519	contrast to $! and $^E, which are set only
		1520	if error condition is detected, the variable $? is
		1521	set on each wait or pipe close,
		1522	overwriting the old value. This is more like $@,
		1523	which on every ''eval()'' is always set on failure and
		1524	cleared on success.
		1525
		1526
		1527	For more details, see the individual descriptions at
		1528	$@, $!, $^E, and
		1529	$?.
		1530
		1531
		1532	__Technical Note on the Syntax of Variable
		1533	Names__
		1534
		1535
		1536	Variable names in Perl can have several formats. Usually,
		1537	they must begin with a letter or underscore, in which case
		1538	they can be arbitrarily long (up to an internal limit of 251
		1539	characters) and may contain letters, digits, underscores, or
		1540	the special sequence :: or '. In this
		1541	case, the part before the last :: or ' is
		1542	taken to be a ''package qualifier''; see
		1543	perlmod.
		1544
		1545
		1546	Perl variable names may also be a sequence of digits or a
		1547	single punctuation or control character. These names are all
		1548	reserved for special uses by Perl; for example, the
		1549	all-digits names are used to hold data captured by
		1550	backreferences after a regular expression match. Perl has a
		1551	special syntax for the single-control-character names: It
		1552	understands ^X (caret X) to mean the
		1553	control-X character. For example, the notation
		1554	$^W (dollar-sign caret W) is the scalar
		1555	variable whose name is the single character
		1556	control-W. This is better than typing a literal
		1557	control-W into your program.
		1558
		1559
		1560	Finally, new in Perl 5.6, Perl variable names may be
		1561	alphanumeric strings that begin with control characters (or
		1562	better yet, a caret). These variables must be written in the
		1563	form ${^Foo}; the braces are not optional.
		1564	${^Foo} denotes the scalar variable whose name is a
		1565	control-F followed by two o's. These
		1566	variables are reserved for future special uses by Perl,
		1567	except for the ones that begin with ^_
		1568	(control-underscore or caret-underscore). No
		1569	control-character name that begins with ^_ will
		1570	acquire a special meaning in any future version of Perl;
		1571	such names may therefore be used safely in programs.
		1572	$^_ itself, however, ''is''
		1573	reserved.
		1574
		1575
		1576	Perl identifiers that begin with digits, control characters,
		1577	or punctuation characters are exempt from the effects of the
		1578	package declaration and are always forced to be in
		1579	package main. A few other names are also
		1580	exempt:
		1581
		1582
		1583	ENV STDIN
		1584	INC STDOUT
		1585	ARGV STDERR
		1586	ARGVOUT
		1587	SIG
		1588	In particular, the new special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope.
		1589	!!BUGS
		1590
		1591
		1592	Due to an unfortunate accident of Perl's implementation,
		1593	use English imposes a considerable performance
		1594	penalty on all regular expression matches in a program,
		1595	regardless of whether they occur in the scope of use
		1596	English. For that reason, saying use English
		1597	in libraries is strongly discouraged. See the
2	perry	1598	Devel::!SawAmpersand module documentation from
1	perry	1599	CPAN
		1600	(http://www.perl.com/CPAN/modules/by-module/Devel/) for more
		1601	information.
		1602
		1603
		1604	Having to even think about the $^S variable in your
		1605	exception handlers is simply wrong. $SIG{__DIE__}
		1606	as currently implemented invites grievous and difficult to
		1607	track down errors. Avoid it and use an END{} or
		1608	CORE::GLOBAL::die override instead.
		1609	----