1 | =head1 NAME
|
---|
2 |
|
---|
3 | perlintern - autogenerated documentation of purely B<internal>
|
---|
4 | Perl functions
|
---|
5 |
|
---|
6 | =head1 DESCRIPTION
|
---|
7 | X<internal Perl functions> X<interpreter functions>
|
---|
8 |
|
---|
9 | This file is the autogenerated documentation of functions in the
|
---|
10 | Perl interpreter that are documented using Perl's internal documentation
|
---|
11 | format but are not marked as part of the Perl API. In other words,
|
---|
12 | B<they are not for use in extensions>!
|
---|
13 |
|
---|
14 |
|
---|
15 | =head1 CV reference counts and CvOUTSIDE
|
---|
16 |
|
---|
17 | =over 8
|
---|
18 |
|
---|
19 | =item CvWEAKOUTSIDE
|
---|
20 | X<CvWEAKOUTSIDE>
|
---|
21 |
|
---|
22 | Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
|
---|
23 | CV (if any). Because pointers to anonymous sub prototypes are
|
---|
24 | stored in C<&> pad slots, it is a possible to get a circular reference,
|
---|
25 | with the parent pointing to the child and vice-versa. To avoid the
|
---|
26 | ensuing memory leak, we do not increment the reference count of the CV
|
---|
27 | pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
|
---|
28 | has a C<&> pad slot pointing back to us. In this case, we set the
|
---|
29 | C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
|
---|
30 | circumstances we should decrement the refcount of the parent when freeing
|
---|
31 | the child.
|
---|
32 |
|
---|
33 | There is a further complication with non-closure anonymous subs (i.e. those
|
---|
34 | that do not refer to any lexicals outside that sub). In this case, the
|
---|
35 | anonymous prototype is shared rather than being cloned. This has the
|
---|
36 | consequence that the parent may be freed while there are still active
|
---|
37 | children, eg
|
---|
38 |
|
---|
39 | BEGIN { $a = sub { eval '$x' } }
|
---|
40 |
|
---|
41 | In this case, the BEGIN is freed immediately after execution since there
|
---|
42 | are no active references to it: the anon sub prototype has
|
---|
43 | C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
|
---|
44 | CV, so it doesn't contribute to BEGIN's refcount either. When $a is
|
---|
45 | executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
|
---|
46 | and the freed BEGIN is accessed.
|
---|
47 |
|
---|
48 | To avoid this, whenever a CV and its associated pad is freed, any
|
---|
49 | C<&> entries in the pad are explicitly removed from the pad, and if the
|
---|
50 | refcount of the pointed-to anon sub is still positive, then that
|
---|
51 | child's C<CvOUTSIDE> is set to point to its grandparent. This will only
|
---|
52 | occur in the single specific case of a non-closure anon prototype
|
---|
53 | having one or more active references (such as C<$a> above).
|
---|
54 |
|
---|
55 | One other thing to consider is that a CV may be merely undefined
|
---|
56 | rather than freed, eg C<undef &foo>. In this case, its refcount may
|
---|
57 | not have reached zero, but we still delete its pad and its C<CvROOT> etc.
|
---|
58 | Since various children may still have their C<CvOUTSIDE> pointing at this
|
---|
59 | undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
|
---|
60 | the chain of lexical scopes is unbroken. For example, the following
|
---|
61 | should print 123:
|
---|
62 |
|
---|
63 | my $x = 123;
|
---|
64 | sub tmp { sub { eval '$x' } }
|
---|
65 | my $a = tmp();
|
---|
66 | undef &tmp;
|
---|
67 | print $a->();
|
---|
68 |
|
---|
69 | bool CvWEAKOUTSIDE(CV *cv)
|
---|
70 |
|
---|
71 | =for hackers
|
---|
72 | Found in file cv.h
|
---|
73 |
|
---|
74 |
|
---|
75 | =back
|
---|
76 |
|
---|
77 | =head1 Functions in file pad.h
|
---|
78 |
|
---|
79 |
|
---|
80 | =over 8
|
---|
81 |
|
---|
82 | =item CX_CURPAD_SAVE
|
---|
83 | X<CX_CURPAD_SAVE>
|
---|
84 |
|
---|
85 | Save the current pad in the given context block structure.
|
---|
86 |
|
---|
87 | void CX_CURPAD_SAVE(struct context)
|
---|
88 |
|
---|
89 | =for hackers
|
---|
90 | Found in file pad.h
|
---|
91 |
|
---|
92 | =item CX_CURPAD_SV
|
---|
93 | X<CX_CURPAD_SV>
|
---|
94 |
|
---|
95 | Access the SV at offset po in the saved current pad in the given
|
---|
96 | context block structure (can be used as an lvalue).
|
---|
97 |
|
---|
98 | SV * CX_CURPAD_SV(struct context, PADOFFSET po)
|
---|
99 |
|
---|
100 | =for hackers
|
---|
101 | Found in file pad.h
|
---|
102 |
|
---|
103 | =item PAD_BASE_SV
|
---|
104 | X<PAD_BASE_SV>
|
---|
105 |
|
---|
106 | Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
|
---|
107 |
|
---|
108 | SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
|
---|
109 |
|
---|
110 | =for hackers
|
---|
111 | Found in file pad.h
|
---|
112 |
|
---|
113 | =item PAD_CLONE_VARS
|
---|
114 | X<PAD_CLONE_VARS>
|
---|
115 |
|
---|
116 | |CLONE_PARAMS* param
|
---|
117 | Clone the state variables associated with running and compiling pads.
|
---|
118 |
|
---|
119 | void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
|
---|
120 |
|
---|
121 | =for hackers
|
---|
122 | Found in file pad.h
|
---|
123 |
|
---|
124 | =item PAD_COMPNAME_FLAGS
|
---|
125 | X<PAD_COMPNAME_FLAGS>
|
---|
126 |
|
---|
127 | Return the flags for the current compiling pad name
|
---|
128 | at offset C<po>. Assumes a valid slot entry.
|
---|
129 |
|
---|
130 | U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
|
---|
131 |
|
---|
132 | =for hackers
|
---|
133 | Found in file pad.h
|
---|
134 |
|
---|
135 | =item PAD_COMPNAME_GEN
|
---|
136 | X<PAD_COMPNAME_GEN>
|
---|
137 |
|
---|
138 | The generation number of the name at offset C<po> in the current
|
---|
139 | compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
|
---|
140 |
|
---|
141 | STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
|
---|
142 |
|
---|
143 | =for hackers
|
---|
144 | Found in file pad.h
|
---|
145 |
|
---|
146 | =item PAD_COMPNAME_GEN_set
|
---|
147 | X<PAD_COMPNAME_GEN_set>
|
---|
148 |
|
---|
149 | Sets the generation number of the name at offset C<po> in the current
|
---|
150 | ling pad (lvalue) to C<gen>. Note that C<SvCUR_set> is hijacked for this purpose.
|
---|
151 |
|
---|
152 | STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
|
---|
153 |
|
---|
154 | =for hackers
|
---|
155 | Found in file pad.h
|
---|
156 |
|
---|
157 | =item PAD_COMPNAME_OURSTASH
|
---|
158 | X<PAD_COMPNAME_OURSTASH>
|
---|
159 |
|
---|
160 | Return the stash associated with an C<our> variable.
|
---|
161 | Assumes the slot entry is a valid C<our> lexical.
|
---|
162 |
|
---|
163 | HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
|
---|
164 |
|
---|
165 | =for hackers
|
---|
166 | Found in file pad.h
|
---|
167 |
|
---|
168 | =item PAD_COMPNAME_PV
|
---|
169 | X<PAD_COMPNAME_PV>
|
---|
170 |
|
---|
171 | Return the name of the current compiling pad name
|
---|
172 | at offset C<po>. Assumes a valid slot entry.
|
---|
173 |
|
---|
174 | char * PAD_COMPNAME_PV(PADOFFSET po)
|
---|
175 |
|
---|
176 | =for hackers
|
---|
177 | Found in file pad.h
|
---|
178 |
|
---|
179 | =item PAD_COMPNAME_TYPE
|
---|
180 | X<PAD_COMPNAME_TYPE>
|
---|
181 |
|
---|
182 | Return the type (stash) of the current compiling pad name at offset
|
---|
183 | C<po>. Must be a valid name. Returns null if not typed.
|
---|
184 |
|
---|
185 | HV * PAD_COMPNAME_TYPE(PADOFFSET po)
|
---|
186 |
|
---|
187 | =for hackers
|
---|
188 | Found in file pad.h
|
---|
189 |
|
---|
190 | =item PAD_DUP
|
---|
191 | X<PAD_DUP>
|
---|
192 |
|
---|
193 | Clone a padlist.
|
---|
194 |
|
---|
195 | void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
|
---|
196 |
|
---|
197 | =for hackers
|
---|
198 | Found in file pad.h
|
---|
199 |
|
---|
200 | =item PAD_RESTORE_LOCAL
|
---|
201 | X<PAD_RESTORE_LOCAL>
|
---|
202 |
|
---|
203 | Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
|
---|
204 |
|
---|
205 | void PAD_RESTORE_LOCAL(PAD *opad)
|
---|
206 |
|
---|
207 | =for hackers
|
---|
208 | Found in file pad.h
|
---|
209 |
|
---|
210 | =item PAD_SAVE_LOCAL
|
---|
211 | X<PAD_SAVE_LOCAL>
|
---|
212 |
|
---|
213 | Save the current pad to the local variable opad, then make the
|
---|
214 | current pad equal to npad
|
---|
215 |
|
---|
216 | void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
|
---|
217 |
|
---|
218 | =for hackers
|
---|
219 | Found in file pad.h
|
---|
220 |
|
---|
221 | =item PAD_SAVE_SETNULLPAD
|
---|
222 | X<PAD_SAVE_SETNULLPAD>
|
---|
223 |
|
---|
224 | Save the current pad then set it to null.
|
---|
225 |
|
---|
226 | void PAD_SAVE_SETNULLPAD()
|
---|
227 |
|
---|
228 | =for hackers
|
---|
229 | Found in file pad.h
|
---|
230 |
|
---|
231 | =item PAD_SETSV
|
---|
232 | X<PAD_SETSV>
|
---|
233 |
|
---|
234 | Set the slot at offset C<po> in the current pad to C<sv>
|
---|
235 |
|
---|
236 | SV * PAD_SETSV(PADOFFSET po, SV* sv)
|
---|
237 |
|
---|
238 | =for hackers
|
---|
239 | Found in file pad.h
|
---|
240 |
|
---|
241 | =item PAD_SET_CUR
|
---|
242 | X<PAD_SET_CUR>
|
---|
243 |
|
---|
244 | Set the current pad to be pad C<n> in the padlist, saving
|
---|
245 | the previous current pad. NB currently this macro expands to a string too
|
---|
246 | long for some compilers, so it's best to replace it with
|
---|
247 |
|
---|
248 | SAVECOMPPAD();
|
---|
249 | PAD_SET_CUR_NOSAVE(padlist,n);
|
---|
250 |
|
---|
251 |
|
---|
252 | void PAD_SET_CUR(PADLIST padlist, I32 n)
|
---|
253 |
|
---|
254 | =for hackers
|
---|
255 | Found in file pad.h
|
---|
256 |
|
---|
257 | =item PAD_SET_CUR_NOSAVE
|
---|
258 | X<PAD_SET_CUR_NOSAVE>
|
---|
259 |
|
---|
260 | like PAD_SET_CUR, but without the save
|
---|
261 |
|
---|
262 | void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
|
---|
263 |
|
---|
264 | =for hackers
|
---|
265 | Found in file pad.h
|
---|
266 |
|
---|
267 | =item PAD_SV
|
---|
268 | X<PAD_SV>
|
---|
269 |
|
---|
270 | Get the value at offset C<po> in the current pad
|
---|
271 |
|
---|
272 | void PAD_SV(PADOFFSET po)
|
---|
273 |
|
---|
274 | =for hackers
|
---|
275 | Found in file pad.h
|
---|
276 |
|
---|
277 | =item PAD_SVl
|
---|
278 | X<PAD_SVl>
|
---|
279 |
|
---|
280 | Lightweight and lvalue version of C<PAD_SV>.
|
---|
281 | Get or set the value at offset C<po> in the current pad.
|
---|
282 | Unlike C<PAD_SV>, does not print diagnostics with -DX.
|
---|
283 | For internal use only.
|
---|
284 |
|
---|
285 | SV * PAD_SVl(PADOFFSET po)
|
---|
286 |
|
---|
287 | =for hackers
|
---|
288 | Found in file pad.h
|
---|
289 |
|
---|
290 | =item SAVECLEARSV
|
---|
291 | X<SAVECLEARSV>
|
---|
292 |
|
---|
293 | Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
|
---|
294 |
|
---|
295 | void SAVECLEARSV(SV **svp)
|
---|
296 |
|
---|
297 | =for hackers
|
---|
298 | Found in file pad.h
|
---|
299 |
|
---|
300 | =item SAVECOMPPAD
|
---|
301 | X<SAVECOMPPAD>
|
---|
302 |
|
---|
303 | save PL_comppad and PL_curpad
|
---|
304 |
|
---|
305 |
|
---|
306 |
|
---|
307 |
|
---|
308 |
|
---|
309 | void SAVECOMPPAD()
|
---|
310 |
|
---|
311 | =for hackers
|
---|
312 | Found in file pad.h
|
---|
313 |
|
---|
314 | =item SAVEPADSV
|
---|
315 | X<SAVEPADSV>
|
---|
316 |
|
---|
317 | Save a pad slot (used to restore after an iteration)
|
---|
318 |
|
---|
319 | XXX DAPM it would make more sense to make the arg a PADOFFSET
|
---|
320 | void SAVEPADSV(PADOFFSET po)
|
---|
321 |
|
---|
322 | =for hackers
|
---|
323 | Found in file pad.h
|
---|
324 |
|
---|
325 |
|
---|
326 | =back
|
---|
327 |
|
---|
328 | =head1 Functions in file pp_ctl.c
|
---|
329 |
|
---|
330 |
|
---|
331 | =over 8
|
---|
332 |
|
---|
333 | =item find_runcv
|
---|
334 | X<find_runcv>
|
---|
335 |
|
---|
336 | Locate the CV corresponding to the currently executing sub or eval.
|
---|
337 | If db_seqp is non_null, skip CVs that are in the DB package and populate
|
---|
338 | *db_seqp with the cop sequence number at the point that the DB:: code was
|
---|
339 | entered. (allows debuggers to eval in the scope of the breakpoint rather
|
---|
340 | than in the scope of the debugger itself).
|
---|
341 |
|
---|
342 | CV* find_runcv(U32 *db_seqp)
|
---|
343 |
|
---|
344 | =for hackers
|
---|
345 | Found in file pp_ctl.c
|
---|
346 |
|
---|
347 |
|
---|
348 | =back
|
---|
349 |
|
---|
350 | =head1 Global Variables
|
---|
351 |
|
---|
352 | =over 8
|
---|
353 |
|
---|
354 | =item PL_DBsingle
|
---|
355 | X<PL_DBsingle>
|
---|
356 |
|
---|
357 | When Perl is run in debugging mode, with the B<-d> switch, this SV is a
|
---|
358 | boolean which indicates whether subs are being single-stepped.
|
---|
359 | Single-stepping is automatically turned on after every step. This is the C
|
---|
360 | variable which corresponds to Perl's $DB::single variable. See
|
---|
361 | C<PL_DBsub>.
|
---|
362 |
|
---|
363 | SV * PL_DBsingle
|
---|
364 |
|
---|
365 | =for hackers
|
---|
366 | Found in file intrpvar.h
|
---|
367 |
|
---|
368 | =item PL_DBsub
|
---|
369 | X<PL_DBsub>
|
---|
370 |
|
---|
371 | When Perl is run in debugging mode, with the B<-d> switch, this GV contains
|
---|
372 | the SV which holds the name of the sub being debugged. This is the C
|
---|
373 | variable which corresponds to Perl's $DB::sub variable. See
|
---|
374 | C<PL_DBsingle>.
|
---|
375 |
|
---|
376 | GV * PL_DBsub
|
---|
377 |
|
---|
378 | =for hackers
|
---|
379 | Found in file intrpvar.h
|
---|
380 |
|
---|
381 | =item PL_DBtrace
|
---|
382 | X<PL_DBtrace>
|
---|
383 |
|
---|
384 | Trace variable used when Perl is run in debugging mode, with the B<-d>
|
---|
385 | switch. This is the C variable which corresponds to Perl's $DB::trace
|
---|
386 | variable. See C<PL_DBsingle>.
|
---|
387 |
|
---|
388 | SV * PL_DBtrace
|
---|
389 |
|
---|
390 | =for hackers
|
---|
391 | Found in file intrpvar.h
|
---|
392 |
|
---|
393 | =item PL_dowarn
|
---|
394 | X<PL_dowarn>
|
---|
395 |
|
---|
396 | The C variable which corresponds to Perl's $^W warning variable.
|
---|
397 |
|
---|
398 | bool PL_dowarn
|
---|
399 |
|
---|
400 | =for hackers
|
---|
401 | Found in file intrpvar.h
|
---|
402 |
|
---|
403 | =item PL_last_in_gv
|
---|
404 | X<PL_last_in_gv>
|
---|
405 |
|
---|
406 | The GV which was last used for a filehandle input operation. (C<< <FH> >>)
|
---|
407 |
|
---|
408 | GV* PL_last_in_gv
|
---|
409 |
|
---|
410 | =for hackers
|
---|
411 | Found in file thrdvar.h
|
---|
412 |
|
---|
413 | =item PL_ofs_sv
|
---|
414 | X<PL_ofs_sv>
|
---|
415 |
|
---|
416 | The output field separator - C<$,> in Perl space.
|
---|
417 |
|
---|
418 | SV* PL_ofs_sv
|
---|
419 |
|
---|
420 | =for hackers
|
---|
421 | Found in file thrdvar.h
|
---|
422 |
|
---|
423 | =item PL_rs
|
---|
424 | X<PL_rs>
|
---|
425 |
|
---|
426 | The input record separator - C<$/> in Perl space.
|
---|
427 |
|
---|
428 | SV* PL_rs
|
---|
429 |
|
---|
430 | =for hackers
|
---|
431 | Found in file thrdvar.h
|
---|
432 |
|
---|
433 |
|
---|
434 | =back
|
---|
435 |
|
---|
436 | =head1 GV Functions
|
---|
437 |
|
---|
438 | =over 8
|
---|
439 |
|
---|
440 | =item is_gv_magical
|
---|
441 | X<is_gv_magical>
|
---|
442 |
|
---|
443 | Returns C<TRUE> if given the name of a magical GV.
|
---|
444 |
|
---|
445 | Currently only useful internally when determining if a GV should be
|
---|
446 | created even in rvalue contexts.
|
---|
447 |
|
---|
448 | C<flags> is not used at present but available for future extension to
|
---|
449 | allow selecting particular classes of magical variable.
|
---|
450 |
|
---|
451 | Currently assumes that C<name> is NUL terminated (as well as len being valid).
|
---|
452 | This assumption is met by all callers within the perl core, which all pass
|
---|
453 | pointers returned by SvPV.
|
---|
454 |
|
---|
455 | bool is_gv_magical(char *name, STRLEN len, U32 flags)
|
---|
456 |
|
---|
457 | =for hackers
|
---|
458 | Found in file gv.c
|
---|
459 |
|
---|
460 |
|
---|
461 | =back
|
---|
462 |
|
---|
463 | =head1 IO Functions
|
---|
464 |
|
---|
465 | =over 8
|
---|
466 |
|
---|
467 | =item start_glob
|
---|
468 | X<start_glob>
|
---|
469 |
|
---|
470 | Function called by C<do_readline> to spawn a glob (or do the glob inside
|
---|
471 | perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
|
---|
472 | this glob starter is only used by miniperl during the build process.
|
---|
473 | Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
|
---|
474 |
|
---|
475 | PerlIO* start_glob(SV* pattern, IO *io)
|
---|
476 |
|
---|
477 | =for hackers
|
---|
478 | Found in file doio.c
|
---|
479 |
|
---|
480 |
|
---|
481 | =back
|
---|
482 |
|
---|
483 | =head1 Pad Data Structures
|
---|
484 |
|
---|
485 | =over 8
|
---|
486 |
|
---|
487 | =item CvPADLIST
|
---|
488 | X<CvPADLIST>
|
---|
489 |
|
---|
490 | CV's can have CvPADLIST(cv) set to point to an AV.
|
---|
491 |
|
---|
492 | For these purposes "forms" are a kind-of CV, eval""s are too (except they're
|
---|
493 | not callable at will and are always thrown away after the eval"" is done
|
---|
494 | executing).
|
---|
495 |
|
---|
496 | XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
|
---|
497 | but that is really the callers pad (a slot of which is allocated by
|
---|
498 | every entersub).
|
---|
499 |
|
---|
500 | The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
|
---|
501 | is managed "manual" (mostly in pad.c) rather than normal av.c rules.
|
---|
502 | The items in the AV are not SVs as for a normal AV, but other AVs:
|
---|
503 |
|
---|
504 | 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
|
---|
505 | the "static type information" for lexicals.
|
---|
506 |
|
---|
507 | The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
|
---|
508 | depth of recursion into the CV.
|
---|
509 | The 0'th slot of a frame AV is an AV which is @_.
|
---|
510 | other entries are storage for variables and op targets.
|
---|
511 |
|
---|
512 | During compilation:
|
---|
513 | C<PL_comppad_name> is set to the names AV.
|
---|
514 | C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
|
---|
515 | C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
|
---|
516 |
|
---|
517 | During execution, C<PL_comppad> and C<PL_curpad> refer to the live
|
---|
518 | frame of the currently executing sub.
|
---|
519 |
|
---|
520 | Iterating over the names AV iterates over all possible pad
|
---|
521 | items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
|
---|
522 | &PL_sv_undef "names" (see pad_alloc()).
|
---|
523 |
|
---|
524 | Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
|
---|
525 | The rest are op targets/GVs/constants which are statically allocated
|
---|
526 | or resolved at compile time. These don't have names by which they
|
---|
527 | can be looked up from Perl code at run time through eval"" like
|
---|
528 | my/our variables can be. Since they can't be looked up by "name"
|
---|
529 | but only by their index allocated at compile time (which is usually
|
---|
530 | in PL_op->op_targ), wasting a name SV for them doesn't make sense.
|
---|
531 |
|
---|
532 | The SVs in the names AV have their PV being the name of the variable.
|
---|
533 | NV+1..IV inclusive is a range of cop_seq numbers for which the name is
|
---|
534 | valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
|
---|
535 | type. For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
|
---|
536 | stash of the associated global (so that duplicate C<our> declarations in the
|
---|
537 | same package can be detected). SvCUR is sometimes hijacked to
|
---|
538 | store the generation number during compilation.
|
---|
539 |
|
---|
540 | If SvFAKE is set on the name SV then slot in the frame AVs are
|
---|
541 | a REFCNT'ed references to a lexical from "outside". In this case,
|
---|
542 | the name SV does not have a cop_seq range, since it is in scope
|
---|
543 | throughout.
|
---|
544 |
|
---|
545 | If the 'name' is '&' the corresponding entry in frame AV
|
---|
546 | is a CV representing a possible closure.
|
---|
547 | (SvFAKE and name of '&' is not a meaningful combination currently but could
|
---|
548 | become so if C<my sub foo {}> is implemented.)
|
---|
549 |
|
---|
550 | The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
|
---|
551 | and set on scope exit. This allows the 'Variable $x is not available' warning
|
---|
552 | to be generated in evals, such as
|
---|
553 |
|
---|
554 | { my $x = 1; sub f { eval '$x'} } f();
|
---|
555 |
|
---|
556 | AV * CvPADLIST(CV *cv)
|
---|
557 |
|
---|
558 | =for hackers
|
---|
559 | Found in file pad.c
|
---|
560 |
|
---|
561 | =item cv_clone
|
---|
562 | X<cv_clone>
|
---|
563 |
|
---|
564 | Clone a CV: make a new CV which points to the same code etc, but which
|
---|
565 | has a newly-created pad built by copying the prototype pad and capturing
|
---|
566 | any outer lexicals.
|
---|
567 |
|
---|
568 | CV* cv_clone(CV* proto)
|
---|
569 |
|
---|
570 | =for hackers
|
---|
571 | Found in file pad.c
|
---|
572 |
|
---|
573 | =item cv_dump
|
---|
574 | X<cv_dump>
|
---|
575 |
|
---|
576 | dump the contents of a CV
|
---|
577 |
|
---|
578 | void cv_dump(const CV *cv, const char *title)
|
---|
579 |
|
---|
580 | =for hackers
|
---|
581 | Found in file pad.c
|
---|
582 |
|
---|
583 | =item do_dump_pad
|
---|
584 | X<do_dump_pad>
|
---|
585 |
|
---|
586 | Dump the contents of a padlist
|
---|
587 |
|
---|
588 | void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
|
---|
589 |
|
---|
590 | =for hackers
|
---|
591 | Found in file pad.c
|
---|
592 |
|
---|
593 | =item intro_my
|
---|
594 | X<intro_my>
|
---|
595 |
|
---|
596 | "Introduce" my variables to visible status.
|
---|
597 |
|
---|
598 | U32 intro_my()
|
---|
599 |
|
---|
600 | =for hackers
|
---|
601 | Found in file pad.c
|
---|
602 |
|
---|
603 | =item pad_add_anon
|
---|
604 | X<pad_add_anon>
|
---|
605 |
|
---|
606 | Add an anon code entry to the current compiling pad
|
---|
607 |
|
---|
608 | PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
|
---|
609 |
|
---|
610 | =for hackers
|
---|
611 | Found in file pad.c
|
---|
612 |
|
---|
613 | =item pad_add_name
|
---|
614 | X<pad_add_name>
|
---|
615 |
|
---|
616 | Create a new name in the current pad at the specified offset.
|
---|
617 | If C<typestash> is valid, the name is for a typed lexical; set the
|
---|
618 | name's stash to that value.
|
---|
619 | If C<ourstash> is valid, it's an our lexical, set the name's
|
---|
620 | GvSTASH to that value
|
---|
621 |
|
---|
622 | Also, if the name is @.. or %.., create a new array or hash for that slot
|
---|
623 |
|
---|
624 | If fake, it means we're cloning an existing entry
|
---|
625 |
|
---|
626 | PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
|
---|
627 |
|
---|
628 | =for hackers
|
---|
629 | Found in file pad.c
|
---|
630 |
|
---|
631 | =item pad_alloc
|
---|
632 | X<pad_alloc>
|
---|
633 |
|
---|
634 | Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
|
---|
635 | the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
|
---|
636 | for a slot which has no name and no active value.
|
---|
637 |
|
---|
638 | PADOFFSET pad_alloc(I32 optype, U32 tmptype)
|
---|
639 |
|
---|
640 | =for hackers
|
---|
641 | Found in file pad.c
|
---|
642 |
|
---|
643 | =item pad_block_start
|
---|
644 | X<pad_block_start>
|
---|
645 |
|
---|
646 | Update the pad compilation state variables on entry to a new block
|
---|
647 |
|
---|
648 | void pad_block_start(int full)
|
---|
649 |
|
---|
650 | =for hackers
|
---|
651 | Found in file pad.c
|
---|
652 |
|
---|
653 | =item pad_check_dup
|
---|
654 | X<pad_check_dup>
|
---|
655 |
|
---|
656 | Check for duplicate declarations: report any of:
|
---|
657 | * a my in the current scope with the same name;
|
---|
658 | * an our (anywhere in the pad) with the same name and the same stash
|
---|
659 | as C<ourstash>
|
---|
660 | C<is_our> indicates that the name to check is an 'our' declaration
|
---|
661 |
|
---|
662 | void pad_check_dup(char* name, bool is_our, HV* ourstash)
|
---|
663 |
|
---|
664 | =for hackers
|
---|
665 | Found in file pad.c
|
---|
666 |
|
---|
667 | =item pad_findlex
|
---|
668 | X<pad_findlex>
|
---|
669 |
|
---|
670 | Find a named lexical anywhere in a chain of nested pads. Add fake entries
|
---|
671 | in the inner pads if it's found in an outer one. innercv is the CV *inside*
|
---|
672 | the chain of outer CVs to be searched. If newoff is non-null, this is a
|
---|
673 | run-time cloning: don't add fake entries, just find the lexical and add a
|
---|
674 | ref to it at newoff in the current pad.
|
---|
675 |
|
---|
676 | PADOFFSET pad_findlex(const char* name, PADOFFSET newoff, const CV* innercv)
|
---|
677 |
|
---|
678 | =for hackers
|
---|
679 | Found in file pad.c
|
---|
680 |
|
---|
681 | =item pad_findmy
|
---|
682 | X<pad_findmy>
|
---|
683 |
|
---|
684 | Given a lexical name, try to find its offset, first in the current pad,
|
---|
685 | or failing that, in the pads of any lexically enclosing subs (including
|
---|
686 | the complications introduced by eval). If the name is found in an outer pad,
|
---|
687 | then a fake entry is added to the current pad.
|
---|
688 | Returns the offset in the current pad, or NOT_IN_PAD on failure.
|
---|
689 |
|
---|
690 | PADOFFSET pad_findmy(char* name)
|
---|
691 |
|
---|
692 | =for hackers
|
---|
693 | Found in file pad.c
|
---|
694 |
|
---|
695 | =item pad_fixup_inner_anons
|
---|
696 | X<pad_fixup_inner_anons>
|
---|
697 |
|
---|
698 | For any anon CVs in the pad, change CvOUTSIDE of that CV from
|
---|
699 | old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
|
---|
700 | moved to a pre-existing CV struct.
|
---|
701 |
|
---|
702 | void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
|
---|
703 |
|
---|
704 | =for hackers
|
---|
705 | Found in file pad.c
|
---|
706 |
|
---|
707 | =item pad_free
|
---|
708 | X<pad_free>
|
---|
709 |
|
---|
710 | Free the SV at offset po in the current pad.
|
---|
711 |
|
---|
712 | void pad_free(PADOFFSET po)
|
---|
713 |
|
---|
714 | =for hackers
|
---|
715 | Found in file pad.c
|
---|
716 |
|
---|
717 | =item pad_leavemy
|
---|
718 | X<pad_leavemy>
|
---|
719 |
|
---|
720 | Cleanup at end of scope during compilation: set the max seq number for
|
---|
721 | lexicals in this scope and warn of any lexicals that never got introduced.
|
---|
722 |
|
---|
723 | void pad_leavemy()
|
---|
724 |
|
---|
725 | =for hackers
|
---|
726 | Found in file pad.c
|
---|
727 |
|
---|
728 | =item pad_new
|
---|
729 | X<pad_new>
|
---|
730 |
|
---|
731 | Create a new compiling padlist, saving and updating the various global
|
---|
732 | vars at the same time as creating the pad itself. The following flags
|
---|
733 | can be OR'ed together:
|
---|
734 |
|
---|
735 | padnew_CLONE this pad is for a cloned CV
|
---|
736 | padnew_SAVE save old globals
|
---|
737 | padnew_SAVESUB also save extra stuff for start of sub
|
---|
738 |
|
---|
739 | PADLIST* pad_new(int flags)
|
---|
740 |
|
---|
741 | =for hackers
|
---|
742 | Found in file pad.c
|
---|
743 |
|
---|
744 | =item pad_push
|
---|
745 | X<pad_push>
|
---|
746 |
|
---|
747 | Push a new pad frame onto the padlist, unless there's already a pad at
|
---|
748 | this depth, in which case don't bother creating a new one.
|
---|
749 | If has_args is true, give the new pad an @_ in slot zero.
|
---|
750 |
|
---|
751 | void pad_push(PADLIST *padlist, int depth, int has_args)
|
---|
752 |
|
---|
753 | =for hackers
|
---|
754 | Found in file pad.c
|
---|
755 |
|
---|
756 | =item pad_reset
|
---|
757 | X<pad_reset>
|
---|
758 |
|
---|
759 | Mark all the current temporaries for reuse
|
---|
760 |
|
---|
761 | void pad_reset()
|
---|
762 |
|
---|
763 | =for hackers
|
---|
764 | Found in file pad.c
|
---|
765 |
|
---|
766 | =item pad_setsv
|
---|
767 | X<pad_setsv>
|
---|
768 |
|
---|
769 | Set the entry at offset po in the current pad to sv.
|
---|
770 | Use the macro PAD_SETSV() rather than calling this function directly.
|
---|
771 |
|
---|
772 | void pad_setsv(PADOFFSET po, SV* sv)
|
---|
773 |
|
---|
774 | =for hackers
|
---|
775 | Found in file pad.c
|
---|
776 |
|
---|
777 | =item pad_swipe
|
---|
778 | X<pad_swipe>
|
---|
779 |
|
---|
780 | Abandon the tmp in the current pad at offset po and replace with a
|
---|
781 | new one.
|
---|
782 |
|
---|
783 | void pad_swipe(PADOFFSET po, bool refadjust)
|
---|
784 |
|
---|
785 | =for hackers
|
---|
786 | Found in file pad.c
|
---|
787 |
|
---|
788 | =item pad_tidy
|
---|
789 | X<pad_tidy>
|
---|
790 |
|
---|
791 | Tidy up a pad after we've finished compiling it:
|
---|
792 | * remove most stuff from the pads of anonsub prototypes;
|
---|
793 | * give it a @_;
|
---|
794 | * mark tmps as such.
|
---|
795 |
|
---|
796 | void pad_tidy(padtidy_type type)
|
---|
797 |
|
---|
798 | =for hackers
|
---|
799 | Found in file pad.c
|
---|
800 |
|
---|
801 | =item pad_undef
|
---|
802 | X<pad_undef>
|
---|
803 |
|
---|
804 | Free the padlist associated with a CV.
|
---|
805 | If parts of it happen to be current, we null the relevant
|
---|
806 | PL_*pad* global vars so that we don't have any dangling references left.
|
---|
807 | We also repoint the CvOUTSIDE of any about-to-be-orphaned
|
---|
808 | inner subs to the outer of this cv.
|
---|
809 |
|
---|
810 | (This function should really be called pad_free, but the name was already
|
---|
811 | taken)
|
---|
812 |
|
---|
813 | void pad_undef(CV* cv)
|
---|
814 |
|
---|
815 | =for hackers
|
---|
816 | Found in file pad.c
|
---|
817 |
|
---|
818 |
|
---|
819 | =back
|
---|
820 |
|
---|
821 | =head1 Stack Manipulation Macros
|
---|
822 |
|
---|
823 | =over 8
|
---|
824 |
|
---|
825 | =item djSP
|
---|
826 | X<djSP>
|
---|
827 |
|
---|
828 | Declare Just C<SP>. This is actually identical to C<dSP>, and declares
|
---|
829 | a local copy of perl's stack pointer, available via the C<SP> macro.
|
---|
830 | See C<SP>. (Available for backward source code compatibility with the
|
---|
831 | old (Perl 5.005) thread model.)
|
---|
832 |
|
---|
833 | djSP;
|
---|
834 |
|
---|
835 | =for hackers
|
---|
836 | Found in file pp.h
|
---|
837 |
|
---|
838 | =item LVRET
|
---|
839 | X<LVRET>
|
---|
840 |
|
---|
841 | True if this op will be the return value of an lvalue subroutine
|
---|
842 |
|
---|
843 | =for hackers
|
---|
844 | Found in file pp.h
|
---|
845 |
|
---|
846 |
|
---|
847 | =back
|
---|
848 |
|
---|
849 | =head1 SV Manipulation Functions
|
---|
850 |
|
---|
851 | =over 8
|
---|
852 |
|
---|
853 | =item report_uninit
|
---|
854 | X<report_uninit>
|
---|
855 |
|
---|
856 | Print appropriate "Use of uninitialized variable" warning
|
---|
857 |
|
---|
858 | void report_uninit()
|
---|
859 |
|
---|
860 | =for hackers
|
---|
861 | Found in file sv.c
|
---|
862 |
|
---|
863 | =item sv_add_arena
|
---|
864 | X<sv_add_arena>
|
---|
865 |
|
---|
866 | Given a chunk of memory, link it to the head of the list of arenas,
|
---|
867 | and split it into a list of free SVs.
|
---|
868 |
|
---|
869 | void sv_add_arena(char* ptr, U32 size, U32 flags)
|
---|
870 |
|
---|
871 | =for hackers
|
---|
872 | Found in file sv.c
|
---|
873 |
|
---|
874 | =item sv_clean_all
|
---|
875 | X<sv_clean_all>
|
---|
876 |
|
---|
877 | Decrement the refcnt of each remaining SV, possibly triggering a
|
---|
878 | cleanup. This function may have to be called multiple times to free
|
---|
879 | SVs which are in complex self-referential hierarchies.
|
---|
880 |
|
---|
881 | I32 sv_clean_all()
|
---|
882 |
|
---|
883 | =for hackers
|
---|
884 | Found in file sv.c
|
---|
885 |
|
---|
886 | =item sv_clean_objs
|
---|
887 | X<sv_clean_objs>
|
---|
888 |
|
---|
889 | Attempt to destroy all objects not yet freed
|
---|
890 |
|
---|
891 | void sv_clean_objs()
|
---|
892 |
|
---|
893 | =for hackers
|
---|
894 | Found in file sv.c
|
---|
895 |
|
---|
896 | =item sv_free_arenas
|
---|
897 | X<sv_free_arenas>
|
---|
898 |
|
---|
899 | Deallocate the memory used by all arenas. Note that all the individual SV
|
---|
900 | heads and bodies within the arenas must already have been freed.
|
---|
901 |
|
---|
902 | void sv_free_arenas()
|
---|
903 |
|
---|
904 | =for hackers
|
---|
905 | Found in file sv.c
|
---|
906 |
|
---|
907 |
|
---|
908 | =back
|
---|
909 |
|
---|
910 | =head1 AUTHORS
|
---|
911 |
|
---|
912 | The autodocumentation system was originally added to the Perl core by
|
---|
913 | Benjamin Stuhl. Documentation is by whoever was kind enough to
|
---|
914 | document their functions.
|
---|
915 |
|
---|
916 | =head1 SEE ALSO
|
---|
917 |
|
---|
918 | perlguts(1), perlapi(1)
|
---|
919 |
|
---|