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