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