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,
13 they are not for use in extensions!
14
16 BhkENTRY
17 NOTE: this function is experimental and may change or be
18 removed without notice.
19 Return an entry from the BHK structure. "which" is a
21 preprocessor token indicating which entry to return. If the
22 appropriate flag is not set this will return "NULL". The type
23 of the return value depends on which entry you ask for.
24 void * BhkENTRY(BHK *hk, which)
26 BhkFLAGS
28 NOTE: this function is experimental and may change or be
29 removed without notice.
30 Return the BHK's flags.
32 U32 BhkFLAGS(BHK *hk)
34 CALL_BLOCK_HOOKS
36 NOTE: this function is experimental and may change or be
37 removed without notice.
38 Call all the registered block hooks for type "which". "which"
40 is a preprocessing token; the type of "arg" depends on "which".
41 void CALL_BLOCK_HOOKS(which, arg)
43
45 core_prototype
46 This function assigns the prototype of the named core function
47 to "sv", or to a new mortal SV if "sv" is "NULL". It returns
48 the modified "sv", or "NULL" if the core function has no
49 prototype. "code" is a code as returned by "keyword()". It
50 must not be equal to 0.
51 SV * core_prototype(SV *sv, const char *name,
53 const int code,
54 int * const opnum)
55
57 docatch Check for the cases 0 or 3 of cur_env.je_ret, only used inside
58 an eval context.
59 0 is used as continue inside eval,
61 3 is used for a die caught by an inner eval - continue inner
63 loop
64 See cop.h: je_mustcatch, when set at any runlevel to TRUE,
66 means eval ops must establish a local jmpenv to handle
67 exception traps.
68 OP* docatch(Perl_ppaddr_t firstpp)
70
72 CvWEAKOUTSIDE
73 Each CV has a pointer, "CvOUTSIDE()", to its lexically
74 enclosing CV (if any). Because pointers to anonymous sub
75 prototypes are stored in "&" pad slots, it is a possible to get
76 a circular reference, with the parent pointing to the child and
77 vice-versa. To avoid the ensuing memory leak, we do not
78 increment the reference count of the CV pointed to by
79 "CvOUTSIDE" in the one specific instance that the parent has a
80 "&" pad slot pointing back to us. In this case, we set the
81 "CvWEAKOUTSIDE" flag in the child. This allows us to determine
82 under what circumstances we should decrement the refcount of
83 the parent when freeing the child.
84 There is a further complication with non-closure anonymous subs
86 (i.e. those that do not refer to any lexicals outside that
87 sub). In this case, the anonymous prototype is shared rather
88 than being cloned. This has the consequence that the parent
89 may be freed while there are still active children, e.g.,
90 BEGIN { $a = sub { eval '$x' } }
92 In this case, the BEGIN is freed immediately after execution
94 since there are no active references to it: the anon sub
95 prototype has "CvWEAKOUTSIDE" set since it's not a closure, and
96 $a points to the same CV, so it doesn't contribute to BEGIN's
97 refcount either. When $a is executed, the "eval '$x'" causes
98 the chain of "CvOUTSIDE"s to be followed, and the freed BEGIN
99 is accessed.
100 To avoid this, whenever a CV and its associated pad is freed,
102 any "&" entries in the pad are explicitly removed from the pad,
103 and if the refcount of the pointed-to anon sub is still
104 positive, then that child's "CvOUTSIDE" is set to point to its
105 grandparent. This will only occur in the single specific case
106 of a non-closure anon prototype having one or more active
107 references (such as $a above).
108 One other thing to consider is that a CV may be merely
110 undefined rather than freed, eg "undef &foo". In this case,
111 its refcount may not have reached zero, but we still delete its
112 pad and its "CvROOT" etc. Since various children may still
113 have their "CvOUTSIDE" pointing at this undefined CV, we keep
114 its own "CvOUTSIDE" for the time being, so that the chain of
115 lexical scopes is unbroken. For example, the following should
116 print 123:
117 my $x = 123;
119 sub tmp { sub { eval '$x' } }
120 my $a = tmp();
121 undef &tmp;
122 print $a->();
123 bool CvWEAKOUTSIDE(CV *cv)
125
127 cv_dump dump the contents of a CV
128 void cv_dump(CV *cv, const char *title)
130 cv_forget_slab
132 When a CV has a reference count on its slab ("CvSLABBED"), it
133 is responsible for making sure it is freed. (Hence, no two CVs
134 should ever have a reference count on the same slab.) The CV
135 only needs to reference the slab during compilation. Once it
136 is compiled and "CvROOT" attached, it has finished its job, so
137 it can forget the slab.
138 void cv_forget_slab(CV *cv)
140 do_dump_pad
142 Dump the contents of a padlist
143 void do_dump_pad(I32 level, PerlIO *file,
145 PADLIST *padlist, int full)
146 pad_alloc_name
148 Allocates a place in the currently-compiling pad (via
149 "pad_alloc" in perlapi) and then stores a name for that entry.
150 "name" is adopted and becomes the name entry; it must already
151 contain the name string. "typestash" and "ourstash" and the
152 "padadd_STATE" flag get added to "name". None of the other
153 processing of "pad_add_name_pvn" in perlapi is done. Returns
154 the offset of the allocated pad slot.
155 PADOFFSET pad_alloc_name(PADNAME *name, U32 flags,
157 HV *typestash, HV *ourstash)
158 pad_block_start
160 Update the pad compilation state variables on entry to a new
161 block.
162 void pad_block_start(int full)
164 pad_check_dup
166 Check for duplicate declarations: report any of:
167 * a 'my' in the current scope with the same name;
169 * an 'our' (anywhere in the pad) with the same name and the
170 same stash as 'ourstash'
171 "is_our" indicates that the name to check is an "our"
173 declaration.
174 void pad_check_dup(PADNAME *name, U32 flags,
176 const HV *ourstash)
177 pad_findlex
179 Find a named lexical anywhere in a chain of nested pads. Add
180 fake entries in the inner pads if it's found in an outer one.
181 Returns the offset in the bottom pad of the lex or the fake
183 lex. "cv" is the CV in which to start the search, and seq is
184 the current "cop_seq" to match against. If "warn" is true,
185 print appropriate warnings. The "out_"* vars return values,
186 and so are pointers to where the returned values should be
187 stored. "out_capture", if non-null, requests that the
188 innermost instance of the lexical is captured; "out_name" is
189 set to the innermost matched pad name or fake pad name;
190 "out_flags" returns the flags normally associated with the
191 "PARENT_FAKELEX_FLAGS" field of a fake pad name.
192 Note that "pad_findlex()" is recursive; it recurses up the
194 chain of CVs, then comes back down, adding fake entries as it
195 goes. It has to be this way because fake names in anon
196 protoypes have to store in "xpadn_low" the index into the
197 parent pad.
198 PADOFFSET pad_findlex(const char *namepv,
200 STRLEN namelen, U32 flags,
201 const CV* cv, U32 seq, int warn,
202 SV** out_capture,
203 PADNAME** out_name,
204 int *out_flags)
205 pad_fixup_inner_anons
207 For any anon CVs in the pad, change "CvOUTSIDE" of that CV from
208 "old_cv" to "new_cv" if necessary. Needed when a newly-
209 compiled CV has to be moved to a pre-existing CV struct.
210 void pad_fixup_inner_anons(PADLIST *padlist,
212 CV *old_cv, CV *new_cv)
213 pad_free
215 Free the SV at offset po in the current pad.
216 void pad_free(PADOFFSET po)
218 pad_leavemy
220 Cleanup at end of scope during compilation: set the max seq
221 number for lexicals in this scope and warn of any lexicals that
222 never got introduced.
223 void pad_leavemy()
225 padlist_dup
227 Duplicates a pad.
228 PADLIST * padlist_dup(PADLIST *srcpad,
230 CLONE_PARAMS *param)
231 padname_dup
233 Duplicates a pad name.
234 PADNAME * padname_dup(PADNAME *src, CLONE_PARAMS *param)
236 padnamelist_dup
238 Duplicates a pad name list.
239 PADNAMELIST * padnamelist_dup(PADNAMELIST *srcpad,
241 CLONE_PARAMS *param)
242 pad_push
244 Push a new pad frame onto the padlist, unless there's already a
245 pad at this depth, in which case don't bother creating a new
246 one. Then give the new pad an @_ in slot zero.
247 void pad_push(PADLIST *padlist, int depth)
249 pad_reset
251 Mark all the current temporaries for reuse
252 void pad_reset()
254 pad_swipe
256 Abandon the tmp in the current pad at offset "po" and replace
257 with a new one.
258 void pad_swipe(PADOFFSET po, bool refadjust)
260
262 gv_try_downgrade
263 NOTE: this function is experimental and may change or be
264 removed without notice.
265 If the typeglob "gv" can be expressed more succinctly, by
267 having something other than a real GV in its place in the
268 stash, replace it with the optimised form. Basic requirements
269 for this are that "gv" is a real typeglob, is sufficiently
270 ordinary, and is only referenced from its package. This
271 function is meant to be used when a GV has been looked up in
272 part to see what was there, causing upgrading, but based on
273 what was found it turns out that the real GV isn't required
274 after all.
275 If "gv" is a completely empty typeglob, it is deleted from the
277 stash.
278 If "gv" is a typeglob containing only a sufficiently-ordinary
280 constant sub, the typeglob is replaced with a scalar-reference
281 placeholder that more compactly represents the same thing.
282 void gv_try_downgrade(GV* gv)
284
286 hv_ename_add
287 Adds a name to a stash's internal list of effective names. See
288 "hv_ename_delete".
289 This is called when a stash is assigned to a new location in
291 the symbol table.
292 void hv_ename_add(HV *hv, const char *name, U32 len,
294 U32 flags)
295 hv_ename_delete
297 Removes a name from a stash's internal list of effective names.
298 If this is the name returned by "HvENAME", then another name in
299 the list will take its place ("HvENAME" will use it).
300 This is called when a stash is deleted from the symbol table.
302 void hv_ename_delete(HV *hv, const char *name,
304 U32 len, U32 flags)
305 refcounted_he_chain_2hv
307 Generates and returns a "HV *" representing the content of a
308 "refcounted_he" chain. "flags" is currently unused and must be
309 zero.
310 HV * refcounted_he_chain_2hv(
312 const struct refcounted_he *c, U32 flags
313 )
314 refcounted_he_fetch_pv
316 Like "refcounted_he_fetch_pvn", but takes a nul-terminated
317 string instead of a string/length pair.
318 SV * refcounted_he_fetch_pv(
320 const struct refcounted_he *chain,
321 const char *key, U32 hash, U32 flags
322 )
323 refcounted_he_fetch_pvn
325 Search along a "refcounted_he" chain for an entry with the key
326 specified by "keypv" and "keylen". If "flags" has the
327 "REFCOUNTED_HE_KEY_UTF8" bit set, the key octets are
328 interpreted as UTF-8, otherwise they are interpreted as
329 Latin-1. "hash" is a precomputed hash of the key string, or
330 zero if it has not been precomputed. Returns a mortal scalar
331 representing the value associated with the key, or
332 &PL_sv_placeholder if there is no value associated with the
333 key.
334 SV * refcounted_he_fetch_pvn(
336 const struct refcounted_he *chain,
337 const char *keypv, STRLEN keylen, U32 hash,
338 U32 flags
339 )
340 refcounted_he_fetch_pvs
342 Like "refcounted_he_fetch_pvn", but takes a "NUL"-terminated
343 literal string instead of a string/length pair, and no
344 precomputed hash.
345 SV * refcounted_he_fetch_pvs(
347 const struct refcounted_he *chain,
348 const char *key, U32 flags
349 )
350 refcounted_he_fetch_sv
352 Like "refcounted_he_fetch_pvn", but takes a Perl scalar instead
353 of a string/length pair.
354 SV * refcounted_he_fetch_sv(
356 const struct refcounted_he *chain, SV *key,
357 U32 hash, U32 flags
358 )
359 refcounted_he_free
361 Decrements the reference count of a "refcounted_he" by one. If
362 the reference count reaches zero the structure's memory is
363 freed, which (recursively) causes a reduction of its parent
364 "refcounted_he"'s reference count. It is safe to pass a null
365 pointer to this function: no action occurs in this case.
366 void refcounted_he_free(struct refcounted_he *he)
368 refcounted_he_inc
370 Increment the reference count of a "refcounted_he". The
371 pointer to the "refcounted_he" is also returned. It is safe to
372 pass a null pointer to this function: no action occurs and a
373 null pointer is returned.
374 struct refcounted_he * refcounted_he_inc(
376 struct refcounted_he *he
377 )
378 refcounted_he_new_pv
380 Like "refcounted_he_new_pvn", but takes a nul-terminated string
381 instead of a string/length pair.
382 struct refcounted_he * refcounted_he_new_pv(
384 struct refcounted_he *parent,
385 const char *key, U32 hash,
386 SV *value, U32 flags
387 )
388 refcounted_he_new_pvn
390 Creates a new "refcounted_he". This consists of a single
391 key/value pair and a reference to an existing "refcounted_he"
392 chain (which may be empty), and thus forms a longer chain.
393 When using the longer chain, the new key/value pair takes
394 precedence over any entry for the same key further along the
395 chain.
396 The new key is specified by "keypv" and "keylen". If "flags"
398 has the "REFCOUNTED_HE_KEY_UTF8" bit set, the key octets are
399 interpreted as UTF-8, otherwise they are interpreted as
400 Latin-1. "hash" is a precomputed hash of the key string, or
401 zero if it has not been precomputed.
402 "value" is the scalar value to store for this key. "value" is
404 copied by this function, which thus does not take ownership of
405 any reference to it, and later changes to the scalar will not
406 be reflected in the value visible in the "refcounted_he".
407 Complex types of scalar will not be stored with referential
408 integrity, but will be coerced to strings. "value" may be
409 either null or &PL_sv_placeholder to indicate that no value is
410 to be associated with the key; this, as with any non-null
411 value, takes precedence over the existence of a value for the
412 key further along the chain.
413 "parent" points to the rest of the "refcounted_he" chain to be
415 attached to the new "refcounted_he". This function takes
416 ownership of one reference to "parent", and returns one
417 reference to the new "refcounted_he".
418 struct refcounted_he * refcounted_he_new_pvn(
420 struct refcounted_he *parent,
421 const char *keypv,
422 STRLEN keylen, U32 hash,
423 SV *value, U32 flags
424 )
425 refcounted_he_new_pvs
427 Like "refcounted_he_new_pvn", but takes a "NUL"-terminated
428 literal string instead of a string/length pair, and no
429 precomputed hash.
430 struct refcounted_he * refcounted_he_new_pvs(
432 struct refcounted_he *parent,
433 const char *key, SV *value,
434 U32 flags
435 )
436 refcounted_he_new_sv
438 Like "refcounted_he_new_pvn", but takes a Perl scalar instead
439 of a string/length pair.
440 struct refcounted_he * refcounted_he_new_sv(
442 struct refcounted_he *parent,
443 SV *key, U32 hash, SV *value,
444 U32 flags
445 )
446
448 start_glob
449 NOTE: this function is experimental and may change or be
450 removed without notice.
451 Function called by "do_readline" to spawn a glob (or do the
453 glob inside perl on VMS). This code used to be inline, but now
454 perl uses "File::Glob" this glob starter is only used by
455 miniperl during the build process, or when PERL_EXTERNAL_GLOB
456 is defined. Moving it away shrinks pp_hot.c; shrinking
457 pp_hot.c helps speed perl up.
458 PerlIO* start_glob(SV *tmpglob, IO *io)
460
462 validate_proto
463 NOTE: this function is experimental and may change or be
464 removed without notice.
465 This function performs syntax checking on a prototype, "proto".
467 If "warn" is true, any illegal characters or mismatched
468 brackets will trigger illegalproto warnings, declaring that
469 they were detected in the prototype for "name".
470 The return value is "true" if this is a valid prototype, and
472 "false" if it is not, regardless of whether "warn" was "true"
473 or "false".
474 Note that "NULL" is a valid "proto" and will always return
476 "true".
477 NOTE: the perl_ form of this function is deprecated.
479 bool validate_proto(SV *name, SV *proto, bool warn)
481
483 magic_clearhint
484 Triggered by a delete from "%^H", records the key to
485 "PL_compiling.cop_hints_hash".
486 int magic_clearhint(SV* sv, MAGIC* mg)
488 magic_clearhints
490 Triggered by clearing "%^H", resets
491 "PL_compiling.cop_hints_hash".
492 int magic_clearhints(SV* sv, MAGIC* mg)
494 magic_methcall
496 Invoke a magic method (like FETCH).
497 "sv" and "mg" are the tied thingy and the tie magic.
499 "meth" is the name of the method to call.
501 "argc" is the number of args (in addition to $self) to pass to
503 the method.
504 The "flags" can be:
506 G_DISCARD invoke method with G_DISCARD flag and don't
508 return a value
509 G_UNDEF_FILL fill the stack with argc pointers to
510 PL_sv_undef
511 The arguments themselves are any values following the "flags"
513 argument.
514 Returns the SV (if any) returned by the method, or "NULL" on
516 failure.
517 SV* magic_methcall(SV *sv, const MAGIC *mg,
519 SV *meth, U32 flags, U32 argc,
520 ...)
521 magic_sethint
523 Triggered by a store to "%^H", records the key/value pair to
524 "PL_compiling.cop_hints_hash". It is assumed that hints aren't
525 storing anything that would need a deep copy. Maybe we should
526 warn if we find a reference.
527 int magic_sethint(SV* sv, MAGIC* mg)
529 mg_localize
531 Copy some of the magic from an existing SV to new localized
532 version of that SV. Container magic (e.g., %ENV, $1, "tie")
533 gets copied, value magic doesn't (e.g., "taint", "pos").
534 If "setmagic" is false then no set magic will be called on the
536 new (empty) SV. This typically means that assignment will soon
537 follow (e.g. 'local $x = $y'), and that will handle the magic.
538 void mg_localize(SV* sv, SV* nsv, bool setmagic)
540
542 free_c_backtrace
543 Deallocates a backtrace received from get_c_bracktrace.
544 void free_c_backtrace(Perl_c_backtrace* bt)
546 get_c_backtrace
548 Collects the backtrace (aka "stacktrace") into a single linear
549 malloced buffer, which the caller must
550 "Perl_free_c_backtrace()".
551 Scans the frames back by "depth + skip", then drops the "skip"
553 innermost, returning at most "depth" frames.
554 Perl_c_backtrace* get_c_backtrace(int max_depth,
556 int skip)
557
559 mro_get_linear_isa_dfs
560 Returns the Depth-First Search linearization of @ISA the given
561 stash. The return value is a read-only AV*. "level" should be
562 0 (it is used internally in this function's recursion).
563 You are responsible for "SvREFCNT_inc()" on the return value if
565 you plan to store it anywhere semi-permanently (otherwise it
566 might be deleted out from under you the next time the cache is
567 invalidated).
568 AV* mro_get_linear_isa_dfs(HV* stash, U32 level)
570 mro_isa_changed_in
572 Takes the necessary steps (cache invalidations, mostly) when
573 the @ISA of the given package has changed. Invoked by the
574 "setisa" magic, should not need to invoke directly.
575 void mro_isa_changed_in(HV* stash)
577 mro_package_moved
579 Call this function to signal to a stash that it has been
580 assigned to another spot in the stash hierarchy. "stash" is
581 the stash that has been assigned. "oldstash" is the stash it
582 replaces, if any. "gv" is the glob that is actually being
583 assigned to.
584 This can also be called with a null first argument to indicate
586 that "oldstash" has been deleted.
587 This function invalidates isa caches on the old stash, on all
589 subpackages nested inside it, and on the subclasses of all
590 those, including non-existent packages that have corresponding
591 entries in "stash".
592 It also sets the effective names ("HvENAME") on all the stashes
594 as appropriate.
595 If the "gv" is present and is not in the symbol table, then
597 this function simply returns. This checked will be skipped if
598 "flags & 1".
599 void mro_package_moved(HV * const stash,
601 HV * const oldstash,
602 const GV * const gv,
603 U32 flags)
604
606 finalize_optree
607 This function finalizes the optree. Should be called directly
608 after the complete optree is built. It does some additional
609 checking which can't be done in the normal "ck_"xxx functions
610 and makes the tree thread-safe.
611 void finalize_optree(OP* o)
613
615 CX_CURPAD_SAVE
616 Save the current pad in the given context block structure.
617 void CX_CURPAD_SAVE(struct context)
619 CX_CURPAD_SV
621 Access the SV at offset "po" in the saved current pad in the
622 given context block structure (can be used as an lvalue).
623 SV * CX_CURPAD_SV(struct context, PADOFFSET po)
625 PAD_BASE_SV
627 Get the value from slot "po" in the base (DEPTH=1) pad of a
628 padlist
629 SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
631 PAD_CLONE_VARS
633 Clone the state variables associated with running and compiling
634 pads.
635 void PAD_CLONE_VARS(PerlInterpreter *proto_perl,
637 CLONE_PARAMS* param)
638 PAD_COMPNAME_FLAGS
640 Return the flags for the current compiling pad name at offset
641 "po". Assumes a valid slot entry.
642 U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
644 PAD_COMPNAME_GEN
646 The generation number of the name at offset "po" in the current
647 compiling pad (lvalue).
648 STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
650 PAD_COMPNAME_GEN_set
652 Sets the generation number of the name at offset "po" in the
653 current ling pad (lvalue) to "gen".
654 STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
655 PAD_COMPNAME_OURSTASH
657 Return the stash associated with an "our" variable. Assumes
658 the slot entry is a valid "our" lexical.
659 HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
661 PAD_COMPNAME_PV
663 Return the name of the current compiling pad name at offset
664 "po". Assumes a valid slot entry.
665 char * PAD_COMPNAME_PV(PADOFFSET po)
667 PAD_COMPNAME_TYPE
669 Return the type (stash) of the current compiling pad name at
670 offset "po". Must be a valid name. Returns null if not typed.
671 HV * PAD_COMPNAME_TYPE(PADOFFSET po)
673 PadnameIsOUR
675 Whether this is an "our" variable.
676 bool PadnameIsOUR(PADNAME pn)
678 PadnameIsSTATE
680 Whether this is a "state" variable.
681 bool PadnameIsSTATE(PADNAME pn)
683 PadnameOURSTASH
685 The stash in which this "our" variable was declared.
686 HV * PadnameOURSTASH()
688 PadnameOUTER
690 Whether this entry belongs to an outer pad. Entries for which
691 this is true are often referred to as 'fake'.
692 bool PadnameOUTER(PADNAME pn)
694 PadnameTYPE
696 The stash associated with a typed lexical. This returns the
697 %Foo:: hash for "my Foo $bar".
698 HV * PadnameTYPE(PADNAME pn)
700 PAD_RESTORE_LOCAL
702 Restore the old pad saved into the local variable "opad" by
703 "PAD_SAVE_LOCAL()"
704 void PAD_RESTORE_LOCAL(PAD *opad)
706 PAD_SAVE_LOCAL
708 Save the current pad to the local variable "opad", then make
709 the current pad equal to "npad"
710 void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
712 PAD_SAVE_SETNULLPAD
714 Save the current pad then set it to null.
715 void PAD_SAVE_SETNULLPAD()
717 PAD_SETSV
719 Set the slot at offset "po" in the current pad to "sv"
720 SV * PAD_SETSV(PADOFFSET po, SV* sv)
722 PAD_SET_CUR
724 Set the current pad to be pad "n" in the padlist, saving the
725 previous current pad. NB currently this macro expands to a
726 string too long for some compilers, so it's best to replace it
727 with
728 SAVECOMPPAD();
730 PAD_SET_CUR_NOSAVE(padlist,n);
731 void PAD_SET_CUR(PADLIST padlist, I32 n)
734 PAD_SET_CUR_NOSAVE
736 like PAD_SET_CUR, but without the save
737 void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
739 PAD_SV Get the value at offset "po" in the current pad
741 SV * PAD_SV(PADOFFSET po)
743 PAD_SVl Lightweight and lvalue version of "PAD_SV". Get or set the
745 value at offset "po" in the current pad. Unlike "PAD_SV", does
746 not print diagnostics with -DX. For internal use only.
747 SV * PAD_SVl(PADOFFSET po)
749 SAVECLEARSV
751 Clear the pointed to pad value on scope exit. (i.e. the
752 runtime action of "my")
753 void SAVECLEARSV(SV **svp)
755 SAVECOMPPAD
757 save "PL_comppad" and "PL_curpad"
758 void SAVECOMPPAD()
760 SAVEPADSV
762 Save a pad slot (used to restore after an iteration)
763 XXX DAPM it would make more sense to make the arg a PADOFFSET
765 void SAVEPADSV(PADOFFSET po)
766
768 PL_DBsingle
769 When Perl is run in debugging mode, with the -d switch, this SV
770 is a boolean which indicates whether subs are being single-
771 stepped. Single-stepping is automatically turned on after
772 every step. This is the C variable which corresponds to Perl's
773 $DB::single variable. See "PL_DBsub".
774 SV * PL_DBsingle
776 PL_DBsub
778 When Perl is run in debugging mode, with the -d switch, this GV
779 contains the SV which holds the name of the sub being debugged.
780 This is the C variable which corresponds to Perl's $DB::sub
781 variable. See "PL_DBsingle".
782 GV * PL_DBsub
784 PL_DBtrace
786 Trace variable used when Perl is run in debugging mode, with
787 the -d switch. This is the C variable which corresponds to
788 Perl's $DB::trace variable. See "PL_DBsingle".
789 SV * PL_DBtrace
791 PL_dowarn
793 The C variable that roughly corresponds to Perl's $^W warning
794 variable. However, $^W is treated as a boolean, whereas
795 "PL_dowarn" is a collection of flag bits.
796 U8 PL_dowarn
798 PL_last_in_gv
800 The GV which was last used for a filehandle input operation.
801 ("<FH>")
802 GV* PL_last_in_gv
804 PL_ofsgv
806 The glob containing the output field separator - "*," in Perl
807 space.
808 GV* PL_ofsgv
810 PL_rs The input record separator - $/ in Perl space.
812 SV* PL_rs
814
816 djSP Declare Just "SP". This is actually identical to "dSP", and
817 declares a local copy of perl's stack pointer, available via
818 the "SP" macro. See ""SP" in perlapi". (Available for
819 backward source code compatibility with the old (Perl 5.005)
820 thread model.)
821 djSP;
823 LVRET True if this op will be the return value of an lvalue
825 subroutine
826
828 sv_2num NOTE: this function is experimental and may change or be
829 removed without notice.
830 Return an SV with the numeric value of the source SV, doing any
832 necessary reference or overload conversion. The caller is
833 expected to have handled get-magic already.
834 SV* sv_2num(SV *const sv)
836
838 An SV (or AV, HV, etc.) is allocated in two parts: the head (struct sv,
839 av, hv...) contains type and reference count information, and for many
840 types, a pointer to the body (struct xrv, xpv, xpviv...), which
841 contains fields specific to each type. Some types store all they need
842 in the head, so don't have a body.
843 In all but the most memory-paranoid configurations (ex: PURIFY), heads
845 and bodies are allocated out of arenas, which by default are
846 approximately 4K chunks of memory parcelled up into N heads or bodies.
847 Sv-bodies are allocated by their sv-type, guaranteeing size consistency
848 needed to allocate safely from arrays.
849 For SV-heads, the first slot in each arena is reserved, and holds a
851 link to the next arena, some flags, and a note of the number of slots.
852 Snaked through each arena chain is a linked list of free items; when
853 this becomes empty, an extra arena is allocated and divided up into N
854 items which are threaded into the free list.
855 SV-bodies are similar, but they use arena-sets by default, which
857 separate the link and info from the arena itself, and reclaim the 1st
858 slot in the arena. SV-bodies are further described later.
859 The following global variables are associated with arenas:
861 PL_sv_arenaroot pointer to list of SV arenas
863 PL_sv_root pointer to list of free SV structures
864 PL_body_arenas head of linked-list of body arenas
866 PL_body_roots[] array of pointers to list of free bodies of svtype
867 arrays are indexed by the svtype needed
868 A few special SV heads are not allocated from an arena, but are instead
870 directly created in the interpreter structure, eg PL_sv_undef. The
871 size of arenas can be changed from the default by setting
872 PERL_ARENA_SIZE appropriately at compile time.
873 The SV arena serves the secondary purpose of allowing still-live SVs to
875 be located and destroyed during final cleanup.
876 At the lowest level, the macros new_SV() and del_SV() grab and free an
878 SV head. (If debugging with -DD, del_SV() calls the function
879 S_del_sv() to return the SV to the free list with error checking.)
880 new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the
881 free list is empty. SVs in the free list have their SvTYPE field set
882 to all ones.
883 At the time of very final cleanup, sv_free_arenas() is called from
885 perl_destruct() to physically free all the arenas allocated since the
886 start of the interpreter.
887 The function visit() scans the SV arenas list, and calls a specified
889 function for each SV it finds which is still live - ie which has an
890 SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is used by
891 the following functions (specified as [function that calls visit()] /
892 [function called by visit() for each SV]):
893 sv_report_used() / do_report_used()
895 dump all remaining SVs (debugging aid)
896 sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
898 do_clean_named_io_objs(),do_curse()
899 Attempt to free all objects pointed to by RVs,
900 try to do the same for all objects indir-
901 ectly referenced by typeglobs too, and
902 then do a final sweep, cursing any
903 objects that remain. Called once from
904 perl_destruct(), prior to calling sv_clean_all()
905 below.
906 sv_clean_all() / do_clean_all()
908 SvREFCNT_dec(sv) each remaining SV, possibly
909 triggering an sv_free(). It also sets the
910 SVf_BREAK flag on the SV to indicate that the
911 refcnt has been artificially lowered, and thus
912 stopping sv_free() from giving spurious warnings
913 about SVs which unexpectedly have a refcnt
914 of zero. called repeatedly from perl_destruct()
915 until there are no SVs left.
916 sv_add_arena
918 Given a chunk of memory, link it to the head of the list of
919 arenas, and split it into a list of free SVs.
920 void sv_add_arena(char *const ptr, const U32 size,
922 const U32 flags)
923 sv_clean_all
925 Decrement the refcnt of each remaining SV, possibly triggering
926 a cleanup. This function may have to be called multiple times
927 to free SVs which are in complex self-referential hierarchies.
928 I32 sv_clean_all()
930 sv_clean_objs
932 Attempt to destroy all objects not yet freed.
933 void sv_clean_objs()
935 sv_free_arenas
937 Deallocate the memory used by all arenas. Note that all the
938 individual SV heads and bodies within the arenas must already
939 have been freed.
940 void sv_free_arenas()
942 SvTHINKFIRST
944 A quick flag check to see whether an "sv" should be passed to
945 "sv_force_normal" to be "downgraded" before "SvIVX" or "SvPVX"
946 can be modified directly.
947 For example, if your scalar is a reference and you want to
949 modify the "SvIVX" slot, you can't just do "SvROK_off", as that
950 will leak the referent.
951 This is used internally by various sv-modifying functions, such
953 as "sv_setsv", "sv_setiv" and "sv_pvn_force".
954 One case that this does not handle is a gv without SvFAKE set.
956 After
957 if (SvTHINKFIRST(gv)) sv_force_normal(gv);
959 it will still be a gv.
961 "SvTHINKFIRST" sometimes produces false positives. In those
963 cases "sv_force_normal" does nothing.
964 U32 SvTHINKFIRST(SV *sv)
966
968 find_uninit_var
969 NOTE: this function is experimental and may change or be
970 removed without notice.
971 Find the name of the undefined variable (if any) that caused
973 the operator to issue a "Use of uninitialized value" warning.
974 If match is true, only return a name if its value matches
975 "uninit_sv". So roughly speaking, if a unary operator (such as
976 "OP_COS") generates a warning, then following the direct child
977 of the op may yield an "OP_PADSV" or "OP_GV" that gives the
978 name of the undefined variable. On the other hand, with
979 "OP_ADD" there are two branches to follow, so we only print the
980 variable name if we get an exact match. "desc_p" points to a
981 string pointer holding the description of the op. This may be
982 updated if needed.
983 The name is returned as a mortal SV.
985 Assumes that "PL_op" is the OP that originally triggered the
987 error, and that "PL_comppad"/"PL_curpad" points to the
988 currently executing pad.
989 SV* find_uninit_var(const OP *const obase,
991 const SV *const uninit_sv,
992 bool match, const char **desc_p)
993 report_uninit
995 Print appropriate "Use of uninitialized variable" warning.
996 void report_uninit(const SV *uninit_sv)
998
1000 The following functions are currently undocumented. If you use one of
1001 them, you may wish to consider creating and submitting documentation
1002 for it.
1003 PerlIO_restore_errno
1005 PerlIO_save_errno
1006 Slab_Alloc
1007 Slab_Free
1008 Slab_to_ro
1009 Slab_to_rw
1010 _add_range_to_invlist
1011 _byte_dump_string
1012 _core_swash_init
1013 _get_regclass_nonbitmap_data
1014 _get_swash_invlist
1015 _invlistEQ
1016 _invlist_array_init
1017 _invlist_contains_cp
1018 _invlist_dump
1019 _invlist_intersection
1020 _invlist_intersection_maybe_complement_2nd
1021 _invlist_invert
1022 _invlist_len
1023 _invlist_populate_swatch
1024 _invlist_search
1025 _invlist_subtract
1026 _invlist_union
1027 _invlist_union_maybe_complement_2nd
1028 _is_grapheme
1029 _load_PL_utf8_foldclosures
1030 _mem_collxfrm
1031 _new_invlist
1032 _new_invlist_C_array
1033 _setup_canned_invlist
1034 _swash_inversion_hash
1035 _swash_to_invlist
1036 _to_fold_latin1
1037 _to_upper_title_latin1
1038 _warn_problematic_locale
1039 abort_execution
1040 add_cp_to_invlist
1041 alloc_LOGOP
1042 alloc_maybe_populate_EXACT
1043 allocmy
1044 amagic_is_enabled
1045 append_utf8_from_native_byte
1046 apply
1047 av_extend_guts
1048 av_reify
1049 bind_match
1050 boot_core_PerlIO
1051 boot_core_UNIVERSAL
1052 boot_core_mro
1053 cando
1054 check_utf8_print
1055 ck_anoncode
1056 ck_backtick
1057 ck_bitop
1058 ck_cmp
1059 ck_concat
1060 ck_defined
1061 ck_delete
1062 ck_each
1063 ck_entersub_args_core
1064 ck_eof
1065 ck_eval
1066 ck_exec
1067 ck_exists
1068 ck_ftst
1069 ck_fun
1070 ck_glob
1071 ck_grep
1072 ck_index
1073 ck_join
1074 ck_length
1075 ck_lfun
1076 ck_listiob
1077 ck_match
1078 ck_method
1079 ck_null
1080 ck_open
1081 ck_prototype
1082 ck_readline
1083 ck_refassign
1084 ck_repeat
1085 ck_require
1086 ck_return
1087 ck_rfun
1088 ck_rvconst
1089 ck_sassign
1090 ck_select
1091 ck_shift
1092 ck_smartmatch
1093 ck_sort
1094 ck_spair
1095 ck_split
1096 ck_stringify
1097 ck_subr
1098 ck_substr
1099 ck_svconst
1100 ck_tell
1101 ck_trunc
1102 closest_cop
1103 compute_EXACTish
1104 coresub_op
1105 create_eval_scope
1106 croak_caller
1107 croak_no_mem
1108 croak_popstack
1109 current_re_engine
1110 custom_op_get_field
1111 cv_ckproto_len_flags
1112 cv_clone_into
1113 cv_const_sv_or_av
1114 cv_undef_flags
1115 cvgv_from_hek
1116 cvgv_set
1117 cvstash_set
1118 deb_stack_all
1119 defelem_target
1120 delete_eval_scope
1121 delimcpy_no_escape
1122 die_unwind
1123 do_aexec
1124 do_aexec5
1125 do_eof
1126 do_exec
1127 do_exec3
1128 do_execfree
1129 do_ipcctl
1130 do_ipcget
1131 do_msgrcv
1132 do_msgsnd
1133 do_ncmp
1134 do_open6
1135 do_open_raw
1136 do_print
1137 do_readline
1138 do_seek
1139 do_semop
1140 do_shmio
1141 do_sysseek
1142 do_tell
1143 do_trans
1144 do_vecget
1145 do_vecset
1146 do_vop
1147 does_utf8_overflow
1148 dofile
1149 drand48_init_r
1150 drand48_r
1151 dtrace_probe_call
1152 dtrace_probe_load
1153 dtrace_probe_op
1154 dtrace_probe_phase
1155 dump_all_perl
1156 dump_packsubs_perl
1157 dump_sub_perl
1158 dump_sv_child
1159 emulate_cop_io
1160 feature_is_enabled
1161 find_lexical_cv
1162 find_runcv_where
1163 find_script
1164 form_short_octal_warning
1165 free_tied_hv_pool
1166 get_db_sub
1167 get_debug_opts
1168 get_hash_seed
1169 get_invlist_iter_addr
1170 get_invlist_offset_addr
1171 get_invlist_previous_index_addr
1172 get_no_modify
1173 get_opargs
1174 get_re_arg
1175 getenv_len
1176 grok_atoUV
1177 grok_bslash_c
1178 grok_bslash_o
1179 grok_bslash_x
1180 gv_fetchmeth_internal
1181 gv_override
1182 gv_setref
1183 gv_stashpvn_internal
1184 gv_stashsvpvn_cached
1185 handle_named_backref
1186 hfree_next_entry
1187 hv_backreferences_p
1188 hv_kill_backrefs
1189 hv_placeholders_p
1190 hv_undef_flags
1191 init_argv_symbols
1192 init_constants
1193 init_dbargs
1194 init_debugger
1195 invert
1196 invlist_array
1197 invlist_clear
1198 invlist_clone
1199 invlist_highest
1200 invlist_is_iterating
1201 invlist_iterfinish
1202 invlist_iterinit
1203 invlist_max
1204 invlist_previous_index
1205 invlist_set_len
1206 invlist_set_previous_index
1207 invlist_trim
1208 io_close
1209 isFF_OVERLONG
1210 isFOO_lc
1211 is_utf8_common
1212 is_utf8_common_with_len
1213 is_utf8_cp_above_31_bits
1214 is_utf8_overlong_given_start_byte_ok
1215 isinfnansv
1216 jmaybe
1217 keyword
1218 keyword_plugin_standard
1219 list
1220 localize
1221 magic_clear_all_env
1222 magic_cleararylen_p
1223 magic_clearenv
1224 magic_clearisa
1225 magic_clearpack
1226 magic_clearsig
1227 magic_copycallchecker
1228 magic_existspack
1229 magic_freearylen_p
1230 magic_freeovrld
1231 magic_get
1232 magic_getarylen
1233 magic_getdebugvar
1234 magic_getdefelem
1235 magic_getnkeys
1236 magic_getpack
1237 magic_getpos
1238 magic_getsig
1239 magic_getsubstr
1240 magic_gettaint
1241 magic_getuvar
1242 magic_getvec
1243 magic_killbackrefs
1244 magic_nextpack
1245 magic_regdata_cnt
1246 magic_regdatum_get
1247 magic_regdatum_set
1248 magic_scalarpack
1249 magic_set
1250 magic_set_all_env
1251 magic_setarylen
1252 magic_setcollxfrm
1253 magic_setdbline
1254 magic_setdebugvar
1255 magic_setdefelem
1256 magic_setenv
1257 magic_setisa
1258 magic_setlvref
1259 magic_setmglob
1260 magic_setnkeys
1261 magic_setpack
1262 magic_setpos
1263 magic_setregexp
1264 magic_setsig
1265 magic_setsubstr
1266 magic_settaint
1267 magic_setutf8
1268 magic_setuvar
1269 magic_setvec
1270 magic_sizepack
1271 magic_wipepack
1272 malloc_good_size
1273 malloced_size
1274 mem_collxfrm
1275 mem_log_alloc
1276 mem_log_free
1277 mem_log_realloc
1278 mg_find_mglob
1279 mode_from_discipline
1280 more_bodies
1281 mro_meta_dup
1282 mro_meta_init
1283 multideref_stringify
1284 my_attrs
1285 my_clearenv
1286 my_lstat_flags
1287 my_stat_flags
1288 my_unexec
1289 newATTRSUB_x
1290 newGP
1291 newMETHOP_internal
1292 newSTUB
1293 newSVavdefelem
1294 newXS_deffile
1295 newXS_len_flags
1296 new_warnings_bitfield
1297 nextargv
1298 noperl_die
1299 notify_parser_that_changed_to_utf8
1300 oopsAV
1301 oopsHV
1302 op_clear
1303 op_integerize
1304 op_lvalue_flags
1305 op_refcnt_dec
1306 op_refcnt_inc
1307 op_relocate_sv
1308 op_std_init
1309 op_unscope
1310 opmethod_stash
1311 opslab_force_free
1312 opslab_free
1313 opslab_free_nopad
1314 package
1315 package_version
1316 pad_add_weakref
1317 padlist_store
1318 padname_free
1319 padnamelist_free
1320 parse_unicode_opts
1321 parser_free
1322 parser_free_nexttoke_ops
1323 path_is_searchable
1324 peep
1325 pmruntime
1326 populate_isa
1327 ptr_hash
1328 qerror
1329 re_exec_indentf
1330 re_indentf
1331 re_op_compile
1332 re_printf
1333 reg_named_buff
1334 reg_named_buff_iter
1335 reg_numbered_buff_fetch
1336 reg_numbered_buff_length
1337 reg_numbered_buff_store
1338 reg_qr_package
1339 reg_skipcomment
1340 reg_temp_copy
1341 regcurly
1342 regprop
1343 report_evil_fh
1344 report_redefined_cv
1345 report_wrongway_fh
1346 rpeep
1347 rsignal_restore
1348 rsignal_save
1349 rxres_save
1350 same_dirent
1351 save_strlen
1352 sawparens
1353 scalar
1354 scalarvoid
1355 set_caret_X
1356 set_padlist
1357 should_warn_nl
1358 sighandler
1359 softref2xv
1360 ssc_add_range
1361 ssc_clear_locale
1362 ssc_cp_and
1363 ssc_intersection
1364 ssc_union
1365 sub_crush_depth
1366 sv_add_backref
1367 sv_buf_to_ro
1368 sv_del_backref
1369 sv_free2
1370 sv_kill_backrefs
1371 sv_len_utf8_nomg
1372 sv_magicext_mglob
1373 sv_mortalcopy_flags
1374 sv_only_taint_gmagic
1375 sv_or_pv_pos_u2b
1376 sv_resetpvn
1377 sv_sethek
1378 sv_setsv_cow
1379 sv_unglob
1380 swash_fetch
1381 swash_init
1382 tied_method
1383 tmps_grow_p
1384 translate_substr_offsets
1385 try_amagic_bin
1386 try_amagic_un
1387 unshare_hek
1388 utilize
1389 varname
1390 vivify_defelem
1391 vivify_ref
1392 wait4pid
1393 was_lvalue_sub
1394 watch
1395 win32_croak_not_implemented
1396 write_to_stderr
1397 xs_boot_epilog
1398 xs_handshake
1399 yyerror
1400 yyerror_pv
1401 yyerror_pvn
1402 yylex
1403 yyparse
1404 yyquit
1405 yyunlex
1406
1408 The autodocumentation system was originally added to the Perl core by
1409 Benjamin Stuhl. Documentation is by whoever was kind enough to
1410 document their functions.
1411
1413 perlguts, perlapi
1414perl v5.26.3 2019-05-11 PERLINTERN(1)