1PERLINTERN(1) Perl Programmers Reference Guide PERLINTERN(1)
2
6 perlintern - autogenerated documentation of purely internal
7 Perl functions
8
10 This file is the autogenerated documentation of functions in the Perl
11 interpreter that are documented using Perl's internal documentation
12 format but are not marked as part of the Perl API. In other words, they
13 are not for use in extensions!
14
16 CvWEAKOUTSIDE
17 Each CV has a pointer, "CvOUTSIDE()", to its lexically
18 enclosing CV (if any). Because pointers to anonymous sub
19 prototypes are stored in "&" pad slots, it is a possible to get
20 a circular reference, with the parent pointing to the child and
21 vice-versa. To avoid the ensuing memory leak, we do not
22 increment the reference count of the CV pointed to by
23 "CvOUTSIDE" in the one specific instance that the parent has a
24 "&" pad slot pointing back to us. In this case, we set the
25 "CvWEAKOUTSIDE" flag in the child. This allows us to determine
26 under what circumstances we should decrement the refcount of
27 the parent when freeing the child.
28 There is a further complication with non-closure anonymous subs
30 (i.e. those that do not refer to any lexicals outside that
31 sub). In this case, the anonymous prototype is shared rather
32 than being cloned. This has the consequence that the parent may
33 be freed while there are still active children, eg
34 BEGIN { $a = sub { eval '$x' } }
36 In this case, the BEGIN is freed immediately after execution
38 since there are no active references to it: the anon sub
39 prototype has "CvWEAKOUTSIDE" set since it's not a closure, and
40 $a points to the same CV, so it doesn't contribute to BEGIN's
41 refcount either. When $a is executed, the "eval '$x'" causes
42 the chain of "CvOUTSIDE"s to be followed, and the freed BEGIN
43 is accessed.
44 To avoid this, whenever a CV and its associated pad is freed,
46 any "&" entries in the pad are explicitly removed from the pad,
47 and if the refcount of the pointed-to anon sub is still
48 positive, then that child's "CvOUTSIDE" is set to point to its
49 grandparent. This will only occur in the single specific case
50 of a non-closure anon prototype having one or more active
51 references (such as $a above).
52 One other thing to consider is that a CV may be merely
54 undefined rather than freed, eg "undef &foo". In this case, its
55 refcount may not have reached zero, but we still delete its pad
56 and its "CvROOT" etc. Since various children may still have
57 their "CvOUTSIDE" pointing at this undefined CV, we keep its
58 own "CvOUTSIDE" for the time being, so that the chain of
59 lexical scopes is unbroken. For example, the following should
60 print 123:
61 my $x = 123;
63 sub tmp { sub { eval '$x' } }
64 my $a = tmp();
65 undef &tmp;
66 print $a->();
67 bool CvWEAKOUTSIDE(CV *cv)
69
71 CX_CURPAD_SAVE
72 Save the current pad in the given context block structure.
73 void CX_CURPAD_SAVE(struct context)
75 CX_CURPAD_SV
77 Access the SV at offset po in the saved current pad in the
78 given context block structure (can be used as an lvalue).
79 SV * CX_CURPAD_SV(struct context, PADOFFSET po)
81 PAD_BASE_SV
83 Get the value from slot "po" in the base (DEPTH=1) pad of a
84 padlist
85 SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
87 PAD_CLONE_VARS
89 Clone the state variables associated with running and compiling
90 pads.
91 void PAD_CLONE_VARS(PerlInterpreter *proto_perl, CLONE_PARAMS* param)
93 PAD_COMPNAME_FLAGS
95 Return the flags for the current compiling pad name at offset
96 "po". Assumes a valid slot entry.
97 U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
99 PAD_COMPNAME_GEN
101 The generation number of the name at offset "po" in the current
102 compiling pad (lvalue). Note that "SvUVX" is hijacked for this
103 purpose.
104 STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
106 PAD_COMPNAME_GEN_set
108 Sets the generation number of the name at offset "po" in the
109 current ling pad (lvalue) to "gen". Note that "SvUV_set" is
110 hijacked for this purpose.
111 STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
113 PAD_COMPNAME_OURSTASH
115 Return the stash associated with an "our" variable. Assumes
116 the slot entry is a valid "our" lexical.
117 HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
119 PAD_COMPNAME_PV
121 Return the name of the current compiling pad name at offset
122 "po". Assumes a valid slot entry.
123 char * PAD_COMPNAME_PV(PADOFFSET po)
125 PAD_COMPNAME_TYPE
127 Return the type (stash) of the current compiling pad name at
128 offset "po". Must be a valid name. Returns null if not typed.
129 HV * PAD_COMPNAME_TYPE(PADOFFSET po)
131 PAD_DUP Clone a padlist.
133 void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
135 PAD_RESTORE_LOCAL
137 Restore the old pad saved into the local variable opad by
138 PAD_SAVE_LOCAL()
139 void PAD_RESTORE_LOCAL(PAD *opad)
141 PAD_SAVE_LOCAL
143 Save the current pad to the local variable opad, then make the
144 current pad equal to npad
145 void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
147 PAD_SAVE_SETNULLPAD
149 Save the current pad then set it to null.
150 void PAD_SAVE_SETNULLPAD()
152 PAD_SETSV
154 Set the slot at offset "po" in the current pad to "sv"
155 SV * PAD_SETSV(PADOFFSET po, SV* sv)
157 PAD_SET_CUR
159 Set the current pad to be pad "n" in the padlist, saving the
160 previous current pad. NB currently this macro expands to a
161 string too long for some compilers, so it's best to replace it
162 with
163 SAVECOMPPAD();
165 PAD_SET_CUR_NOSAVE(padlist,n);
166 void PAD_SET_CUR(PADLIST padlist, I32 n)
169 PAD_SET_CUR_NOSAVE
171 like PAD_SET_CUR, but without the save
172 void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
174 PAD_SV Get the value at offset "po" in the current pad
176 void PAD_SV(PADOFFSET po)
178 PAD_SVl Lightweight and lvalue version of "PAD_SV". Get or set the
180 value at offset "po" in the current pad. Unlike "PAD_SV", does
181 not print diagnostics with -DX. For internal use only.
182 SV * PAD_SVl(PADOFFSET po)
184 SAVECLEARSV
186 Clear the pointed to pad value on scope exit. (i.e. the runtime
187 action of 'my')
188 void SAVECLEARSV(SV **svp)
190 SAVECOMPPAD
192 save PL_comppad and PL_curpad
193 void SAVECOMPPAD()
195 SAVEPADSV
197 Save a pad slot (used to restore after an iteration)
198 XXX DAPM it would make more sense to make the arg a PADOFFSET
200 void SAVEPADSV(PADOFFSET po)
201
203 is_gv_magical
204 Returns "TRUE" if given the name of a magical GV.
205 Currently only useful internally when determining if a GV
207 should be created even in rvalue contexts.
208 "flags" is not used at present but available for future
210 extension to allow selecting particular classes of magical
211 variable.
212 Currently assumes that "name" is NUL terminated (as well as len
214 being valid). This assumption is met by all callers within the
215 perl core, which all pass pointers returned by SvPV.
216 bool is_gv_magical(const char *name, STRLEN len, U32 flags)
218 is_gv_magical_sv
220 Returns "TRUE" if given the name of a magical GV. Calls
221 is_gv_magical.
222 bool is_gv_magical_sv(SV *name, U32 flags)
224
226 refcounted_he_chain_2hv
227 Generates and returns a "HV *" by walking up the tree starting
228 at the passed in "struct refcounted_he *".
229 HV * refcounted_he_chain_2hv(const struct refcounted_he *c)
231 refcounted_he_free
233 Decrements the reference count of the passed in "struct
234 refcounted_he *" by one. If the reference count reaches zero
235 the structure's memory is freed, and "refcounted_he_free"
236 iterates onto the parent node.
237 void refcounted_he_free(struct refcounted_he *he)
239 refcounted_he_new
241 Creates a new "struct refcounted_he". As key is copied, and
242 value is stored in a compact form, all references remain the
243 property of the caller. The "struct refcounted_he" is returned
244 with a reference count of 1.
245 struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value)
247
249 start_glob
250 Function called by "do_readline" to spawn a glob (or do the
251 glob inside perl on VMS). This code used to be inline, but now
252 perl uses "File::Glob" this glob starter is only used by
253 miniperl during the build process. Moving it away shrinks
254 pp_hot.c; shrinking pp_hot.c helps speed perl up.
255 PerlIO* start_glob(SV *tmpglob, IO *io)
257
259 magic_clearhint
260 Triggered by a delete from %^H, records the key to
261 "PL_compiling.cop_hints_hash".
262 int magic_clearhint(SV* sv, MAGIC* mg)
264 magic_sethint
266 Triggered by a store to %^H, records the key/value pair to
267 "PL_compiling.cop_hints_hash". It is assumed that hints aren't
268 storing anything that would need a deep copy. Maybe we should
269 warn if we find a reference.
270 int magic_sethint(SV* sv, MAGIC* mg)
272 mg_localize
274 Copy some of the magic from an existing SV to new localized
275 version of that SV. Container magic (eg %ENV, $1, tie) gets
276 copied, value magic doesn't (eg taint, pos).
277 void mg_localize(SV* sv, SV* nsv)
279
281 mro_get_linear_isa_dfs
282 Returns the Depth-First Search linearization of @ISA the given
283 stash. The return value is a read-only AV*. "level" should be
284 0 (it is used internally in this function's recursion).
285 You are responsible for "SvREFCNT_inc()" on the return value if
287 you plan to store it anywhere semi-permanently (otherwise it
288 might be deleted out from under you the next time the cache is
289 invalidated).
290 AV* mro_get_linear_isa_dfs(HV* stash, U32 level)
292 mro_isa_changed_in
294 Takes the necessary steps (cache invalidations, mostly) when
295 the @ISA of the given package has changed. Invoked by the
296 "setisa" magic, should not need to invoke directly.
297 void mro_isa_changed_in(HV* stash)
299
301 CvPADLIST
302 CV's can have CvPADLIST(cv) set to point to an AV.
303 For these purposes "forms" are a kind-of CV, eval""s are too
305 (except they're not callable at will and are always thrown away
306 after the eval"" is done executing). Require'd files are simply
307 evals without any outer lexical scope.
308 XSUBs don't have CvPADLIST set - dXSTARG fetches values from
310 PL_curpad, but that is really the callers pad (a slot of which
311 is allocated by every entersub).
312 The CvPADLIST AV has does not have AvREAL set, so REFCNT of
314 component items is managed "manual" (mostly in pad.c) rather
315 than normal av.c rules. The items in the AV are not SVs as for
316 a normal AV, but other AVs:
317 0'th Entry of the CvPADLIST is an AV which represents the
319 "names" or rather the "static type information" for lexicals.
320 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the
322 stack frame at that depth of recursion into the CV. The 0'th
323 slot of a frame AV is an AV which is @_. other entries are
324 storage for variables and op targets.
325 During compilation: "PL_comppad_name" is set to the names AV.
327 "PL_comppad" is set to the frame AV for the frame CvDEPTH == 1.
328 "PL_curpad" is set to the body of the frame AV (i.e.
329 AvARRAY(PL_comppad)).
330 During execution, "PL_comppad" and "PL_curpad" refer to the
332 live frame of the currently executing sub.
333 Iterating over the names AV iterates over all possible pad
335 items. Pad slots that are SVs_PADTMP (targets/GVs/constants)
336 end up having &PL_sv_undef "names" (see pad_alloc()).
337 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid
339 names. The rest are op targets/GVs/constants which are
340 statically allocated or resolved at compile time. These don't
341 have names by which they can be looked up from Perl code at run
342 time through eval"" like my/our variables can be. Since they
343 can't be looked up by "name" but only by their index allocated
344 at compile time (which is usually in PL_op->op_targ), wasting a
345 name SV for them doesn't make sense.
346 The SVs in the names AV have their PV being the name of the
348 variable. xlow+1..xhigh inclusive in the NV union is a range
349 of cop_seq numbers for which the name is valid. For typed
350 lexicals name SV is SVt_PVMG and SvSTASH points at the type.
351 For "our" lexicals, the type is also SVt_PVMG, with the
352 SvOURSTASH slot pointing at the stash of the associated global
353 (so that duplicate "our" declarations in the same package can
354 be detected). SvUVX is sometimes hijacked to store the
355 generation number during compilation.
356 If SvFAKE is set on the name SV, then that slot in the frame AV
358 is a REFCNT'ed reference to a lexical from "outside". In this
359 case, the name SV does not use xlow and xhigh to store a
360 cop_seq range, since it is in scope throughout. Instead xhigh
361 stores some flags containing info about the real lexical (is it
362 declared in an anon, and is it capable of being instantiated
363 multiple times?), and for fake ANONs, xlow contains the index
364 within the parent's pad where the lexical's value is stored, to
365 make cloning quicker.
366 If the 'name' is '&' the corresponding entry in frame AV is a
368 CV representing a possible closure. (SvFAKE and name of '&' is
369 not a meaningful combination currently but could become so if
370 "my sub foo {}" is implemented.)
371 Note that formats are treated as anon subs, and are cloned each
373 time write is called (if necessary).
374 The flag SVf_PADSTALE is cleared on lexicals each time the my()
376 is executed, and set on scope exit. This allows the 'Variable
377 $x is not available' warning to be generated in evals, such as
378 { my $x = 1; sub f { eval '$x'} } f();
380 For state vars, SVf_PADSTALE is overloaded to mean 'not yet
382 initialised'
383 AV * CvPADLIST(CV *cv)
385 cv_clone
387 Clone a CV: make a new CV which points to the same code etc,
388 but which has a newly-created pad built by copying the
389 prototype pad and capturing any outer lexicals.
390 CV* cv_clone(CV* proto)
392 cv_dump dump the contents of a CV
394 void cv_dump(const CV *cv, const char *title)
396 do_dump_pad
398 Dump the contents of a padlist
399 void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
401 intro_my
403 "Introduce" my variables to visible status.
404 U32 intro_my()
406 pad_add_anon
408 Add an anon code entry to the current compiling pad
409 PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
411 pad_add_name
413 Create a new name and associated PADMY SV in the current pad;
414 return the offset. If "typestash" is valid, the name is for a
415 typed lexical; set the name's stash to that value. If
416 "ourstash" is valid, it's an our lexical, set the name's
417 SvOURSTASH to that value
418 If fake, it means we're cloning an existing entry
420 PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state)
422 pad_alloc
424 Allocate a new my or tmp pad entry. For a my, simply push a
425 null SV onto the end of PL_comppad, but for a tmp, scan the pad
426 from PL_padix upwards for a slot which has no name and no
427 active value.
428 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
430 pad_block_start
432 Update the pad compilation state variables on entry to a new
433 block
434 void pad_block_start(int full)
436 pad_check_dup
438 Check for duplicate declarations: report any of:
439 * a my in the current scope with the same name;
440 * an our (anywhere in the pad) with the same name and the
441 same stash
442 as "ourstash" "is_our" indicates that the name to check
443 is an 'our' declaration
444 void pad_check_dup(const char* name, bool is_our, const HV* ourstash)
446 pad_findlex
448 Find a named lexical anywhere in a chain of nested pads. Add
449 fake entries in the inner pads if it's found in an outer one.
450 Returns the offset in the bottom pad of the lex or the fake
452 lex. cv is the CV in which to start the search, and seq is the
453 current cop_seq to match against. If warn is true, print
454 appropriate warnings. The out_* vars return values, and so are
455 pointers to where the returned values should be stored.
456 out_capture, if non-null, requests that the innermost instance
457 of the lexical is captured; out_name_sv is set to the innermost
458 matched namesv or fake namesv; out_flags returns the flags
459 normally associated with the IVX field of a fake namesv.
460 Note that pad_findlex() is recursive; it recurses up the chain
462 of CVs, then comes back down, adding fake entries as it goes.
463 It has to be this way because fake namesvs in anon protoypes
464 have to store in xlow the index into the parent pad.
465 PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
467 pad_findmy
469 Given a lexical name, try to find its offset, first in the
470 current pad, or failing that, in the pads of any lexically
471 enclosing subs (including the complications introduced by
472 eval). If the name is found in an outer pad, then a fake entry
473 is added to the current pad. Returns the offset in the current
474 pad, or NOT_IN_PAD on failure.
475 PADOFFSET pad_findmy(const char* name)
477 pad_fixup_inner_anons
479 For any anon CVs in the pad, change CvOUTSIDE of that CV from
480 old_cv to new_cv if necessary. Needed when a newly-compiled CV
481 has to be moved to a pre-existing CV struct.
482 void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
484 pad_free
486 Free the SV at offset po in the current pad.
487 void pad_free(PADOFFSET po)
489 pad_leavemy
491 Cleanup at end of scope during compilation: set the max seq
492 number for lexicals in this scope and warn of any lexicals that
493 never got introduced.
494 void pad_leavemy()
496 pad_new Create a new compiling padlist, saving and updating the various
498 global vars at the same time as creating the pad itself. The
499 following flags can be OR'ed together:
500 padnew_CLONE this pad is for a cloned CV
502 padnew_SAVE save old globals
503 padnew_SAVESUB also save extra stuff for start of sub
504 PADLIST* pad_new(int flags)
506 pad_push
508 Push a new pad frame onto the padlist, unless there's already a
509 pad at this depth, in which case don't bother creating a new
510 one. Then give the new pad an @_ in slot zero.
511 void pad_push(PADLIST *padlist, int depth)
513 pad_reset
515 Mark all the current temporaries for reuse
516 void pad_reset()
518 pad_setsv
520 Set the entry at offset po in the current pad to sv. Use the
521 macro PAD_SETSV() rather than calling this function directly.
522 void pad_setsv(PADOFFSET po, SV* sv)
524 pad_swipe
526 Abandon the tmp in the current pad at offset po and replace
527 with a new one.
528 void pad_swipe(PADOFFSET po, bool refadjust)
530 pad_tidy
532 Tidy up a pad after we've finished compiling it:
533 * remove most stuff from the pads of anonsub prototypes;
534 * give it a @_;
535 * mark tmps as such.
536 void pad_tidy(padtidy_type type)
538 pad_undef
540 Free the padlist associated with a CV. If parts of it happen
541 to be current, we null the relevant PL_*pad* global vars so
542 that we don't have any dangling references left. We also
543 repoint the CvOUTSIDE of any about-to-be-orphaned inner subs to
544 the outer of this cv.
545 (This function should really be called pad_free, but the name
547 was already taken)
548 void pad_undef(CV* cv)
550
552 PL_DBsingle
553 When Perl is run in debugging mode, with the -d switch, this SV
554 is a boolean which indicates whether subs are being single-
555 stepped. Single-stepping is automatically turned on after
556 every step. This is the C variable which corresponds to Perl's
557 $DB::single variable. See "PL_DBsub".
558 SV * PL_DBsingle
560 PL_DBsub
562 When Perl is run in debugging mode, with the -d switch, this GV
563 contains the SV which holds the name of the sub being debugged.
564 This is the C variable which corresponds to Perl's $DB::sub
565 variable. See "PL_DBsingle".
566 GV * PL_DBsub
568 PL_DBtrace
570 Trace variable used when Perl is run in debugging mode, with
571 the -d switch. This is the C variable which corresponds to
572 Perl's $DB::trace variable. See "PL_DBsingle".
573 SV * PL_DBtrace
575 PL_dowarn
577 The C variable which corresponds to Perl's $^W warning
578 variable.
579 bool PL_dowarn
581 PL_last_in_gv
583 The GV which was last used for a filehandle input operation.
584 ("<FH>")
585 GV* PL_last_in_gv
587 PL_ofs_sv
589 The output field separator - $, in Perl space.
590 SV* PL_ofs_sv
592 PL_rs The input record separator - $/ in Perl space.
594 SV* PL_rs
596
598 djSP Declare Just "SP". This is actually identical to "dSP", and
599 declares a local copy of perl's stack pointer, available via
600 the "SP" macro. See "SP". (Available for backward source code
601 compatibility with the old (Perl 5.005) thread model.)
602 djSP;
604 LVRET True if this op will be the return value of an lvalue
606 subroutine
607
609 sv_add_arena
610 Given a chunk of memory, link it to the head of the list of
611 arenas, and split it into a list of free SVs.
612 void sv_add_arena(char* ptr, U32 size, U32 flags)
614 sv_clean_all
616 Decrement the refcnt of each remaining SV, possibly triggering
617 a cleanup. This function may have to be called multiple times
618 to free SVs which are in complex self-referential hierarchies.
619 I32 sv_clean_all()
621 sv_clean_objs
623 Attempt to destroy all objects not yet freed
624 void sv_clean_objs()
626 sv_free_arenas
628 Deallocate the memory used by all arenas. Note that all the
629 individual SV heads and bodies within the arenas must already
630 have been freed.
631 void sv_free_arenas()
633
635 sv_2num Return an SV with the numeric value of the source SV, doing any
636 necessary reference or overload conversion. You must use the
637 "SvNUM(sv)" macro to access this function.
638 SV* sv_2num(SV* sv)
640
642 find_uninit_var
643 Find the name of the undefined variable (if any) that caused
644 the operator o to issue a "Use of uninitialized value" warning.
645 If match is true, only return a name if it's value matches
646 uninit_sv. So roughly speaking, if a unary operator (such as
647 OP_COS) generates a warning, then following the direct child of
648 the op may yield an OP_PADSV or OP_GV that gives the name of
649 the undefined variable. On the other hand, with OP_ADD there
650 are two branches to follow, so we only print the variable name
651 if we get an exact match.
652 The name is returned as a mortal SV.
654 Assumes that PL_op is the op that originally triggered the
656 error, and that PL_comppad/PL_curpad points to the currently
657 executing pad.
658 SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top)
660 report_uninit
662 Print appropriate "Use of uninitialized variable" warning
663 void report_uninit(SV* uninit_sv)
665
667 The autodocumentation system was originally added to the Perl core by
668 Benjamin Stuhl. Documentation is by whoever was kind enough to document
669 their functions.
670
672 perlguts(1), perlapi(1)
673perl v5.10.1 2017-03-22 PERLINTERN(1)