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