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