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