Update Changes.
[p5sagit/p5-mst-13.2.git] / pod / perlintern.pod
CommitLineData
954c1994 1=head1 NAME
2
1c846c1f 3perlintern - autogenerated documentation of purely B<internal>
954c1994 4 Perl functions
5
6=head1 DESCRIPTION
7
1c846c1f 8This file is the autogenerated documentation of functions in the
4375e838 9Perl interpreter that are documented using Perl's internal documentation
1c846c1f 10format but are not marked as part of the Perl API. In other words,
954c1994 11B<they are not for use in extensions>!
12
a8586c98 13
a4f1a029 14=head1 Global Variables
78f9721b 15
a4f1a029 16=over 8
78f9721b 17
2eb25c99 18=item PL_DBsingle
19
20When Perl is run in debugging mode, with the B<-d> switch, this SV is a
21boolean which indicates whether subs are being single-stepped.
22Single-stepping is automatically turned on after every step. This is the C
23variable which corresponds to Perl's $DB::single variable. See
24C<PL_DBsub>.
25
26 SV * PL_DBsingle
27
28=for hackers
29Found in file intrpvar.h
30
31=item PL_DBsub
32
33When Perl is run in debugging mode, with the B<-d> switch, this GV contains
34the SV which holds the name of the sub being debugged. This is the C
35variable which corresponds to Perl's $DB::sub variable. See
36C<PL_DBsingle>.
37
38 GV * PL_DBsub
39
40=for hackers
41Found in file intrpvar.h
42
43=item PL_DBtrace
44
45Trace variable used when Perl is run in debugging mode, with the B<-d>
46switch. This is the C variable which corresponds to Perl's $DB::trace
47variable. See C<PL_DBsingle>.
48
49 SV * PL_DBtrace
50
51=for hackers
52Found in file intrpvar.h
53
54=item PL_dowarn
55
56The C variable which corresponds to Perl's $^W warning variable.
57
58 bool PL_dowarn
59
60=for hackers
61Found in file intrpvar.h
62
63=item PL_last_in_gv
64
65The GV which was last used for a filehandle input operation. (C<< <FH> >>)
66
67 GV* PL_last_in_gv
68
69=for hackers
70Found in file thrdvar.h
71
72=item PL_ofs_sv
73
74The output field separator - C<$,> in Perl space.
75
76 SV* PL_ofs_sv
77
78=for hackers
79Found in file thrdvar.h
80
81=item PL_rs
82
83The input record separator - C<$/> in Perl space.
84
85 SV* PL_rs
86
87=for hackers
88Found in file thrdvar.h
89
645c22ef 90
a4f1a029 91=back
645c22ef 92
a4f1a029 93=head1 GV Functions
94
95=over 8
96
97=item is_gv_magical
98
99Returns C<TRUE> if given the name of a magical GV.
100
101Currently only useful internally when determining if a GV should be
102created even in rvalue contexts.
103
104C<flags> is not used at present but available for future extension to
105allow selecting particular classes of magical variable.
106
107 bool is_gv_magical(char *name, STRLEN len, U32 flags)
645c22ef 108
109=for hackers
a4f1a029 110Found in file gv.c
111
112
113=back
114
115=head1 IO Functions
116
117=over 8
645c22ef 118
a8586c98 119=item start_glob
120
121Function called by C<do_readline> to spawn a glob (or do the glob inside
122perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
bd16a5f0 123this glob starter is only used by miniperl during the build process.
a8586c98 124Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
125
126 PerlIO* start_glob(SV* pattern, IO *io)
127
128=for hackers
129Found in file doio.c
130
a4f1a029 131
132=back
133
134=head1 Pad Data Structures
135
136=over 8
137
138=item CvPADLIST
139
140CV's can have CvPADLIST(cv) set to point to an AV.
141
142For these purposes "forms" are a kind-of CV, eval""s are too (except they're
143not callable at will and are always thrown away after the eval"" is done
144executing).
145
146XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
147but that is really the callers pad (a slot of which is allocated by
148every entersub).
149
150The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
151is managed "manual" (mostly in op.c) rather than normal av.c rules.
152The items in the AV are not SVs as for a normal AV, but other AVs:
153
1540'th Entry of the CvPADLIST is an AV which represents the "names" or rather
155the "static type information" for lexicals.
156
157The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
158depth of recursion into the CV.
159The 0'th slot of a frame AV is an AV which is @_.
160other entries are storage for variables and op targets.
161
162During compilation:
163C<PL_comppad_name> is set the the the names AV.
164C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
165C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
166
167Itterating over the names AV itterates over all possible pad
168items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
169&PL_sv_undef "names" (see pad_alloc()).
170
171Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
172The rest are op targets/GVs/constants which are statically allocated
173or resolved at compile time. These don't have names by which they
174can be looked up from Perl code at run time through eval"" like
175my/our variables can be. Since they can't be looked up by "name"
176but only by their index allocated at compile time (which is usually
177in PL_op->op_targ), wasting a name SV for them doesn't make sense.
178
179The SVs in the names AV have their PV being the name of the variable.
180NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid.
181For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type.
182
183If SvFAKE is set on the name SV then slot in the frame AVs are
184a REFCNT'ed references to a lexical from "outside".
185
186If the 'name' is '&' the the corresponding entry in frame AV
187is a CV representing a possible closure.
188(SvFAKE and name of '&' is not a meaningful combination currently but could
189become so if C<my sub foo {}> is implemented.)
190
191 AV * CvPADLIST(CV *cv)
192
193=for hackers
194Found in file cv.h
195
196
197=back
198
199=head1 Stack Manipulation Macros
200
201=over 8
202
203=item djSP
204
205Declare Just C<SP>. This is actually identical to C<dSP>, and declares
206a local copy of perl's stack pointer, available via the C<SP> macro.
207See C<SP>. (Available for backward source code compatibility with the
208old (Perl 5.005) thread model.)
209
210 djSP;
211
212=for hackers
213Found in file pp.h
214
215=item LVRET
216
217True if this op will be the return value of an lvalue subroutine
218
219=for hackers
220Found in file pp.h
221
222
223=back
224
225=head1 SV Manipulation Functions
226
227=over 8
228
229=item report_uninit
230
231Print appropriate "Use of uninitialized variable" warning
232
233 void report_uninit()
234
235=for hackers
236Found in file sv.c
237
645c22ef 238=item sv_add_arena
239
240Given a chunk of memory, link it to the head of the list of arenas,
241and split it into a list of free SVs.
242
243 void sv_add_arena(char* ptr, U32 size, U32 flags)
244
245=for hackers
246Found in file sv.c
247
248=item sv_clean_all
249
250Decrement the refcnt of each remaining SV, possibly triggering a
251cleanup. This function may have to be called multiple times to free
8fb26106 252SVs which are in complex self-referential hierarchies.
645c22ef 253
254 I32 sv_clean_all()
255
256=for hackers
257Found in file sv.c
258
259=item sv_clean_objs
260
261Attempt to destroy all objects not yet freed
262
263 void sv_clean_objs()
264
265=for hackers
266Found in file sv.c
267
268=item sv_free_arenas
269
270Deallocate the memory used by all arenas. Note that all the individual SV
271heads and bodies within the arenas must already have been freed.
272
273 void sv_free_arenas()
274
275=for hackers
276Found in file sv.c
277
a4f1a029 278
954c1994 279=back
280
281=head1 AUTHORS
282
1c846c1f 283The autodocumentation system was originally added to the Perl core by
284Benjamin Stuhl. Documentation is by whoever was kind enough to
954c1994 285document their functions.
286
287=head1 SEE ALSO
288
289perlguts(1), perlapi(1)
290