This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
PL_curpad == AvARRAY(PL_comppad) always
[perl5.git] / pod / perlintern.pod
1 =head1 NAME
2
3 perlintern - autogenerated documentation of purely B<internal>
4                  Perl functions
5
6 =head1 DESCRIPTION
7
8 This file is the autogenerated documentation of functions in the
9 Perl interpreter that are documented using Perl's internal documentation
10 format but are not marked as part of the Perl API. In other words,
11 B<they are not for use in extensions>!
12
13
14 =head1 Functions in file pad.h
15
16
17 =over 8
18
19 =item CX_CURPAD_SAVE
20
21 Save the current pad in the given context block structure.
22
23         void    CX_CURPAD_SAVE(struct context)
24
25 =for hackers
26 Found in file pad.h
27
28 =item CX_CURPAD_SV
29
30 Access the SV at offset po in the saved current pad in the given
31 context block structure (can be used as an lvalue).
32
33         SV *    CX_CURPAD_SV(struct context, PADOFFSET po)
34
35 =for hackers
36 Found in file pad.h
37
38 =item PAD_BASE_SV       
39
40 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
41
42         SV *    PAD_BASE_SV     (PADLIST padlist, PADOFFSET po)
43
44 =for hackers
45 Found in file pad.h
46
47 =item PAD_CLONE_VARS
48
49 |CLONE_PARAMS* param
50 Clone the state variables associated with running and compiling pads.
51
52         void    PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
53
54 =for hackers
55 Found in file pad.h
56
57 =item PAD_COMPNAME_FLAGS
58
59 Return the flags for the current compiling pad name
60 at offset C<po>. Assumes a valid slot entry.
61
62         U32     PAD_COMPNAME_FLAGS(PADOFFSET po)
63
64 =for hackers
65 Found in file pad.h
66
67 =item PAD_COMPNAME_GEN
68
69 The generation number of the name at offset C<po> in the current
70 compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
71
72         STRLEN  PAD_COMPNAME_GEN(PADOFFSET po)
73
74 =for hackers
75 Found in file pad.h
76
77 =item PAD_COMPNAME_OURSTASH
78
79 Return the stash associated with an C<our> variable.
80 Assumes the slot entry is a valid C<our> lexical.
81
82         HV *    PAD_COMPNAME_OURSTASH(PADOFFSET po)
83
84 =for hackers
85 Found in file pad.h
86
87 =item PAD_COMPNAME_PV
88
89 Return the name of the current compiling pad name
90 at offset C<po>. Assumes a valid slot entry.
91
92         char *  PAD_COMPNAME_PV(PADOFFSET po)
93
94 =for hackers
95 Found in file pad.h
96
97 =item PAD_COMPNAME_TYPE
98
99 Return the type (stash) of the current compiling pad name at offset
100 C<po>. Must be a valid name. Returns null if not typed.
101
102         HV *    PAD_COMPNAME_TYPE(PADOFFSET po)
103
104 =for hackers
105 Found in file pad.h
106
107 =item PAD_DUP
108
109 Clone a padlist.
110
111         void    PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
112
113 =for hackers
114 Found in file pad.h
115
116 =item PAD_RESTORE_LOCAL
117
118 Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
119
120         void    PAD_RESTORE_LOCAL(PAD *opad)
121
122 =for hackers
123 Found in file pad.h
124
125 =item PAD_SAVE_LOCAL
126
127 Save the current pad to the local variable opad, then make the
128 current pad equal to npad
129
130         void    PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
131
132 =for hackers
133 Found in file pad.h
134
135 =item PAD_SAVE_SETNULLPAD
136
137 Save the current pad then set it to null.
138
139         void    PAD_SAVE_SETNULLPAD()
140
141 =for hackers
142 Found in file pad.h
143
144 =item PAD_SETSV 
145
146 Set the slot at offset C<po> in the current pad to C<sv>
147
148         SV *    PAD_SETSV       (PADOFFSET po, SV* sv)
149
150 =for hackers
151 Found in file pad.h
152
153 =item PAD_SET_CUR       
154
155 Set the current pad to be pad C<n> in the padlist, saving
156 the previous current pad.
157
158         void    PAD_SET_CUR     (PADLIST padlist, I32 n)
159
160 =for hackers
161 Found in file pad.h
162
163 =item PAD_SV    
164
165 Get the value at offset C<po> in the current pad
166
167         void    PAD_SV  (PADOFFSET po)
168
169 =for hackers
170 Found in file pad.h
171
172 =item PAD_SVl   
173
174 Lightweight and lvalue version of C<PAD_SV>.
175 Get or set the value at offset C<po> in the current pad.
176 Unlike C<PAD_SV>, does not print diagnostics with -DX.
177 For internal use only.
178
179         SV *    PAD_SVl (PADOFFSET po)
180
181 =for hackers
182 Found in file pad.h
183
184 =item SAVECLEARSV       
185
186 Clear the pointed to pad value on scope exit. (ie the runtime action of 'my')
187
188         void    SAVECLEARSV     (SV **svp)
189
190 =for hackers
191 Found in file pad.h
192
193 =item SAVECOMPPAD
194
195 save PL_comppad and PL_curpad
196
197
198
199
200
201         void    SAVECOMPPAD()
202
203 =for hackers
204 Found in file pad.h
205
206 =item SAVEPADSV 
207
208 Save a pad slot (used to restore after an iteration)
209
210 XXX DAPM it would make more sense to make the arg a PADOFFSET
211         void    SAVEPADSV       (PADOFFSET po)
212
213 =for hackers
214 Found in file pad.h
215
216
217 =back
218
219 =head1 Global Variables
220
221 =over 8
222
223 =item PL_DBsingle
224
225 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
226 boolean which indicates whether subs are being single-stepped.
227 Single-stepping is automatically turned on after every step.  This is the C
228 variable which corresponds to Perl's $DB::single variable.  See
229 C<PL_DBsub>.
230
231         SV *    PL_DBsingle
232
233 =for hackers
234 Found in file intrpvar.h
235
236 =item PL_DBsub
237
238 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
239 the SV which holds the name of the sub being debugged.  This is the C
240 variable which corresponds to Perl's $DB::sub variable.  See
241 C<PL_DBsingle>.
242
243         GV *    PL_DBsub
244
245 =for hackers
246 Found in file intrpvar.h
247
248 =item PL_DBtrace
249
250 Trace variable used when Perl is run in debugging mode, with the B<-d>
251 switch.  This is the C variable which corresponds to Perl's $DB::trace
252 variable.  See C<PL_DBsingle>.
253
254         SV *    PL_DBtrace
255
256 =for hackers
257 Found in file intrpvar.h
258
259 =item PL_dowarn
260
261 The C variable which corresponds to Perl's $^W warning variable.
262
263         bool    PL_dowarn
264
265 =for hackers
266 Found in file intrpvar.h
267
268 =item PL_last_in_gv
269
270 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
271
272         GV*     PL_last_in_gv
273
274 =for hackers
275 Found in file thrdvar.h
276
277 =item PL_ofs_sv
278
279 The output field separator - C<$,> in Perl space.
280
281         SV*     PL_ofs_sv
282
283 =for hackers
284 Found in file thrdvar.h
285
286 =item PL_rs
287
288 The input record separator - C<$/> in Perl space.
289
290         SV*     PL_rs
291
292 =for hackers
293 Found in file thrdvar.h
294
295
296 =back
297
298 =head1 GV Functions
299
300 =over 8
301
302 =item is_gv_magical
303
304 Returns C<TRUE> if given the name of a magical GV.
305
306 Currently only useful internally when determining if a GV should be
307 created even in rvalue contexts.
308
309 C<flags> is not used at present but available for future extension to
310 allow selecting particular classes of magical variable.
311
312         bool    is_gv_magical(char *name, STRLEN len, U32 flags)
313
314 =for hackers
315 Found in file gv.c
316
317
318 =back
319
320 =head1 IO Functions
321
322 =over 8
323
324 =item start_glob
325
326 Function called by C<do_readline> to spawn a glob (or do the glob inside
327 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
328 this glob starter is only used by miniperl during the build process.
329 Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
330
331         PerlIO* start_glob(SV* pattern, IO *io)
332
333 =for hackers
334 Found in file doio.c
335
336
337 =back
338
339 =head1 Pad Data Structures
340
341 =over 8
342
343 =item CvPADLIST
344
345 CV's can have CvPADLIST(cv) set to point to an AV.
346
347 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
348 not callable at will and are always thrown away after the eval"" is done
349 executing).
350
351 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
352 but that is really the callers pad (a slot of which is allocated by
353 every entersub).
354
355 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
356 is managed "manual" (mostly in pad.c) rather than normal av.c rules.
357 The items in the AV are not SVs as for a normal AV, but other AVs:
358
359 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
360 the "static type information" for lexicals.
361
362 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
363 depth of recursion into the CV.
364 The 0'th slot of a frame AV is an AV which is @_.
365 other entries are storage for variables and op targets.
366
367 During compilation:
368 C<PL_comppad_name> is set the the the names AV.
369 C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
370 C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
371
372 During execution, C<PL_comppad> and C<PL_curpad> refer to the live
373 frame of the currently executing sub.
374
375 Iterating over the names AV iterates over all possible pad
376 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
377 &PL_sv_undef "names" (see pad_alloc()).
378
379 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
380 The rest are op targets/GVs/constants which are statically allocated
381 or resolved at compile time.  These don't have names by which they
382 can be looked up from Perl code at run time through eval"" like
383 my/our variables can be.  Since they can't be looked up by "name"
384 but only by their index allocated at compile time (which is usually
385 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
386
387 The SVs in the names AV have their PV being the name of the variable.
388 NV+1..IV inclusive is a range of cop_seq numbers for which the name is
389 valid.  For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
390 type.  For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
391 stash of the associated global (so that duplicate C<our> delarations in the
392 same package can be detected).  SvCUR is sometimes hijacked to
393 store the generation number during compilation.
394
395 If SvFAKE is set on the name SV then slot in the frame AVs are
396 a REFCNT'ed references to a lexical from "outside".
397
398 If the 'name' is '&' the the corresponding entry in frame AV
399 is a CV representing a possible closure.
400 (SvFAKE and name of '&' is not a meaningful combination currently but could
401 become so if C<my sub foo {}> is implemented.)
402
403         AV *    CvPADLIST(CV *cv)
404
405 =for hackers
406 Found in file pad.c
407
408 =item cv_clone
409
410 Clone a CV: make a new CV which points to the same code etc, but which
411 has a newly-created pad built by copying the prototype pad and capturing
412 any outer lexicals.
413
414         CV*     cv_clone(CV* proto)
415
416 =for hackers
417 Found in file pad.c
418
419 =item cv_dump
420
421 dump the contents of a CV
422
423         void    cv_dump(CV *cv, char *title)
424
425 =for hackers
426 Found in file pad.c
427
428 =item do_dump_pad
429
430 Dump the contents of a padlist
431
432         void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
433
434 =for hackers
435 Found in file pad.c
436
437 =item intro_my
438
439 "Introduce" my variables to visible status.
440
441         U32     intro_my()
442
443 =for hackers
444 Found in file pad.c
445
446 =item pad_add_anon
447
448 Add an anon code entry to the current compiling pad
449
450         PADOFFSET       pad_add_anon(SV* sv, OPCODE op_type)
451
452 =for hackers
453 Found in file pad.c
454
455 =item pad_add_name
456
457 Create a new name in the current pad at the specified offset.
458 If C<typestash> is valid, the name is for a typed lexical; set the
459 name's stash to that value.
460 If C<ourstash> is valid, it's an our lexical, set the name's
461 GvSTASH to that value
462
463 Also, if the name is @.. or %.., create a new array or hash for that slot
464
465 If fake, it means we're cloning an existing entry
466
467         PADOFFSET       pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
468
469 =for hackers
470 Found in file pad.c
471
472 =item pad_alloc
473
474 Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
475 the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
476 for a slot which has no name and and no active value.
477
478         PADOFFSET       pad_alloc(I32 optype, U32 tmptype)
479
480 =for hackers
481 Found in file pad.c
482
483 =item pad_block_start
484
485 Update the pad compilation state variables on entry to a new block
486
487         void    pad_block_start(int full)
488
489 =for hackers
490 Found in file pad.c
491
492 =item pad_check_dup
493
494 Check for duplicate declarations: report any of:
495      * a my in the current scope with the same name;
496      * an our (anywhere in the pad) with the same name and the same stash
497        as C<ourstash>
498 C<is_our> indicates that the name to check is an 'our' declaration
499
500         void    pad_check_dup(char* name, bool is_our, HV* ourstash)
501
502 =for hackers
503 Found in file pad.c
504
505 =item pad_findlex
506
507 Find a named lexical anywhere in a chain of nested pads. Add fake entries
508 in the inner pads if its found in an outer one.
509
510 If flags == FINDLEX_NOSEARCH we don't bother searching outer contexts.
511
512         PADOFFSET       pad_findlex(char* name, PADOFFSET newoff, U32 seq, CV* startcv, I32 cx_ix, I32 saweval, U32 flags)
513
514 =for hackers
515 Found in file pad.c
516
517 =item pad_findmy
518
519 Given a lexical name, try to find its offset, first in the current pad,
520 or failing that, in the pads of any lexically enclosing subs (including
521 the complications introduced by eval). If the name is found in an outer pad,
522 then a fake entry is added to the current pad.
523 Returns the offset in the current pad, or NOT_IN_PAD on failure.
524
525         PADOFFSET       pad_findmy(char* name)
526
527 =for hackers
528 Found in file pad.c
529
530 =item pad_fixup_inner_anons
531
532 For any anon CVs in the pad, change CvOUTSIDE of that CV from
533 old_cv to new_cv if necessary.
534
535         void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
536
537 =for hackers
538 Found in file pad.c
539
540 =item pad_free
541
542 Free the SV at offet po in the current pad.
543
544         void    pad_free(PADOFFSET po)
545
546 =for hackers
547 Found in file pad.c
548
549 =item pad_leavemy
550
551 Cleanup at end of scope during compilation: set the max seq number for
552 lexicals in this scope and warn of any lexicals that never got introduced.
553
554         void    pad_leavemy()
555
556 =for hackers
557 Found in file pad.c
558
559 =item pad_new
560
561 Create a new compiling padlist, saving and updating the various global
562 vars at the same time as creating the pad itself. The following flags
563 can be OR'ed together:
564
565     padnew_CLONE        this pad is for a cloned CV
566     padnew_SAVE         save old globals
567     padnew_SAVESUB      also save extra stuff for start of sub
568
569         PADLIST*        pad_new(padnew_flags flags)
570
571 =for hackers
572 Found in file pad.c
573
574 =item pad_push
575
576 Push a new pad frame onto the padlist, unless there's already a pad at
577 this depth, in which case don't bother creating a new one.
578 If has_args is true, give the new pad an @_ in slot zero.
579
580         void    pad_push(PADLIST *padlist, int depth, int has_args)
581
582 =for hackers
583 Found in file pad.c
584
585 =item pad_reset
586
587 Mark all the current temporaries for reuse
588
589         void    pad_reset()
590
591 =for hackers
592 Found in file pad.c
593
594 =item pad_setsv
595
596 Set the entry at offset po in the current pad to sv.
597 Use the macro PAD_SETSV() rather than calling this function directly.
598
599         void    pad_setsv(PADOFFSET po, SV* sv)
600
601 =for hackers
602 Found in file pad.c
603
604 =item pad_swipe
605
606 Abandon the tmp in the current pad at offset po and replace with a
607 new one.
608
609         void    pad_swipe(PADOFFSET po, bool refadjust)
610
611 =for hackers
612 Found in file pad.c
613
614 =item pad_tidy
615
616 Tidy up a pad after we've finished compiling it:
617     * remove most stuff from the pads of anonsub prototypes;
618     * give it a @_;
619     * mark tmps as such.
620
621         void    pad_tidy(padtidy_type type)
622
623 =for hackers
624 Found in file pad.c
625
626 =item pad_undef
627
628 Free the padlist associated with a CV.
629 If parts of it happen to be current, we null the relevant
630 PL_*pad* global vars so that we don't have any dangling references left.
631 We also repoint the CvOUTSIDE of any about-to-be-orphaned
632 inner subs to outercv.
633
634         void    pad_undef(CV* cv, CV* outercv)
635
636 =for hackers
637 Found in file pad.c
638
639
640 =back
641
642 =head1 Stack Manipulation Macros
643
644 =over 8
645
646 =item djSP
647
648 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
649 a local copy of perl's stack pointer, available via the C<SP> macro.
650 See C<SP>.  (Available for backward source code compatibility with the
651 old (Perl 5.005) thread model.)
652
653                 djSP;
654
655 =for hackers
656 Found in file pp.h
657
658 =item LVRET
659
660 True if this op will be the return value of an lvalue subroutine
661
662 =for hackers
663 Found in file pp.h
664
665
666 =back
667
668 =head1 SV Manipulation Functions
669
670 =over 8
671
672 =item report_uninit
673
674 Print appropriate "Use of uninitialized variable" warning
675
676         void    report_uninit()
677
678 =for hackers
679 Found in file sv.c
680
681 =item sv_add_arena
682
683 Given a chunk of memory, link it to the head of the list of arenas,
684 and split it into a list of free SVs.
685
686         void    sv_add_arena(char* ptr, U32 size, U32 flags)
687
688 =for hackers
689 Found in file sv.c
690
691 =item sv_clean_all
692
693 Decrement the refcnt of each remaining SV, possibly triggering a
694 cleanup. This function may have to be called multiple times to free
695 SVs which are in complex self-referential hierarchies.
696
697         I32     sv_clean_all()
698
699 =for hackers
700 Found in file sv.c
701
702 =item sv_clean_objs
703
704 Attempt to destroy all objects not yet freed
705
706         void    sv_clean_objs()
707
708 =for hackers
709 Found in file sv.c
710
711 =item sv_free_arenas
712
713 Deallocate the memory used by all arenas. Note that all the individual SV
714 heads and bodies within the arenas must already have been freed.
715
716         void    sv_free_arenas()
717
718 =for hackers
719 Found in file sv.c
720
721
722 =back
723
724 =head1 AUTHORS
725
726 The autodocumentation system was originally added to the Perl core by
727 Benjamin Stuhl. Documentation is by whoever was kind enough to
728 document their functions.
729
730 =head1 SEE ALSO
731
732 perlguts(1), perlapi(1)
733