[perl5.git] / pod / perlintern.pod

=head1 NAME

perlintern - autogenerated documentation of purely B<internal>
		 Perl functions

=head1 DESCRIPTION

This file is the autogenerated documentation of functions in the
Perl interpreter that are documented using Perl's internal documentation
format but are not marked as part of the Perl API. In other words,
B<they are not for use in extensions>!

=over 8

=item djSP

Declare Just C<SP>. This is actually identical to C<dSP>, and declares
a local copy of perl's stack pointer, available via the C<SP> macro.
See C<SP>.  (Available for backward source code compatibility with the
old (Perl 5.005) thread model.)

		djSP;

=for hackers
Found in file pp.h

=item is_gv_magical

Returns C<TRUE> if given the name of a magical GV.

Currently only useful internally when determining if a GV should be
created even in rvalue contexts.

C<flags> is not used at present but available for future extension to
allow selecting particular classes of magical variable.

	bool	is_gv_magical(char *name, STRLEN len, U32 flags)

=for hackers
Found in file gv.c

=item LVRET

True if this op will be the return value of an lvalue subroutine

=for hackers
Found in file pp.h

=item PL_DBsingle

When Perl is run in debugging mode, with the B<-d> switch, this SV is a
boolean which indicates whether subs are being single-stepped.
Single-stepping is automatically turned on after every step.  This is the C
variable which corresponds to Perl's $DB::single variable.  See
C<PL_DBsub>.

	SV *	PL_DBsingle

=for hackers
Found in file intrpvar.h

=item PL_DBsub

When Perl is run in debugging mode, with the B<-d> switch, this GV contains
the SV which holds the name of the sub being debugged.  This is the C
variable which corresponds to Perl's $DB::sub variable.  See
C<PL_DBsingle>.

	GV *	PL_DBsub

=for hackers
Found in file intrpvar.h

=item PL_DBtrace

Trace variable used when Perl is run in debugging mode, with the B<-d>
switch.  This is the C variable which corresponds to Perl's $DB::trace
variable.  See C<PL_DBsingle>.

	SV *	PL_DBtrace

=for hackers
Found in file intrpvar.h

=item PL_dowarn

The C variable which corresponds to Perl's $^W warning variable.

	bool	PL_dowarn

=for hackers
Found in file intrpvar.h

=item PL_last_in_gv

The GV which was last used for a filehandle input operation. (C<< <FH> >>)

	GV*	PL_last_in_gv

=for hackers
Found in file thrdvar.h

=item PL_ofs_sv

The output field separator - C<$,> in Perl space.

	SV*	PL_ofs_sv

=for hackers
Found in file thrdvar.h

=item PL_rs

The input record separator - C<$/> in Perl space.

	SV*	PL_rs

=for hackers
Found in file thrdvar.h

=item report_uninit

Print appropriate "Use of uninitialized variable" warning

	void	report_uninit()

=for hackers
Found in file sv.c

=item start_glob

Function called by C<do_readline> to spawn a glob (or do the glob inside
perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
this glob starter is only used by miniperl during the build process.
Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.

	PerlIO*	start_glob(SV* pattern, IO *io)

=for hackers
Found in file doio.c

=item sv_add_arena

Given a chunk of memory, link it to the head of the list of arenas,
and split it into a list of free SVs.

	void	sv_add_arena(char* ptr, U32 size, U32 flags)

=for hackers
Found in file sv.c

=item sv_clean_all

Decrement the refcnt of each remaining SV, possibly triggering a
cleanup. This function may have to be called multiple times to free
SVs which are in complex self-referential hierarchies.

	I32	sv_clean_all()

=for hackers
Found in file sv.c

=item sv_clean_objs

Attempt to destroy all objects not yet freed

	void	sv_clean_objs()

=for hackers
Found in file sv.c

=item sv_free_arenas

Deallocate the memory used by all arenas. Note that all the individual SV
heads and bodies within the arenas must already have been freed.

	void	sv_free_arenas()

=for hackers
Found in file sv.c

=back

=head1 AUTHORS

The autodocumentation system was originally added to the Perl core by
Benjamin Stuhl. Documentation is by whoever was kind enough to
document their functions.

=head1 SEE ALSO

perlguts(1), perlapi(1)
Commit	Line	Data
954c1994 GS	1	=head1 NAME
954c1994 GS	2
1c846c1f	3	perlintern - autogenerated documentation of purely B<internal>
954c1994 GS	4	Perl functions
	5
	6	=head1 DESCRIPTION
	7
1c846c1f	8	This file is the autogenerated documentation of functions in the
4375e838	9	Perl interpreter that are documented using Perl's internal documentation
1c846c1f	10	format but are not marked as part of the Perl API. In other words,
954c1994 GS	11	B<they are not for use in extensions>!
	12
	13	=over 8
	14
a8586c98 JH	15	=item djSP
	16
	17	Declare Just C<SP>. This is actually identical to C<dSP>, and declares
	18	a local copy of perl's stack pointer, available via the C<SP> macro.
	19	See C<SP>. (Available for backward source code compatibility with the
	20	old (Perl 5.005) thread model.)
	21
	22	djSP;
	23
	24	=for hackers
	25	Found in file pp.h
	26
c9d5ac95 GS	27	=item is_gv_magical
	28
	29	Returns C<TRUE> if given the name of a magical GV.
	30
	31	Currently only useful internally when determining if a GV should be
	32	created even in rvalue contexts.
	33
	34	C<flags> is not used at present but available for future extension to
	35	allow selecting particular classes of magical variable.
	36
	37	bool is_gv_magical(char *name, STRLEN len, U32 flags)
	38
497711e7 GS	39	=for hackers
	40	Found in file gv.c
	41
78f9721b SM	42	=item LVRET
	43
	44	True if this op will be the return value of an lvalue subroutine
	45
	46	=for hackers
	47	Found in file pp.h
	48
2eb25c99 JH	49	=item PL_DBsingle
	50
	51	When Perl is run in debugging mode, with the B<-d> switch, this SV is a
	52	boolean which indicates whether subs are being single-stepped.
	53	Single-stepping is automatically turned on after every step. This is the C
	54	variable which corresponds to Perl's $DB::single variable. See
	55	C<PL_DBsub>.
	56
	57	SV * PL_DBsingle
	58
	59	=for hackers
	60	Found in file intrpvar.h
	61
	62	=item PL_DBsub
	63
	64	When Perl is run in debugging mode, with the B<-d> switch, this GV contains
	65	the SV which holds the name of the sub being debugged. This is the C
	66	variable which corresponds to Perl's $DB::sub variable. See
	67	C<PL_DBsingle>.
	68
	69	GV * PL_DBsub
	70
	71	=for hackers
	72	Found in file intrpvar.h
	73
	74	=item PL_DBtrace
	75
	76	Trace variable used when Perl is run in debugging mode, with the B<-d>
	77	switch. This is the C variable which corresponds to Perl's $DB::trace
	78	variable. See C<PL_DBsingle>.
	79
	80	SV * PL_DBtrace
	81
	82	=for hackers
	83	Found in file intrpvar.h
	84
	85	=item PL_dowarn
	86
	87	The C variable which corresponds to Perl's $^W warning variable.
	88
	89	bool PL_dowarn
	90
	91	=for hackers
	92	Found in file intrpvar.h
	93
	94	=item PL_last_in_gv
	95
	96	The GV which was last used for a filehandle input operation. (C<< <FH> >>)
	97
	98	GV* PL_last_in_gv
	99
	100	=for hackers
	101	Found in file thrdvar.h
	102
	103	=item PL_ofs_sv
	104
	105	The output field separator - C<$,> in Perl space.
	106
	107	SV* PL_ofs_sv
	108
	109	=for hackers
	110	Found in file thrdvar.h
	111
	112	=item PL_rs
113
114	The input record separator - C<$/> in Perl space.
115
116	SV* PL_rs
117
118	=for hackers
119	Found in file thrdvar.h
120
645c22ef DM	121	=item report_uninit
	122
	123	Print appropriate "Use of uninitialized variable" warning
	124
	125	void report_uninit()
	126
	127	=for hackers
	128	Found in file sv.c
	129
a8586c98 JH	130	=item start_glob
	131
	132	Function called by C<do_readline> to spawn a glob (or do the glob inside
	133	perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
bd16a5f0	134	this glob starter is only used by miniperl during the build process.
a8586c98 JH	135	Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
	136
	137	PerlIO* start_glob(SV* pattern, IO *io)
	138
	139	=for hackers
	140	Found in file doio.c
	141
645c22ef DM	142	=item sv_add_arena
	143
	144	Given a chunk of memory, link it to the head of the list of arenas,
	145	and split it into a list of free SVs.
	146
	147	void sv_add_arena(char* ptr, U32 size, U32 flags)
	148
	149	=for hackers
	150	Found in file sv.c
	151
	152	=item sv_clean_all
	153
	154	Decrement the refcnt of each remaining SV, possibly triggering a
	155	cleanup. This function may have to be called multiple times to free
8fb26106	156	SVs which are in complex self-referential hierarchies.
645c22ef DM	157
	158	I32 sv_clean_all()
	159
	160	=for hackers
	161	Found in file sv.c
	162
	163	=item sv_clean_objs
	164
	165	Attempt to destroy all objects not yet freed
	166
	167	void sv_clean_objs()
	168
	169	=for hackers
	170	Found in file sv.c
	171
	172	=item sv_free_arenas
	173
	174	Deallocate the memory used by all arenas. Note that all the individual SV
	175	heads and bodies within the arenas must already have been freed.
	176
	177	void sv_free_arenas()
	178
	179	=for hackers
	180	Found in file sv.c
	181
954c1994 GS	182	=back
	183
	184	=head1 AUTHORS
	185
1c846c1f NIS	186	The autodocumentation system was originally added to the Perl core by
1c846c1f NIS	187	Benjamin Stuhl. Documentation is by whoever was kind enough to
954c1994 GS	188	document their functions.
	189
	190	=head1 SEE ALSO
	191
	192	perlguts(1), perlapi(1)
	193