This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ea5c902c0f59f6b875dfb062c00e22704e8f2ac7
[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 Functions in file pp_ctl.c
220
221
222 =over 8
223
224 =item find_runcv
225
226 Locate the CV corresponding to the currently executing sub or eval.
227
228         CV*     find_runcv()
229
230 =for hackers
231 Found in file pp_ctl.c
232
233
234 =back
235
236 =head1 Global Variables
237
238 =over 8
239
240 =item PL_DBsingle
241
242 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
243 boolean which indicates whether subs are being single-stepped.
244 Single-stepping is automatically turned on after every step.  This is the C
245 variable which corresponds to Perl's $DB::single variable.  See
246 C<PL_DBsub>.
247
248         SV *    PL_DBsingle
249
250 =for hackers
251 Found in file intrpvar.h
252
253 =item PL_DBsub
254
255 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
256 the SV which holds the name of the sub being debugged.  This is the C
257 variable which corresponds to Perl's $DB::sub variable.  See
258 C<PL_DBsingle>.
259
260         GV *    PL_DBsub
261
262 =for hackers
263 Found in file intrpvar.h
264
265 =item PL_DBtrace
266
267 Trace variable used when Perl is run in debugging mode, with the B<-d>
268 switch.  This is the C variable which corresponds to Perl's $DB::trace
269 variable.  See C<PL_DBsingle>.
270
271         SV *    PL_DBtrace
272
273 =for hackers
274 Found in file intrpvar.h
275
276 =item PL_dowarn
277
278 The C variable which corresponds to Perl's $^W warning variable.
279
280         bool    PL_dowarn
281
282 =for hackers
283 Found in file intrpvar.h
284
285 =item PL_last_in_gv
286
287 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
288
289         GV*     PL_last_in_gv
290
291 =for hackers
292 Found in file thrdvar.h
293
294 =item PL_ofs_sv
295
296 The output field separator - C<$,> in Perl space.
297
298         SV*     PL_ofs_sv
299
300 =for hackers
301 Found in file thrdvar.h
302
303 =item PL_rs
304
305 The input record separator - C<$/> in Perl space.
306
307         SV*     PL_rs
308
309 =for hackers
310 Found in file thrdvar.h
311
312
313 =back
314
315 =head1 GV Functions
316
317 =over 8
318
319 =item is_gv_magical
320
321 Returns C<TRUE> if given the name of a magical GV.
322
323 Currently only useful internally when determining if a GV should be
324 created even in rvalue contexts.
325
326 C<flags> is not used at present but available for future extension to
327 allow selecting particular classes of magical variable.
328
329         bool    is_gv_magical(char *name, STRLEN len, U32 flags)
330
331 =for hackers
332 Found in file gv.c
333
334
335 =back
336
337 =head1 IO Functions
338
339 =over 8
340
341 =item start_glob
342
343 Function called by C<do_readline> to spawn a glob (or do the glob inside
344 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
345 this glob starter is only used by miniperl during the build process.
346 Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
347
348         PerlIO* start_glob(SV* pattern, IO *io)
349
350 =for hackers
351 Found in file doio.c
352
353
354 =back
355
356 =head1 Pad Data Structures
357
358 =over 8
359
360 =item CvPADLIST
361
362 CV's can have CvPADLIST(cv) set to point to an AV.
363
364 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
365 not callable at will and are always thrown away after the eval"" is done
366 executing).
367
368 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
369 but that is really the callers pad (a slot of which is allocated by
370 every entersub).
371
372 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
373 is managed "manual" (mostly in pad.c) rather than normal av.c rules.
374 The items in the AV are not SVs as for a normal AV, but other AVs:
375
376 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
377 the "static type information" for lexicals.
378
379 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
380 depth of recursion into the CV.
381 The 0'th slot of a frame AV is an AV which is @_.
382 other entries are storage for variables and op targets.
383
384 During compilation:
385 C<PL_comppad_name> is set the the the names AV.
386 C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
387 C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
388
389 During execution, C<PL_comppad> and C<PL_curpad> refer to the live
390 frame of the currently executing sub.
391
392 Iterating over the names AV iterates over all possible pad
393 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
394 &PL_sv_undef "names" (see pad_alloc()).
395
396 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
397 The rest are op targets/GVs/constants which are statically allocated
398 or resolved at compile time.  These don't have names by which they
399 can be looked up from Perl code at run time through eval"" like
400 my/our variables can be.  Since they can't be looked up by "name"
401 but only by their index allocated at compile time (which is usually
402 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
403
404 The SVs in the names AV have their PV being the name of the variable.
405 NV+1..IV inclusive is a range of cop_seq numbers for which the name is
406 valid.  For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
407 type.  For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
408 stash of the associated global (so that duplicate C<our> delarations in the
409 same package can be detected).  SvCUR is sometimes hijacked to
410 store the generation number during compilation.
411
412 If SvFAKE is set on the name SV then slot in the frame AVs are
413 a REFCNT'ed references to a lexical from "outside". In this case,
414 the name SV does not have a cop_seq range, since it is in scope
415 throughout.
416
417 If the 'name' is '&' the the corresponding entry in frame AV
418 is a CV representing a possible closure.
419 (SvFAKE and name of '&' is not a meaningful combination currently but could
420 become so if C<my sub foo {}> is implemented.)
421
422         AV *    CvPADLIST(CV *cv)
423
424 =for hackers
425 Found in file pad.c
426
427 =item cv_clone
428
429 Clone a CV: make a new CV which points to the same code etc, but which
430 has a newly-created pad built by copying the prototype pad and capturing
431 any outer lexicals.
432
433         CV*     cv_clone(CV* proto)
434
435 =for hackers
436 Found in file pad.c
437
438 =item cv_dump
439
440 dump the contents of a CV
441
442         void    cv_dump(CV *cv, char *title)
443
444 =for hackers
445 Found in file pad.c
446
447 =item do_dump_pad
448
449 Dump the contents of a padlist
450
451         void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
452
453 =for hackers
454 Found in file pad.c
455
456 =item intro_my
457
458 "Introduce" my variables to visible status.
459
460         U32     intro_my()
461
462 =for hackers
463 Found in file pad.c
464
465 =item pad_add_anon
466
467 Add an anon code entry to the current compiling pad
468
469         PADOFFSET       pad_add_anon(SV* sv, OPCODE op_type)
470
471 =for hackers
472 Found in file pad.c
473
474 =item pad_add_name
475
476 Create a new name in the current pad at the specified offset.
477 If C<typestash> is valid, the name is for a typed lexical; set the
478 name's stash to that value.
479 If C<ourstash> is valid, it's an our lexical, set the name's
480 GvSTASH to that value
481
482 Also, if the name is @.. or %.., create a new array or hash for that slot
483
484 If fake, it means we're cloning an existing entry
485
486         PADOFFSET       pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
487
488 =for hackers
489 Found in file pad.c
490
491 =item pad_alloc
492
493 Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
494 the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
495 for a slot which has no name and and no active value.
496
497         PADOFFSET       pad_alloc(I32 optype, U32 tmptype)
498
499 =for hackers
500 Found in file pad.c
501
502 =item pad_block_start
503
504 Update the pad compilation state variables on entry to a new block
505
506         void    pad_block_start(int full)
507
508 =for hackers
509 Found in file pad.c
510
511 =item pad_check_dup
512
513 Check for duplicate declarations: report any of:
514      * a my in the current scope with the same name;
515      * an our (anywhere in the pad) with the same name and the same stash
516        as C<ourstash>
517 C<is_our> indicates that the name to check is an 'our' declaration
518
519         void    pad_check_dup(char* name, bool is_our, HV* ourstash)
520
521 =for hackers
522 Found in file pad.c
523
524 =item pad_findlex
525
526 Find a named lexical anywhere in a chain of nested pads. Add fake entries
527 in the inner pads if it's found in an outer one. innercv is the CV *inside*
528 the chain of outer CVs to be searched. If newoff is non-null, this is a
529 run-time cloning: don't add fake entries, just find the lexical and add a
530 ref to it at newoff in the current pad.
531
532         PADOFFSET       pad_findlex(char* name, PADOFFSET newoff, CV* innercv)
533
534 =for hackers
535 Found in file pad.c
536
537 =item pad_findmy
538
539 Given a lexical name, try to find its offset, first in the current pad,
540 or failing that, in the pads of any lexically enclosing subs (including
541 the complications introduced by eval). If the name is found in an outer pad,
542 then a fake entry is added to the current pad.
543 Returns the offset in the current pad, or NOT_IN_PAD on failure.
544
545         PADOFFSET       pad_findmy(char* name)
546
547 =for hackers
548 Found in file pad.c
549
550 =item pad_fixup_inner_anons
551
552 For any anon CVs in the pad, change CvOUTSIDE of that CV from
553 old_cv to new_cv if necessary.
554
555         void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
556
557 =for hackers
558 Found in file pad.c
559
560 =item pad_free
561
562 Free the SV at offet po in the current pad.
563
564         void    pad_free(PADOFFSET po)
565
566 =for hackers
567 Found in file pad.c
568
569 =item pad_leavemy
570
571 Cleanup at end of scope during compilation: set the max seq number for
572 lexicals in this scope and warn of any lexicals that never got introduced.
573
574         void    pad_leavemy()
575
576 =for hackers
577 Found in file pad.c
578
579 =item pad_new
580
581 Create a new compiling padlist, saving and updating the various global
582 vars at the same time as creating the pad itself. The following flags
583 can be OR'ed together:
584
585     padnew_CLONE        this pad is for a cloned CV
586     padnew_SAVE         save old globals
587     padnew_SAVESUB      also save extra stuff for start of sub
588
589         PADLIST*        pad_new(padnew_flags flags)
590
591 =for hackers
592 Found in file pad.c
593
594 =item pad_push
595
596 Push a new pad frame onto the padlist, unless there's already a pad at
597 this depth, in which case don't bother creating a new one.
598 If has_args is true, give the new pad an @_ in slot zero.
599
600         void    pad_push(PADLIST *padlist, int depth, int has_args)
601
602 =for hackers
603 Found in file pad.c
604
605 =item pad_reset
606
607 Mark all the current temporaries for reuse
608
609         void    pad_reset()
610
611 =for hackers
612 Found in file pad.c
613
614 =item pad_setsv
615
616 Set the entry at offset po in the current pad to sv.
617 Use the macro PAD_SETSV() rather than calling this function directly.
618
619         void    pad_setsv(PADOFFSET po, SV* sv)
620
621 =for hackers
622 Found in file pad.c
623
624 =item pad_swipe
625
626 Abandon the tmp in the current pad at offset po and replace with a
627 new one.
628
629         void    pad_swipe(PADOFFSET po, bool refadjust)
630
631 =for hackers
632 Found in file pad.c
633
634 =item pad_tidy
635
636 Tidy up a pad after we've finished compiling it:
637     * remove most stuff from the pads of anonsub prototypes;
638     * give it a @_;
639     * mark tmps as such.
640
641         void    pad_tidy(padtidy_type type)
642
643 =for hackers
644 Found in file pad.c
645
646 =item pad_undef
647
648 Free the padlist associated with a CV.
649 If parts of it happen to be current, we null the relevant
650 PL_*pad* global vars so that we don't have any dangling references left.
651 We also repoint the CvOUTSIDE of any about-to-be-orphaned
652 inner subs to the outer of this cv.
653
654         void    pad_undef(CV* cv)
655
656 =for hackers
657 Found in file pad.c
658
659
660 =back
661
662 =head1 Stack Manipulation Macros
663
664 =over 8
665
666 =item djSP
667
668 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
669 a local copy of perl's stack pointer, available via the C<SP> macro.
670 See C<SP>.  (Available for backward source code compatibility with the
671 old (Perl 5.005) thread model.)
672
673                 djSP;
674
675 =for hackers
676 Found in file pp.h
677
678 =item LVRET
679
680 True if this op will be the return value of an lvalue subroutine
681
682 =for hackers
683 Found in file pp.h
684
685
686 =back
687
688 =head1 SV Manipulation Functions
689
690 =over 8
691
692 =item report_uninit
693
694 Print appropriate "Use of uninitialized variable" warning
695
696         void    report_uninit()
697
698 =for hackers
699 Found in file sv.c
700
701 =item sv_add_arena
702
703 Given a chunk of memory, link it to the head of the list of arenas,
704 and split it into a list of free SVs.
705
706         void    sv_add_arena(char* ptr, U32 size, U32 flags)
707
708 =for hackers
709 Found in file sv.c
710
711 =item sv_clean_all
712
713 Decrement the refcnt of each remaining SV, possibly triggering a
714 cleanup. This function may have to be called multiple times to free
715 SVs which are in complex self-referential hierarchies.
716
717         I32     sv_clean_all()
718
719 =for hackers
720 Found in file sv.c
721
722 =item sv_clean_objs
723
724 Attempt to destroy all objects not yet freed
725
726         void    sv_clean_objs()
727
728 =for hackers
729 Found in file sv.c
730
731 =item sv_free_arenas
732
733 Deallocate the memory used by all arenas. Note that all the individual SV
734 heads and bodies within the arenas must already have been freed.
735
736         void    sv_free_arenas()
737
738 =for hackers
739 Found in file sv.c
740
741
742 =back
743
744 =head1 AUTHORS
745
746 The autodocumentation system was originally added to the Perl core by
747 Benjamin Stuhl. Documentation is by whoever was kind enough to
748 document their functions.
749
750 =head1 SEE ALSO
751
752 perlguts(1), perlapi(1)
753