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