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