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