This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
eliminate PL_reg_re
[perl5.git] / pod / perlintern.pod
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(const char *name, STRLEN len, U32 flags)
456
457 =for hackers
458 Found in file gv.c
459
460 =item is_gv_magical_sv
461 X<is_gv_magical_sv>
462
463 Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical.
464
465         bool    is_gv_magical_sv(SV *name, U32 flags)
466
467 =for hackers
468 Found in file gv.c
469
470
471 =back
472
473 =head1 Hash Manipulation Functions
474
475 =over 8
476
477 =item refcounted_he_chain_2hv
478 X<refcounted_he_chain_2hv>
479
480 Generates an returns a C<HV *> by walking up the tree starting at the passed
481 in C<struct refcounted_he *>.
482
483         HV *    refcounted_he_chain_2hv(const struct refcounted_he *c)
484
485 =for hackers
486 Found in file hv.c
487
488 =item refcounted_he_free
489 X<refcounted_he_free>
490
491 Decrements the reference count of the passed in C<struct refcounted_he *>
492 by one. If the reference count reaches zero the structure's memory is freed,
493 and C<refcounted_he_free> iterates onto the parent node.
494
495         void    refcounted_he_free(struct refcounted_he *he)
496
497 =for hackers
498 Found in file hv.c
499
500 =item refcounted_he_new
501 X<refcounted_he_new>
502
503 Creates a new C<struct refcounted_he>. Assumes ownership of one reference
504 to I<value>. As S<key> is copied into a shared hash key, all references remain
505 the property of the caller. The C<struct refcounted_he> is returned with a
506 reference count of 1.
507
508         struct refcounted_he *  refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value)
509
510 =for hackers
511 Found in file hv.c
512
513
514 =back
515
516 =head1 IO Functions
517
518 =over 8
519
520 =item start_glob
521 X<start_glob>
522
523 Function called by C<do_readline> to spawn a glob (or do the glob inside
524 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
525 this glob starter is only used by miniperl during the build process.
526 Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
527
528         PerlIO* start_glob(SV* pattern, IO *io)
529
530 =for hackers
531 Found in file doio.c
532
533
534 =back
535
536 =head1 Magical Functions
537
538 =over 8
539
540 =item magic_sethint
541 X<magic_sethint>
542
543 Triggered by a delete from %^H, records the key to C<PL_compiling.cop_hints>.
544
545         int     magic_sethint(SV* sv, MAGIC* mg)
546
547 =for hackers
548 Found in file mg.c
549
550 =item mg_localize
551 X<mg_localize>
552
553 Copy some of the magic from an existing SV to new localized version of
554 that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic
555 doesn't (eg taint, pos).
556
557         void    mg_localize(SV* sv, SV* nsv)
558
559 =for hackers
560 Found in file mg.c
561
562
563 =back
564
565 =head1 Pad Data Structures
566
567 =over 8
568
569 =item CvPADLIST
570 X<CvPADLIST>
571
572 CV's can have CvPADLIST(cv) set to point to an AV.
573
574 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
575 not callable at will and are always thrown away after the eval"" is done
576 executing). Require'd files are simply evals without any outer lexical
577 scope.
578
579 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
580 but that is really the callers pad (a slot of which is allocated by
581 every entersub).
582
583 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
584 is managed "manual" (mostly in pad.c) rather than normal av.c rules.
585 The items in the AV are not SVs as for a normal AV, but other AVs:
586
587 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
588 the "static type information" for lexicals.
589
590 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
591 depth of recursion into the CV.
592 The 0'th slot of a frame AV is an AV which is @_.
593 other entries are storage for variables and op targets.
594
595 During compilation:
596 C<PL_comppad_name> is set to the names AV.
597 C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
598 C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
599
600 During execution, C<PL_comppad> and C<PL_curpad> refer to the live
601 frame of the currently executing sub.
602
603 Iterating over the names AV iterates over all possible pad
604 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
605 &PL_sv_undef "names" (see pad_alloc()).
606
607 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
608 The rest are op targets/GVs/constants which are statically allocated
609 or resolved at compile time.  These don't have names by which they
610 can be looked up from Perl code at run time through eval"" like
611 my/our variables can be.  Since they can't be looked up by "name"
612 but only by their index allocated at compile time (which is usually
613 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
614
615 The SVs in the names AV have their PV being the name of the variable.
616 NV+1..IV inclusive is a range of cop_seq numbers for which the name is
617 valid.  For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
618 type.  For C<our> lexicals, the type is also SVt_PVGV, with the MAGIC slot
619 pointing at the stash of the associated global (so that duplicate C<our>
620 declarations in the same package can be detected).  SvCUR is sometimes
621 hijacked to store the generation number during compilation.
622
623 If SvFAKE is set on the name SV, then that slot in the frame AV is
624 a REFCNT'ed reference to a lexical from "outside". In this case,
625 the name SV does not use NVX and IVX to store a cop_seq range, since it is
626 in scope throughout. Instead IVX stores some flags containing info about
627 the real lexical (is it declared in an anon, and is it capable of being
628 instantiated multiple times?), and for fake ANONs, NVX contains the index
629 within the parent's pad where the lexical's value is stored, to make
630 cloning quicker.
631
632 If the 'name' is '&' the corresponding entry in frame AV
633 is a CV representing a possible closure.
634 (SvFAKE and name of '&' is not a meaningful combination currently but could
635 become so if C<my sub foo {}> is implemented.)
636
637 Note that formats are treated as anon subs, and are cloned each time
638 write is called (if necessary).
639
640 The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
641 and set on scope exit. This allows the 'Variable $x is not available' warning
642 to be generated in evals, such as 
643
644     { my $x = 1; sub f { eval '$x'} } f();
645
646         AV *    CvPADLIST(CV *cv)
647
648 =for hackers
649 Found in file pad.c
650
651 =item cv_clone
652 X<cv_clone>
653
654 Clone a CV: make a new CV which points to the same code etc, but which
655 has a newly-created pad built by copying the prototype pad and capturing
656 any outer lexicals.
657
658         CV*     cv_clone(CV* proto)
659
660 =for hackers
661 Found in file pad.c
662
663 =item cv_dump
664 X<cv_dump>
665
666 dump the contents of a CV
667
668         void    cv_dump(const CV *cv, const char *title)
669
670 =for hackers
671 Found in file pad.c
672
673 =item do_dump_pad
674 X<do_dump_pad>
675
676 Dump the contents of a padlist
677
678         void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
679
680 =for hackers
681 Found in file pad.c
682
683 =item intro_my
684 X<intro_my>
685
686 "Introduce" my variables to visible status.
687
688         U32     intro_my()
689
690 =for hackers
691 Found in file pad.c
692
693 =item pad_add_anon
694 X<pad_add_anon>
695
696 Add an anon code entry to the current compiling pad
697
698         PADOFFSET       pad_add_anon(SV* sv, OPCODE op_type)
699
700 =for hackers
701 Found in file pad.c
702
703 =item pad_add_name
704 X<pad_add_name>
705
706 Create a new name and associated PADMY SV in the current pad; return the
707 offset.
708 If C<typestash> is valid, the name is for a typed lexical; set the
709 name's stash to that value.
710 If C<ourstash> is valid, it's an our lexical, set the name's
711 OURSTASH to that value
712
713 If fake, it means we're cloning an existing entry
714
715         PADOFFSET       pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone)
716
717 =for hackers
718 Found in file pad.c
719
720 =item pad_alloc
721 X<pad_alloc>
722
723 Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
724 the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
725 for a slot which has no name and no active value.
726
727         PADOFFSET       pad_alloc(I32 optype, U32 tmptype)
728
729 =for hackers
730 Found in file pad.c
731
732 =item pad_block_start
733 X<pad_block_start>
734
735 Update the pad compilation state variables on entry to a new block
736
737         void    pad_block_start(int full)
738
739 =for hackers
740 Found in file pad.c
741
742 =item pad_check_dup
743 X<pad_check_dup>
744
745 Check for duplicate declarations: report any of:
746      * a my in the current scope with the same name;
747      * an our (anywhere in the pad) with the same name and the same stash
748        as C<ourstash>
749 C<is_our> indicates that the name to check is an 'our' declaration
750
751         void    pad_check_dup(const char* name, bool is_our, const HV* ourstash)
752
753 =for hackers
754 Found in file pad.c
755
756 =item pad_findlex
757 X<pad_findlex>
758
759 Find a named lexical anywhere in a chain of nested pads. Add fake entries
760 in the inner pads if it's found in an outer one.
761
762 Returns the offset in the bottom pad of the lex or the fake lex.
763 cv is the CV in which to start the search, and seq is the current cop_seq
764 to match against. If warn is true, print appropriate warnings.  The out_*
765 vars return values, and so are pointers to where the returned values
766 should be stored. out_capture, if non-null, requests that the innermost
767 instance of the lexical is captured; out_name_sv is set to the innermost
768 matched namesv or fake namesv; out_flags returns the flags normally
769 associated with the IVX field of a fake namesv.
770
771 Note that pad_findlex() is recursive; it recurses up the chain of CVs,
772 then comes back down, adding fake entries as it goes. It has to be this way
773 because fake namesvs in anon protoypes have to store in NVX the index into
774 the parent pad.
775
776         PADOFFSET       pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
777
778 =for hackers
779 Found in file pad.c
780
781 =item pad_findmy
782 X<pad_findmy>
783
784 Given a lexical name, try to find its offset, first in the current pad,
785 or failing that, in the pads of any lexically enclosing subs (including
786 the complications introduced by eval). If the name is found in an outer pad,
787 then a fake entry is added to the current pad.
788 Returns the offset in the current pad, or NOT_IN_PAD on failure.
789
790         PADOFFSET       pad_findmy(const char* name)
791
792 =for hackers
793 Found in file pad.c
794
795 =item pad_fixup_inner_anons
796 X<pad_fixup_inner_anons>
797
798 For any anon CVs in the pad, change CvOUTSIDE of that CV from
799 old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
800 moved to a pre-existing CV struct.
801
802         void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
803
804 =for hackers
805 Found in file pad.c
806
807 =item pad_free
808 X<pad_free>
809
810 Free the SV at offset po in the current pad.
811
812         void    pad_free(PADOFFSET po)
813
814 =for hackers
815 Found in file pad.c
816
817 =item pad_leavemy
818 X<pad_leavemy>
819
820 Cleanup at end of scope during compilation: set the max seq number for
821 lexicals in this scope and warn of any lexicals that never got introduced.
822
823         void    pad_leavemy()
824
825 =for hackers
826 Found in file pad.c
827
828 =item pad_new
829 X<pad_new>
830
831 Create a new compiling padlist, saving and updating the various global
832 vars at the same time as creating the pad itself. The following flags
833 can be OR'ed together:
834
835     padnew_CLONE        this pad is for a cloned CV
836     padnew_SAVE         save old globals
837     padnew_SAVESUB      also save extra stuff for start of sub
838
839         PADLIST*        pad_new(int flags)
840
841 =for hackers
842 Found in file pad.c
843
844 =item pad_push
845 X<pad_push>
846
847 Push a new pad frame onto the padlist, unless there's already a pad at
848 this depth, in which case don't bother creating a new one.  Then give
849 the new pad an @_ in slot zero.
850
851         void    pad_push(PADLIST *padlist, int depth)
852
853 =for hackers
854 Found in file pad.c
855
856 =item pad_reset
857 X<pad_reset>
858
859 Mark all the current temporaries for reuse
860
861         void    pad_reset()
862
863 =for hackers
864 Found in file pad.c
865
866 =item pad_setsv
867 X<pad_setsv>
868
869 Set the entry at offset po in the current pad to sv.
870 Use the macro PAD_SETSV() rather than calling this function directly.
871
872         void    pad_setsv(PADOFFSET po, SV* sv)
873
874 =for hackers
875 Found in file pad.c
876
877 =item pad_swipe
878 X<pad_swipe>
879
880 Abandon the tmp in the current pad at offset po and replace with a
881 new one.
882
883         void    pad_swipe(PADOFFSET po, bool refadjust)
884
885 =for hackers
886 Found in file pad.c
887
888 =item pad_tidy
889 X<pad_tidy>
890
891 Tidy up a pad after we've finished compiling it:
892     * remove most stuff from the pads of anonsub prototypes;
893     * give it a @_;
894     * mark tmps as such.
895
896         void    pad_tidy(padtidy_type type)
897
898 =for hackers
899 Found in file pad.c
900
901 =item pad_undef
902 X<pad_undef>
903
904 Free the padlist associated with a CV.
905 If parts of it happen to be current, we null the relevant
906 PL_*pad* global vars so that we don't have any dangling references left.
907 We also repoint the CvOUTSIDE of any about-to-be-orphaned
908 inner subs to the outer of this cv.
909
910 (This function should really be called pad_free, but the name was already
911 taken)
912
913         void    pad_undef(CV* cv)
914
915 =for hackers
916 Found in file pad.c
917
918
919 =back
920
921 =head1 Stack Manipulation Macros
922
923 =over 8
924
925 =item djSP
926 X<djSP>
927
928 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
929 a local copy of perl's stack pointer, available via the C<SP> macro.
930 See C<SP>.  (Available for backward source code compatibility with the
931 old (Perl 5.005) thread model.)
932
933                 djSP;
934
935 =for hackers
936 Found in file pp.h
937
938 =item LVRET
939 X<LVRET>
940
941 True if this op will be the return value of an lvalue subroutine
942
943 =for hackers
944 Found in file pp.h
945
946
947 =back
948
949 =head1 SV Manipulation Functions
950
951 =over 8
952
953 =item sv_add_arena
954 X<sv_add_arena>
955
956 Given a chunk of memory, link it to the head of the list of arenas,
957 and split it into a list of free SVs.
958
959         void    sv_add_arena(char* ptr, U32 size, U32 flags)
960
961 =for hackers
962 Found in file sv.c
963
964 =item sv_clean_all
965 X<sv_clean_all>
966
967 Decrement the refcnt of each remaining SV, possibly triggering a
968 cleanup. This function may have to be called multiple times to free
969 SVs which are in complex self-referential hierarchies.
970
971         I32     sv_clean_all()
972
973 =for hackers
974 Found in file sv.c
975
976 =item sv_clean_objs
977 X<sv_clean_objs>
978
979 Attempt to destroy all objects not yet freed
980
981         void    sv_clean_objs()
982
983 =for hackers
984 Found in file sv.c
985
986 =item sv_free_arenas
987 X<sv_free_arenas>
988
989 Deallocate the memory used by all arenas. Note that all the individual SV
990 heads and bodies within the arenas must already have been freed.
991
992         void    sv_free_arenas()
993
994 =for hackers
995 Found in file sv.c
996
997
998 =back
999
1000 =head1 Unicode Support
1001
1002 =over 8
1003
1004 =item find_uninit_var
1005 X<find_uninit_var>
1006
1007 Find the name of the undefined variable (if any) that caused the operator o
1008 to issue a "Use of uninitialized value" warning.
1009 If match is true, only return a name if it's value matches uninit_sv.
1010 So roughly speaking, if a unary operator (such as OP_COS) generates a
1011 warning, then following the direct child of the op may yield an
1012 OP_PADSV or OP_GV that gives the name of the undefined variable. On the
1013 other hand, with OP_ADD there are two branches to follow, so we only print
1014 the variable name if we get an exact match.
1015
1016 The name is returned as a mortal SV.
1017
1018 Assumes that PL_op is the op that originally triggered the error, and that
1019 PL_comppad/PL_curpad points to the currently executing pad.
1020
1021         SV*     find_uninit_var(OP* obase, SV* uninit_sv, bool top)
1022
1023 =for hackers
1024 Found in file sv.c
1025
1026 =item report_uninit
1027 X<report_uninit>
1028
1029 Print appropriate "Use of uninitialized variable" warning
1030
1031         void    report_uninit(SV* uninit_sv)
1032
1033 =for hackers
1034 Found in file sv.c
1035
1036
1037 =back
1038
1039 =head1 AUTHORS
1040
1041 The autodocumentation system was originally added to the Perl core by
1042 Benjamin Stuhl. Documentation is by whoever was kind enough to
1043 document their functions.
1044
1045 =head1 SEE ALSO
1046
1047 perlguts(1), perlapi(1)
1048