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