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