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 enclos‐
18 ing CV (if any). Because pointers to anonymous sub prototypes
19 are stored in "&" pad slots, it is a possible to get a circular
20 reference, with the parent pointing to the child and
21 vice-versa. To avoid the ensuing memory leak, we do not incre‐
22 ment the reference count of the CV pointed to by "CvOUTSIDE" in
23 the one specific instance that the parent has a "&" pad slot
24 pointing back to us. In this case, we set the "CvWEAKOUTSIDE"
25 flag in the child. This allows us to determine under what cir‐
26 cumstances we should decrement the refcount of the parent when
27 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 proto‐
39 type has "CvWEAKOUTSIDE" set since it's not a closure, and $a
40 points to the same CV, so it doesn't contribute to BEGIN's ref‐
41 count either. When $a is executed, the "eval '$x'" causes the
42 chain of "CvOUTSIDE"s to be followed, and the freed BEGIN is
43 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 posi‐
48 tive, 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 ref‐
51 erences (such as $a above).
52 One other thing to consider is that a CV may be merely unde‐
54 fined 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 lexi‐
59 cal scopes is unbroken. For example, the following should print
60 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_PARAMS* param Clone the state variables associated with
90 running and compiling pads.
91 void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
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 "SvCUR" 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 "SvCUR_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)
168 PAD_SET_CUR_NOSAVE
170 like PAD_SET_CUR, but without the save
171 void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
173 PAD_SV Get the value at offset "po" in the current pad
175 void PAD_SV(PADOFFSET po)
177 PAD_SVl Lightweight and lvalue version of "PAD_SV". Get or set the
179 value at offset "po" in the current pad. Unlike "PAD_SV", does
180 not print diagnostics with -DX. For internal use only.
181 SV * PAD_SVl(PADOFFSET po)
183 SAVECLEARSV
185 Clear the pointed to pad value on scope exit. (i.e. the runtime
186 action of 'my')
187 void SAVECLEARSV(SV **svp)
189 SAVECOMPPAD
191 save PL_comppad and PL_curpad
192 void SAVECOMPPAD()
194 SAVEPADSV
196 Save a pad slot (used to restore after an iteration)
197 XXX DAPM it would make more sense to make the arg a PADOFFSET
199 void SAVEPADSV(PADOFFSET po)
200
202 find_runcv
203 Locate the CV corresponding to the currently executing sub or
204 eval. If db_seqp is non_null, skip CVs that are in the DB
205 package and populate *db_seqp with the cop sequence number at
206 the point that the DB:: code was entered. (allows debuggers to
207 eval in the scope of the breakpoint rather than in the scope of
208 the debugger itself).
209 CV* find_runcv(U32 *db_seqp)
211
213 PL_DBsingle
214 When Perl is run in debugging mode, with the -d switch, this SV
215 is a boolean which indicates whether subs are being sin‐
216 gle-stepped. Single-stepping is automatically turned on after
217 every step. This is the C variable which corresponds to Perl's
218 $DB::single variable. See "PL_DBsub".
219 SV * PL_DBsingle
221 PL_DBsub
223 When Perl is run in debugging mode, with the -d switch, this GV
224 contains the SV which holds the name of the sub being debugged.
225 This is the C variable which corresponds to Perl's $DB::sub
226 variable. See "PL_DBsingle".
227 GV * PL_DBsub
229 PL_DBtrace
231 Trace variable used when Perl is run in debugging mode, with
232 the -d switch. This is the C variable which corresponds to
233 Perl's $DB::trace variable. See "PL_DBsingle".
234 SV * PL_DBtrace
236 PL_dowarn
238 The C variable which corresponds to Perl's $^W warning vari‐
239 able.
240 bool PL_dowarn
242 PL_last_in_gv
244 The GV which was last used for a filehandle input operation.
245 ("<FH>")
246 GV* PL_last_in_gv
248 PL_ofs_sv
250 The output field separator - $, in Perl space.
251 SV* PL_ofs_sv
253 PL_rs The input record separator - $/ in Perl space.
255 SV* PL_rs
257
259 is_gv_magical
260 Returns "TRUE" if given the name of a magical GV.
261 Currently only useful internally when determining if a GV
263 should be created even in rvalue contexts.
264 "flags" is not used at present but available for future exten‐
266 sion to allow selecting particular classes of magical variable.
267 Currently assumes that "name" is NUL terminated (as well as len
269 being valid). This assumption is met by all callers within the
270 perl core, which all pass pointers returned by SvPV.
271 bool is_gv_magical(char *name, STRLEN len, U32 flags)
273
275 start_glob
276 Function called by "do_readline" to spawn a glob (or do the
277 glob inside perl on VMS). This code used to be inline, but now
278 perl uses "File::Glob" this glob starter is only used by
279 miniperl during the build process. Moving it away shrinks
280 pp_hot.c; shrinking pp_hot.c helps speed perl up.
281 PerlIO* start_glob(SV* pattern, IO *io)
283
285 CvPADLIST
286 CV's can have CvPADLIST(cv) set to point to an AV.
287 For these purposes "forms" are a kind-of CV, eval""s are too
289 (except they're not callable at will and are always thrown away
290 after the eval"" is done executing).
291 XSUBs don't have CvPADLIST set - dXSTARG fetches values from
293 PL_curpad, but that is really the callers pad (a slot of which
294 is allocated by every entersub).
295 The CvPADLIST AV has does not have AvREAL set, so REFCNT of
297 component items is managed "manual" (mostly in pad.c) rather
298 than normal av.c rules. The items in the AV are not SVs as for
299 a normal AV, but other AVs:
300 0'th Entry of the CvPADLIST is an AV which represents the
302 "names" or rather the "static type information" for lexicals.
303 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the
305 stack frame at that depth of recursion into the CV. The 0'th
306 slot of a frame AV is an AV which is @_. other entries are
307 storage for variables and op targets.
308 During compilation: "PL_comppad_name" is set to the names AV.
310 "PL_comppad" is set to the frame AV for the frame CvDEPTH == 1.
311 "PL_curpad" is set to the body of the frame AV (i.e. AvAR‐
312 RAY(PL_comppad)).
313 During execution, "PL_comppad" and "PL_curpad" refer to the
315 live frame of the currently executing sub.
316 Iterating over the names AV iterates over all possible pad
318 items. Pad slots that are SVs_PADTMP (targets/GVs/constants)
319 end up having &PL_sv_undef "names" (see pad_alloc()).
320 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid
322 names. The rest are op targets/GVs/constants which are stati‐
323 cally allocated or resolved at compile time. These don't have
324 names by which they can be looked up from Perl code at run time
325 through eval"" like my/our variables can be. Since they can't
326 be looked up by "name" but only by their index allocated at
327 compile time (which is usually in PL_op->op_targ), wasting a
328 name SV for them doesn't make sense.
329 The SVs in the names AV have their PV being the name of the
331 variable. NV+1..IV inclusive is a range of cop_seq numbers for
332 which the name is valid. For typed lexicals name SV is
333 SVt_PVMG and SvSTASH points at the type. For "our" lexicals,
334 the type is SVt_PVGV, and GvSTASH points at the stash of the
335 associated global (so that duplicate "our" declarations in the
336 same package can be detected). SvCUR is sometimes hijacked to
337 store the generation number during compilation.
338 If SvFAKE is set on the name SV then slot in the frame AVs are
340 a REFCNT'ed references to a lexical from "outside". In this
341 case, the name SV does not have a cop_seq range, since it is in
342 scope throughout.
343 If the 'name' is '&' the corresponding entry in frame AV is a
345 CV representing a possible closure. (SvFAKE and name of '&' is
346 not a meaningful combination currently but could become so if
347 "my sub foo {}" is implemented.)
348 The flag SVf_PADSTALE is cleared on lexicals each time the my()
350 is executed, and set on scope exit. This allows the 'Variable
351 $x is not available' warning to be generated in evals, such as
352 { my $x = 1; sub f { eval '$x'} } f();
354 AV * CvPADLIST(CV *cv)
356 cv_clone
358 Clone a CV: make a new CV which points to the same code etc,
359 but which has a newly-created pad built by copying the proto‐
360 type pad and capturing any outer lexicals.
361 CV* cv_clone(CV* proto)
363 cv_dump dump the contents of a CV
365 void cv_dump(const CV *cv, const char *title)
367 do_dump_pad
369 Dump the contents of a padlist
370 void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
372 intro_my
374 "Introduce" my variables to visible status.
375 U32 intro_my()
377 pad_add_anon
379 Add an anon code entry to the current compiling pad
380 PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
382 pad_add_name
384 Create a new name in the current pad at the specified offset.
385 If "typestash" is valid, the name is for a typed lexical; set
386 the name's stash to that value. If "ourstash" is valid, it's
387 an our lexical, set the name's GvSTASH to that value
388 Also, if the name is @.. or %.., create a new array or hash for
390 that slot
391 If fake, it means we're cloning an existing entry
393 PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
395 pad_alloc
397 Allocate a new my or tmp pad entry. For a my, simply push a
398 null SV onto the end of PL_comppad, but for a tmp, scan the pad
399 from PL_padix upwards for a slot which has no name and no
400 active value.
401 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
403 pad_block_start
405 Update the pad compilation state variables on entry to a new
406 block
407 void pad_block_start(int full)
409 pad_check_dup
411 Check for duplicate declarations: report any of:
412 * a my in the current scope with the same name;
413 * an our (anywhere in the pad) with the same name and the
414 same stash
415 as "ourstash" "is_our" indicates that the name to check
416 is an 'our' declaration
417 void pad_check_dup(char* name, bool is_our, HV* ourstash)
419 pad_findlex
421 Find a named lexical anywhere in a chain of nested pads. Add
422 fake entries in the inner pads if it's found in an outer one.
423 innercv is the CV *inside* the chain of outer CVs to be
424 searched. If newoff is non-null, this is a run-time cloning:
425 don't add fake entries, just find the lexical and add a ref to
426 it at newoff in the current pad.
427 PADOFFSET pad_findlex(const char* name, PADOFFSET newoff, const CV* innercv)
429 pad_findmy
431 Given a lexical name, try to find its offset, first in the cur‐
432 rent pad, or failing that, in the pads of any lexically enclos‐
433 ing subs (including the complications introduced by eval). If
434 the name is found in an outer pad, then a fake entry is added
435 to the current pad. Returns the offset in the current pad, or
436 NOT_IN_PAD on failure.
437 PADOFFSET pad_findmy(char* name)
439 pad_fixup_inner_anons
441 For any anon CVs in the pad, change CvOUTSIDE of that CV from
442 old_cv to new_cv if necessary. Needed when a newly-compiled CV
443 has to be moved to a pre-existing CV struct.
444 void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
446 pad_free
448 Free the SV at offset po in the current pad.
449 void pad_free(PADOFFSET po)
451 pad_leavemy
453 Cleanup at end of scope during compilation: set the max seq
454 number for lexicals in this scope and warn of any lexicals that
455 never got introduced.
456 void pad_leavemy()
458 pad_new Create a new compiling padlist, saving and updating the various
460 global vars at the same time as creating the pad itself. The
461 following flags can be OR'ed together:
462 padnew_CLONE this pad is for a cloned CV
464 padnew_SAVE save old globals
465 padnew_SAVESUB also save extra stuff for start of sub
466 PADLIST* pad_new(int flags)
468 pad_push
470 Push a new pad frame onto the padlist, unless there's already a
471 pad at this depth, in which case don't bother creating a new
472 one. If has_args is true, give the new pad an @_ in slot zero.
473 void pad_push(PADLIST *padlist, int depth, int has_args)
475 pad_reset
477 Mark all the current temporaries for reuse
478 void pad_reset()
480 pad_setsv
482 Set the entry at offset po in the current pad to sv. Use the
483 macro PAD_SETSV() rather than calling this function directly.
484 void pad_setsv(PADOFFSET po, SV* sv)
486 pad_swipe
488 Abandon the tmp in the current pad at offset po and replace
489 with a new one.
490 void pad_swipe(PADOFFSET po, bool refadjust)
492 pad_tidy
494 Tidy up a pad after we've finished compiling it:
495 * remove most stuff from the pads of anonsub prototypes;
496 * give it a @_;
497 * mark tmps as such.
498 void pad_tidy(padtidy_type type)
500 pad_undef
502 Free the padlist associated with a CV. If parts of it happen
503 to be current, we null the relevant PL_*pad* global vars so
504 that we don't have any dangling references left. We also
505 repoint the CvOUTSIDE of any about-to-be-orphaned inner subs to
506 the outer of this cv.
507 (This function should really be called pad_free, but the name
509 was already taken)
510 void pad_undef(CV* cv)
512
514 djSP Declare Just "SP". This is actually identical to "dSP", and
515 declares a local copy of perl's stack pointer, available via
516 the "SP" macro. See "SP". (Available for backward source code
517 compatibility with the old (Perl 5.005) thread model.)
518 djSP;
520 LVRET True if this op will be the return value of an lvalue subrou‐
522 tine
523
525 report_uninit
526 Print appropriate "Use of uninitialized variable" warning
527 void report_uninit()
529 sv_add_arena
531 Given a chunk of memory, link it to the head of the list of
532 arenas, and split it into a list of free SVs.
533 void sv_add_arena(char* ptr, U32 size, U32 flags)
535 sv_clean_all
537 Decrement the refcnt of each remaining SV, possibly triggering
538 a cleanup. This function may have to be called multiple times
539 to free SVs which are in complex self-referential hierarchies.
540 I32 sv_clean_all()
542 sv_clean_objs
544 Attempt to destroy all objects not yet freed
545 void sv_clean_objs()
547 sv_free_arenas
549 Deallocate the memory used by all arenas. Note that all the
550 individual SV heads and bodies within the arenas must already
551 have been freed.
552 void sv_free_arenas()
554
556 The autodocumentation system was originally added to the Perl core by
557 Benjamin Stuhl. Documentation is by whoever was kind enough to document
558 their functions.
559
561 perlguts(1), perlapi(1)
562perl v5.8.8 2006-01-07 PERLINTERN(1)