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