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