1PERLINTERN(1) Perl Programmers Reference Guide PERLINTERN(1)
2
6 perlintern - autogenerated documentation of purely internal Perl
7 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 AvFILLp
17 int AvFILLp(AV* av)
18
20 BhkENTRY
21 NOTE: this function is experimental and may change or be
22 removed without notice.
23 Return an entry from the BHK structure. "which" is a
25 preprocessor token indicating which entry to return. If the
26 appropriate flag is not set this will return "NULL". The type
27 of the return value depends on which entry you ask for.
28 void * BhkENTRY(BHK *hk, which)
30 BhkFLAGS
32 NOTE: this function is experimental and may change or be
33 removed without notice.
34 Return the BHK's flags.
36 U32 BhkFLAGS(BHK *hk)
38 CALL_BLOCK_HOOKS
40 NOTE: this function is experimental and may change or be
41 removed without notice.
42 Call all the registered block hooks for type "which". "which"
44 is a preprocessing token; the type of "arg" depends on "which".
45 void CALL_BLOCK_HOOKS(which, arg)
47
49 core_prototype
50 This function assigns the prototype of the named core function
51 to "sv", or to a new mortal SV if "sv" is "NULL". It returns
52 the modified "sv", or "NULL" if the core function has no
53 prototype. "code" is a code as returned by "keyword()". It
54 must not be equal to 0.
55 SV * core_prototype(SV *sv, const char *name,
57 const int code,
58 int * const opnum)
59
61 docatch Check for the cases 0 or 3 of cur_env.je_ret, only used inside
62 an eval context.
63 0 is used as continue inside eval,
65 3 is used for a die caught by an inner eval - continue inner
67 loop
68 See cop.h: je_mustcatch, when set at any runlevel to TRUE,
70 means eval ops must establish a local jmpenv to handle
71 exception traps.
72 OP* docatch(Perl_ppaddr_t firstpp)
74
76 CvWEAKOUTSIDE
77 Each CV has a pointer, "CvOUTSIDE()", to its lexically
78 enclosing CV (if any). Because pointers to anonymous sub
79 prototypes are stored in "&" pad slots, it is a possible to get
80 a circular reference, with the parent pointing to the child and
81 vice-versa. To avoid the ensuing memory leak, we do not
82 increment the reference count of the CV pointed to by
83 "CvOUTSIDE" in the one specific instance that the parent has a
84 "&" pad slot pointing back to us. In this case, we set the
85 "CvWEAKOUTSIDE" flag in the child. This allows us to determine
86 under what circumstances we should decrement the refcount of
87 the parent when freeing the child.
88 There is a further complication with non-closure anonymous subs
90 (i.e. those that do not refer to any lexicals outside that
91 sub). In this case, the anonymous prototype is shared rather
92 than being cloned. This has the consequence that the parent
93 may be freed while there are still active children, e.g.,
94 BEGIN { $a = sub { eval '$x' } }
96 In this case, the BEGIN is freed immediately after execution
98 since there are no active references to it: the anon sub
99 prototype has "CvWEAKOUTSIDE" set since it's not a closure, and
100 $a points to the same CV, so it doesn't contribute to BEGIN's
101 refcount either. When $a is executed, the "eval '$x'" causes
102 the chain of "CvOUTSIDE"s to be followed, and the freed BEGIN
103 is accessed.
104 To avoid this, whenever a CV and its associated pad is freed,
106 any "&" entries in the pad are explicitly removed from the pad,
107 and if the refcount of the pointed-to anon sub is still
108 positive, then that child's "CvOUTSIDE" is set to point to its
109 grandparent. This will only occur in the single specific case
110 of a non-closure anon prototype having one or more active
111 references (such as $a above).
112 One other thing to consider is that a CV may be merely
114 undefined rather than freed, eg "undef &foo". In this case,
115 its refcount may not have reached zero, but we still delete its
116 pad and its "CvROOT" etc. Since various children may still
117 have their "CvOUTSIDE" pointing at this undefined CV, we keep
118 its own "CvOUTSIDE" for the time being, so that the chain of
119 lexical scopes is unbroken. For example, the following should
120 print 123:
121 my $x = 123;
123 sub tmp { sub { eval '$x' } }
124 my $a = tmp();
125 undef &tmp;
126 print $a->();
127 bool CvWEAKOUTSIDE(CV *cv)
129
131 cv_dump dump the contents of a CV
132 void cv_dump(const CV *cv, const char *title)
134 cv_forget_slab
136 When a CV has a reference count on its slab ("CvSLABBED"), it
137 is responsible for making sure it is freed. (Hence, no two CVs
138 should ever have a reference count on the same slab.) The CV
139 only needs to reference the slab during compilation. Once it
140 is compiled and "CvROOT" attached, it has finished its job, so
141 it can forget the slab.
142 void cv_forget_slab(CV *cv)
144 do_dump_pad
146 Dump the contents of a padlist
147 void do_dump_pad(I32 level, PerlIO *file,
149 PADLIST *padlist, int full)
150 pad_alloc_name
152 Allocates a place in the currently-compiling pad (via
153 "pad_alloc" in perlapi) and then stores a name for that entry.
154 "name" is adopted and becomes the name entry; it must already
155 contain the name string. "typestash" and "ourstash" and the
156 "padadd_STATE" flag get added to "name". None of the other
157 processing of "pad_add_name_pvn" in perlapi is done. Returns
158 the offset of the allocated pad slot.
159 PADOFFSET pad_alloc_name(PADNAME *name, U32 flags,
161 HV *typestash, HV *ourstash)
162 pad_block_start
164 Update the pad compilation state variables on entry to a new
165 block.
166 void pad_block_start(int full)
168 pad_check_dup
170 Check for duplicate declarations: report any of:
171 * a 'my' in the current scope with the same name;
173 * an 'our' (anywhere in the pad) with the same name and the
174 same stash as 'ourstash'
175 "is_our" indicates that the name to check is an "our"
177 declaration.
178 void pad_check_dup(PADNAME *name, U32 flags,
180 const HV *ourstash)
181 pad_findlex
183 Find a named lexical anywhere in a chain of nested pads. Add
184 fake entries in the inner pads if it's found in an outer one.
185 Returns the offset in the bottom pad of the lex or the fake
187 lex. "cv" is the CV in which to start the search, and seq is
188 the current "cop_seq" to match against. If "warn" is true,
189 print appropriate warnings. The "out_"* vars return values,
190 and so are pointers to where the returned values should be
191 stored. "out_capture", if non-null, requests that the
192 innermost instance of the lexical is captured; "out_name" is
193 set to the innermost matched pad name or fake pad name;
194 "out_flags" returns the flags normally associated with the
195 "PARENT_FAKELEX_FLAGS" field of a fake pad name.
196 Note that "pad_findlex()" is recursive; it recurses up the
198 chain of CVs, then comes back down, adding fake entries as it
199 goes. It has to be this way because fake names in anon
200 protoypes have to store in "xpadn_low" the index into the
201 parent pad.
202 PADOFFSET pad_findlex(const char *namepv,
204 STRLEN namelen, U32 flags,
205 const CV* cv, U32 seq, int warn,
206 SV** out_capture,
207 PADNAME** out_name,
208 int *out_flags)
209 pad_fixup_inner_anons
211 For any anon CVs in the pad, change "CvOUTSIDE" of that CV from
212 "old_cv" to "new_cv" if necessary. Needed when a newly-
213 compiled CV has to be moved to a pre-existing CV struct.
214 void pad_fixup_inner_anons(PADLIST *padlist,
216 CV *old_cv, CV *new_cv)
217 pad_free
219 Free the SV at offset po in the current pad.
220 void pad_free(PADOFFSET po)
222 pad_leavemy
224 Cleanup at end of scope during compilation: set the max seq
225 number for lexicals in this scope and warn of any lexicals that
226 never got introduced.
227 OP * pad_leavemy()
229 padlist_dup
231 Duplicates a pad.
232 PADLIST * padlist_dup(PADLIST *srcpad,
234 CLONE_PARAMS *param)
235 padname_dup
237 Duplicates a pad name.
238 PADNAME * padname_dup(PADNAME *src, CLONE_PARAMS *param)
240 padnamelist_dup
242 Duplicates a pad name list.
243 PADNAMELIST * padnamelist_dup(PADNAMELIST *srcpad,
245 CLONE_PARAMS *param)
246 pad_push
248 Push a new pad frame onto the padlist, unless there's already a
249 pad at this depth, in which case don't bother creating a new
250 one. Then give the new pad an @_ in slot zero.
251 void pad_push(PADLIST *padlist, int depth)
253 pad_reset
255 Mark all the current temporaries for reuse
256 void pad_reset()
258 pad_swipe
260 Abandon the tmp in the current pad at offset "po" and replace
261 with a new one.
262 void pad_swipe(PADOFFSET po, bool refadjust)
264
266 dSAVEDERRNO
267 Declare variables needed to save "errno" and any operating
268 system specific error number.
269 void dSAVEDERRNO
271 dSAVE_ERRNO
273 Declare variables needed to save "errno" and any operating
274 system specific error number, and save them for optional later
275 restoration by "RESTORE_ERRNO".
276 void dSAVE_ERRNO
278 RESTORE_ERRNO
280 Restore "errno" and any operating system specific error number
281 that was saved by "dSAVE_ERRNO" or "RESTORE_ERRNO".
282 void RESTORE_ERRNO
284 SAVE_ERRNO
286 Save "errno" and any operating system specific error number for
287 optional later restoration by "RESTORE_ERRNO". Requires
288 "dSAVEDERRNO" or "dSAVE_ERRNO" in scope.
289 void SAVE_ERRNO
291 SETERRNO
293 Set "errno", and on VMS set "vaxc$errno".
294 void SETERRNO(int errcode, int vmserrcode)
296
298 gv_try_downgrade
299 NOTE: this function is experimental and may change or be
300 removed without notice.
301 If the typeglob "gv" can be expressed more succinctly, by
303 having something other than a real GV in its place in the
304 stash, replace it with the optimised form. Basic requirements
305 for this are that "gv" is a real typeglob, is sufficiently
306 ordinary, and is only referenced from its package. This
307 function is meant to be used when a GV has been looked up in
308 part to see what was there, causing upgrading, but based on
309 what was found it turns out that the real GV isn't required
310 after all.
311 If "gv" is a completely empty typeglob, it is deleted from the
313 stash.
314 If "gv" is a typeglob containing only a sufficiently-ordinary
316 constant sub, the typeglob is replaced with a scalar-reference
317 placeholder that more compactly represents the same thing.
318 void gv_try_downgrade(GV* gv)
320
322 hv_ename_add
323 Adds a name to a stash's internal list of effective names. See
324 "hv_ename_delete".
325 This is called when a stash is assigned to a new location in
327 the symbol table.
328 void hv_ename_add(HV *hv, const char *name, U32 len,
330 U32 flags)
331 hv_ename_delete
333 Removes a name from a stash's internal list of effective names.
334 If this is the name returned by "HvENAME", then another name in
335 the list will take its place ("HvENAME" will use it).
336 This is called when a stash is deleted from the symbol table.
338 void hv_ename_delete(HV *hv, const char *name,
340 U32 len, U32 flags)
341 refcounted_he_chain_2hv
343 Generates and returns a "HV *" representing the content of a
344 "refcounted_he" chain. "flags" is currently unused and must be
345 zero.
346 HV * refcounted_he_chain_2hv(
348 const struct refcounted_he *c, U32 flags
349 )
350 refcounted_he_fetch_pv
352 Like "refcounted_he_fetch_pvn", but takes a nul-terminated
353 string instead of a string/length pair.
354 SV * refcounted_he_fetch_pv(
356 const struct refcounted_he *chain,
357 const char *key, U32 hash, U32 flags
358 )
359 refcounted_he_fetch_pvn
361 Search along a "refcounted_he" chain for an entry with the key
362 specified by "keypv" and "keylen". If "flags" has the
363 "REFCOUNTED_HE_KEY_UTF8" bit set, the key octets are
364 interpreted as UTF-8, otherwise they are interpreted as
365 Latin-1. "hash" is a precomputed hash of the key string, or
366 zero if it has not been precomputed. Returns a mortal scalar
367 representing the value associated with the key, or
368 &PL_sv_placeholder if there is no value associated with the
369 key.
370 SV * refcounted_he_fetch_pvn(
372 const struct refcounted_he *chain,
373 const char *keypv, STRLEN keylen, U32 hash,
374 U32 flags
375 )
376 refcounted_he_fetch_pvs
378 Like "refcounted_he_fetch_pvn", but takes a literal string
379 instead of a string/length pair, and no precomputed hash.
380 SV * refcounted_he_fetch_pvs(
382 const struct refcounted_he *chain, "key",
383 U32 flags
384 )
385 refcounted_he_fetch_sv
387 Like "refcounted_he_fetch_pvn", but takes a Perl scalar instead
388 of a string/length pair.
389 SV * refcounted_he_fetch_sv(
391 const struct refcounted_he *chain, SV *key,
392 U32 hash, U32 flags
393 )
394 refcounted_he_free
396 Decrements the reference count of a "refcounted_he" by one. If
397 the reference count reaches zero the structure's memory is
398 freed, which (recursively) causes a reduction of its parent
399 "refcounted_he"'s reference count. It is safe to pass a null
400 pointer to this function: no action occurs in this case.
401 void refcounted_he_free(struct refcounted_he *he)
403 refcounted_he_inc
405 Increment the reference count of a "refcounted_he". The
406 pointer to the "refcounted_he" is also returned. It is safe to
407 pass a null pointer to this function: no action occurs and a
408 null pointer is returned.
409 struct refcounted_he * refcounted_he_inc(
411 struct refcounted_he *he
412 )
413 refcounted_he_new_pv
415 Like "refcounted_he_new_pvn", but takes a nul-terminated string
416 instead of a string/length pair.
417 struct refcounted_he * refcounted_he_new_pv(
419 struct refcounted_he *parent,
420 const char *key, U32 hash,
421 SV *value, U32 flags
422 )
423 refcounted_he_new_pvn
425 Creates a new "refcounted_he". This consists of a single
426 key/value pair and a reference to an existing "refcounted_he"
427 chain (which may be empty), and thus forms a longer chain.
428 When using the longer chain, the new key/value pair takes
429 precedence over any entry for the same key further along the
430 chain.
431 The new key is specified by "keypv" and "keylen". If "flags"
433 has the "REFCOUNTED_HE_KEY_UTF8" bit set, the key octets are
434 interpreted as UTF-8, otherwise they are interpreted as
435 Latin-1. "hash" is a precomputed hash of the key string, or
436 zero if it has not been precomputed.
437 "value" is the scalar value to store for this key. "value" is
439 copied by this function, which thus does not take ownership of
440 any reference to it, and later changes to the scalar will not
441 be reflected in the value visible in the "refcounted_he".
442 Complex types of scalar will not be stored with referential
443 integrity, but will be coerced to strings. "value" may be
444 either null or &PL_sv_placeholder to indicate that no value is
445 to be associated with the key; this, as with any non-null
446 value, takes precedence over the existence of a value for the
447 key further along the chain.
448 "parent" points to the rest of the "refcounted_he" chain to be
450 attached to the new "refcounted_he". This function takes
451 ownership of one reference to "parent", and returns one
452 reference to the new "refcounted_he".
453 struct refcounted_he * refcounted_he_new_pvn(
455 struct refcounted_he *parent,
456 const char *keypv,
457 STRLEN keylen, U32 hash,
458 SV *value, U32 flags
459 )
460 refcounted_he_new_pvs
462 Like "refcounted_he_new_pvn", but takes a literal string
463 instead of a string/length pair, and no precomputed hash.
464 struct refcounted_he * refcounted_he_new_pvs(
466 struct refcounted_he *parent,
467 "key", SV *value, U32 flags
468 )
469 refcounted_he_new_sv
471 Like "refcounted_he_new_pvn", but takes a Perl scalar instead
472 of a string/length pair.
473 struct refcounted_he * refcounted_he_new_sv(
475 struct refcounted_he *parent,
476 SV *key, U32 hash, SV *value,
477 U32 flags
478 )
479
481 start_glob
482 NOTE: this function is experimental and may change or be
483 removed without notice.
484 Function called by "do_readline" to spawn a glob (or do the
486 glob inside perl on VMS). This code used to be inline, but now
487 perl uses "File::Glob" this glob starter is only used by
488 miniperl during the build process, or when PERL_EXTERNAL_GLOB
489 is defined. Moving it away shrinks pp_hot.c; shrinking
490 pp_hot.c helps speed perl up.
491 NOTE: this function must be explicitly called as
493 Perl_start_glob with an aTHX_ parameter.
494 PerlIO* Perl_start_glob(pTHX_ SV *tmpglob, IO *io)
496
498 validate_proto
499 NOTE: this function is experimental and may change or be
500 removed without notice.
501 This function performs syntax checking on a prototype, "proto".
503 If "warn" is true, any illegal characters or mismatched
504 brackets will trigger illegalproto warnings, declaring that
505 they were detected in the prototype for "name".
506 The return value is "true" if this is a valid prototype, and
508 "false" if it is not, regardless of whether "warn" was "true"
509 or "false".
510 Note that "NULL" is a valid "proto" and will always return
512 "true".
513 bool validate_proto(SV *name, SV *proto, bool warn,
515 bool curstash)
516
518 magic_clearhint
519 Triggered by a delete from "%^H", records the key to
520 "PL_compiling.cop_hints_hash".
521 int magic_clearhint(SV* sv, MAGIC* mg)
523 magic_clearhints
525 Triggered by clearing "%^H", resets
526 "PL_compiling.cop_hints_hash".
527 int magic_clearhints(SV* sv, MAGIC* mg)
529 magic_methcall
531 Invoke a magic method (like FETCH).
532 "sv" and "mg" are the tied thingy and the tie magic.
534 "meth" is the name of the method to call.
536 "argc" is the number of args (in addition to $self) to pass to
538 the method.
539 The "flags" can be:
541 G_DISCARD invoke method with G_DISCARD flag and don't
543 return a value
544 G_UNDEF_FILL fill the stack with argc pointers to
545 PL_sv_undef
546 The arguments themselves are any values following the "flags"
548 argument.
549 Returns the SV (if any) returned by the method, or "NULL" on
551 failure.
552 NOTE: this function must be explicitly called as
554 Perl_magic_methcall with an aTHX_ parameter.
555 SV* Perl_magic_methcall(pTHX_ SV *sv,
557 const MAGIC *mg, SV *meth,
558 U32 flags, U32 argc, ...)
559 magic_sethint
561 Triggered by a store to "%^H", records the key/value pair to
562 "PL_compiling.cop_hints_hash". It is assumed that hints aren't
563 storing anything that would need a deep copy. Maybe we should
564 warn if we find a reference.
565 int magic_sethint(SV* sv, MAGIC* mg)
567 mg_localize
569 Copy some of the magic from an existing SV to new localized
570 version of that SV. Container magic (e.g., %ENV, $1, "tie")
571 gets copied, value magic doesn't (e.g., "taint", "pos").
572 If "setmagic" is false then no set magic will be called on the
574 new (empty) SV. This typically means that assignment will soon
575 follow (e.g. 'local $x = $y'), and that will handle the magic.
576 void mg_localize(SV* sv, SV* nsv, bool setmagic)
578
580 free_c_backtrace
581 Deallocates a backtrace received from get_c_bracktrace.
582 void free_c_backtrace(Perl_c_backtrace* bt)
584 get_c_backtrace
586 Collects the backtrace (aka "stacktrace") into a single linear
587 malloced buffer, which the caller must
588 "Perl_free_c_backtrace()".
589 Scans the frames back by "depth + skip", then drops the "skip"
591 innermost, returning at most "depth" frames.
592 Perl_c_backtrace* get_c_backtrace(int max_depth,
594 int skip)
595 quadmath_format_needed
597 "quadmath_format_needed()" returns true if the "format" string
598 seems to contain at least one non-Q-prefixed "%[efgaEFGA]"
599 format specifier, or returns false otherwise.
600 The format specifier detection is not complete printf-syntax
602 detection, but it should catch most common cases.
603 If true is returned, those arguments should in theory be
605 processed with "quadmath_snprintf()", but in case there is more
606 than one such format specifier (see "quadmath_format_valid"),
607 and if there is anything else beyond that one (even just a
608 single byte), they cannot be processed because
609 "quadmath_snprintf()" is very strict, accepting only one format
610 spec, and nothing else. In this case, the code should probably
611 fail.
612 bool quadmath_format_needed(const char* format)
614 quadmath_format_valid
616 "quadmath_snprintf()" is very strict about its "format" string
617 and will fail, returning -1, if the format is invalid. It
618 accepts exactly one format spec.
619 "quadmath_format_valid()" checks that the intended single spec
621 looks sane: begins with "%", has only one "%", ends with
622 "[efgaEFGA]", and has "Q" before it. This is not a full
623 "printf syntax check", just the basics.
624 Returns true if it is valid, false if not.
626 See also "quadmath_format_needed".
628 bool quadmath_format_valid(const char* format)
630
632 mro_get_linear_isa_dfs
633 Returns the Depth-First Search linearization of @ISA the given
634 stash. The return value is a read-only AV*. "level" should be
635 0 (it is used internally in this function's recursion).
636 You are responsible for "SvREFCNT_inc()" on the return value if
638 you plan to store it anywhere semi-permanently (otherwise it
639 might be deleted out from under you the next time the cache is
640 invalidated).
641 AV* mro_get_linear_isa_dfs(HV* stash, U32 level)
643 mro_isa_changed_in
645 Takes the necessary steps (cache invalidations, mostly) when
646 the @ISA of the given package has changed. Invoked by the
647 "setisa" magic, should not need to invoke directly.
648 void mro_isa_changed_in(HV* stash)
650 mro_package_moved
652 Call this function to signal to a stash that it has been
653 assigned to another spot in the stash hierarchy. "stash" is
654 the stash that has been assigned. "oldstash" is the stash it
655 replaces, if any. "gv" is the glob that is actually being
656 assigned to.
657 This can also be called with a null first argument to indicate
659 that "oldstash" has been deleted.
660 This function invalidates isa caches on the old stash, on all
662 subpackages nested inside it, and on the subclasses of all
663 those, including non-existent packages that have corresponding
664 entries in "stash".
665 It also sets the effective names ("HvENAME") on all the stashes
667 as appropriate.
668 If the "gv" is present and is not in the symbol table, then
670 this function simply returns. This checked will be skipped if
671 "flags & 1".
672 void mro_package_moved(HV * const stash,
674 HV * const oldstash,
675 const GV * const gv,
676 U32 flags)
677
679 grok_atoUV
680 parse a string, looking for a decimal unsigned integer.
681 On entry, "pv" points to the beginning of the string; "valptr"
683 points to a UV that will receive the converted value, if found;
684 "endptr" is either NULL or points to a variable that points to
685 one byte beyond the point in "pv" that this routine should
686 examine. If "endptr" is NULL, "pv" is assumed to be NUL-
687 terminated.
688 Returns FALSE if "pv" doesn't represent a valid unsigned
690 integer value (with no leading zeros). Otherwise it returns
691 TRUE, and sets *valptr to that value.
692 If you constrain the portion of "pv" that is looked at by this
694 function (by passing a non-NULL "endptr"), and if the intial
695 bytes of that portion form a valid value, it will return TRUE,
696 setting *endptr to the byte following the final digit of the
697 value. But if there is no constraint at what's looked at, all
698 of "pv" must be valid in order for TRUE to be returned.
699 *endptr is unchanged from its value on input if FALSE is
700 returned;
701 The only characters this accepts are the decimal digits
703 '0'..'9'.
704 As opposed to atoi(3) or strtol(3), "grok_atoUV" does NOT allow
706 optional leading whitespace, nor negative inputs. If such
707 features are required, the calling code needs to explicitly
708 implement those.
709 Note that this function returns FALSE for inputs that would
711 overflow a UV, or have leading zeros. Thus a single 0 is
712 accepted, but not 00 nor 01, 002, etc.
713 Background: "atoi" has severe problems with illegal inputs, it
715 cannot be used for incremental parsing, and therefore should be
716 avoided "atoi" and "strtol" are also affected by locale
717 settings, which can also be seen as a bug (global state
718 controlled by user environment).
719 bool grok_atoUV(const char* pv, UV* valptr,
721 const char** endptr)
722 isinfnansv
724 Checks whether the argument would be either an infinity or
725 "NaN" when used as a number, but is careful not to trigger non-
726 numeric or uninitialized warnings. it assumes the caller has
727 done "SvGETMAGIC(sv)" already.
728 bool isinfnansv(SV *sv)
730
732 utf8n_to_uvuni
733 DEPRECATED! It is planned to remove this function from a
734 future release of Perl. Do not use it for new code; remove it
735 from existing code.
736 Instead use "utf8_to_uvchr_buf" in perlapi, or rarely,
738 "utf8n_to_uvchr" in perlapi.
739 This function was useful for code that wanted to handle both
741 EBCDIC and ASCII platforms with Unicode properties, but
742 starting in Perl v5.20, the distinctions between the platforms
743 have mostly been made invisible to most code, so this function
744 is quite unlikely to be what you want. If you do need this
745 precise functionality, use instead
746 "NATIVE_TO_UNI(utf8_to_uvchr_buf(...))" or
747 "NATIVE_TO_UNI(utf8n_to_uvchr(...))".
748 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen,
750 STRLEN *retlen, U32 flags)
751 utf8_to_uvuni
753 DEPRECATED! It is planned to remove this function from a
754 future release of Perl. Do not use it for new code; remove it
755 from existing code.
756 Returns the Unicode code point of the first character in the
758 string "s" which is assumed to be in UTF-8 encoding; "retlen"
759 will be set to the length, in bytes, of that character.
760 Some, but not all, UTF-8 malformations are detected, and in
762 fact, some malformed input could cause reading beyond the end
763 of the input buffer, which is one reason why this function is
764 deprecated. The other is that only in extremely limited
765 circumstances should the Unicode versus native code point be of
766 any interest to you. See "utf8_to_uvuni_buf" for alternatives.
767 If "s" points to one of the detected malformations, and UTF8
769 warnings are enabled, zero is returned and *retlen is set (if
770 "retlen" doesn't point to NULL) to -1. If those warnings are
771 off, the computed value if well-defined (or the Unicode
772 REPLACEMENT CHARACTER, if not) is silently returned, and
773 *retlen is set (if "retlen" isn't NULL) so that ("s" + *retlen)
774 is the next possible position in "s" that could begin a non-
775 malformed character. See "utf8n_to_uvchr" in perlapi for
776 details on when the REPLACEMENT CHARACTER is returned.
777 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
779 uvuni_to_utf8_flags
781 DEPRECATED! It is planned to remove this function from a
782 future release of Perl. Do not use it for new code; remove it
783 from existing code.
784 Instead you almost certainly want to use "uvchr_to_utf8" in
786 perlapi or "uvchr_to_utf8_flags" in perlapi.
787 This function is a deprecated synonym for
789 "uvoffuni_to_utf8_flags", which itself, while not deprecated,
790 should be used only in isolated circumstances. These functions
791 were useful for code that wanted to handle both EBCDIC and
792 ASCII platforms with Unicode properties, but starting in Perl
793 v5.20, the distinctions between the platforms have mostly been
794 made invisible to most code, so this function is quite unlikely
795 to be what you want.
796 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
798
800 finalize_optree
801 This function finalizes the optree. Should be called directly
802 after the complete optree is built. It does some additional
803 checking which can't be done in the normal "ck_"xxx functions
804 and makes the tree thread-safe.
805 void finalize_optree(OP* o)
807 newATTRSUB_x
809 Construct a Perl subroutine, also performing some surrounding
810 jobs.
811 This function is expected to be called in a Perl compilation
813 context, and some aspects of the subroutine are taken from
814 global variables associated with compilation. In particular,
815 "PL_compcv" represents the subroutine that is currently being
816 compiled. It must be non-null when this function is called,
817 and some aspects of the subroutine being constructed are taken
818 from it. The constructed subroutine may actually be a reuse of
819 the "PL_compcv" object, but will not necessarily be so.
820 If "block" is null then the subroutine will have no body, and
822 for the time being it will be an error to call it. This
823 represents a forward subroutine declaration such as
824 "sub foo ($$);". If "block" is non-null then it provides the
825 Perl code of the subroutine body, which will be executed when
826 the subroutine is called. This body includes any argument
827 unwrapping code resulting from a subroutine signature or
828 similar. The pad use of the code must correspond to the pad
829 attached to "PL_compcv". The code is not expected to include a
830 "leavesub" or "leavesublv" op; this function will add such an
831 op. "block" is consumed by this function and will become part
832 of the constructed subroutine.
833 "proto" specifies the subroutine's prototype, unless one is
835 supplied as an attribute (see below). If "proto" is null, then
836 the subroutine will not have a prototype. If "proto" is non-
837 null, it must point to a "const" op whose value is a string,
838 and the subroutine will have that string as its prototype. If
839 a prototype is supplied as an attribute, the attribute takes
840 precedence over "proto", but in that case "proto" should
841 preferably be null. In any case, "proto" is consumed by this
842 function.
843 "attrs" supplies attributes to be applied the subroutine. A
845 handful of attributes take effect by built-in means, being
846 applied to "PL_compcv" immediately when seen. Other attributes
847 are collected up and attached to the subroutine by this route.
848 "attrs" may be null to supply no attributes, or point to a
849 "const" op for a single attribute, or point to a "list" op
850 whose children apart from the "pushmark" are "const" ops for
851 one or more attributes. Each "const" op must be a string,
852 giving the attribute name optionally followed by parenthesised
853 arguments, in the manner in which attributes appear in Perl
854 source. The attributes will be applied to the sub by this
855 function. "attrs" is consumed by this function.
856 If "o_is_gv" is false and "o" is null, then the subroutine will
858 be anonymous. If "o_is_gv" is false and "o" is non-null, then
859 "o" must point to a "const" op, which will be consumed by this
860 function, and its string value supplies a name for the
861 subroutine. The name may be qualified or unqualified, and if
862 it is unqualified then a default stash will be selected in some
863 manner. If "o_is_gv" is true, then "o" doesn't point to an
864 "OP" at all, but is instead a cast pointer to a "GV" by which
865 the subroutine will be named.
866 If there is already a subroutine of the specified name, then
868 the new sub will either replace the existing one in the glob or
869 be merged with the existing one. A warning may be generated
870 about redefinition.
871 If the subroutine has one of a few special names, such as
873 "BEGIN" or "END", then it will be claimed by the appropriate
874 queue for automatic running of phase-related subroutines. In
875 this case the relevant glob will be left not containing any
876 subroutine, even if it did contain one before. In the case of
877 "BEGIN", the subroutine will be executed and the reference to
878 it disposed of before this function returns.
879 The function returns a pointer to the constructed subroutine.
881 If the sub is anonymous then ownership of one counted reference
882 to the subroutine is transferred to the caller. If the sub is
883 named then the caller does not get ownership of a reference.
884 In most such cases, where the sub has a non-phase name, the sub
885 will be alive at the point it is returned by virtue of being
886 contained in the glob that names it. A phase-named subroutine
887 will usually be alive by virtue of the reference owned by the
888 phase's automatic run queue. But a "BEGIN" subroutine, having
889 already been executed, will quite likely have been destroyed
890 already by the time this function returns, making it erroneous
891 for the caller to make any use of the returned pointer. It is
892 the caller's responsibility to ensure that it knows which of
893 these situations applies.
894 CV* newATTRSUB_x(I32 floor, OP *o, OP *proto,
896 OP *attrs, OP *block, bool o_is_gv)
897 newXS_len_flags
899 Construct an XS subroutine, also performing some surrounding
900 jobs.
901 The subroutine will have the entry point "subaddr". It will
903 have the prototype specified by the nul-terminated string
904 "proto", or no prototype if "proto" is null. The prototype
905 string is copied; the caller can mutate the supplied string
906 afterwards. If "filename" is non-null, it must be a nul-
907 terminated filename, and the subroutine will have its "CvFILE"
908 set accordingly. By default "CvFILE" is set to point directly
909 to the supplied string, which must be static. If "flags" has
910 the "XS_DYNAMIC_FILENAME" bit set, then a copy of the string
911 will be taken instead.
912 Other aspects of the subroutine will be left in their default
914 state. If anything else needs to be done to the subroutine for
915 it to function correctly, it is the caller's responsibility to
916 do that after this function has constructed it. However,
917 beware of the subroutine potentially being destroyed before
918 this function returns, as described below.
919 If "name" is null then the subroutine will be anonymous, with
921 its "CvGV" referring to an "__ANON__" glob. If "name" is non-
922 null then the subroutine will be named accordingly, referenced
923 by the appropriate glob. "name" is a string of length "len"
924 bytes giving a sigilless symbol name, in UTF-8 if "flags" has
925 the "SVf_UTF8" bit set and in Latin-1 otherwise. The name may
926 be either qualified or unqualified, with the stash defaulting
927 in the same manner as for "gv_fetchpvn_flags". "flags" may
928 contain flag bits understood by "gv_fetchpvn_flags" with the
929 same meaning as they have there, such as "GV_ADDWARN". The
930 symbol is always added to the stash if necessary, with
931 "GV_ADDMULTI" semantics.
932 If there is already a subroutine of the specified name, then
934 the new sub will replace the existing one in the glob. A
935 warning may be generated about the redefinition. If the old
936 subroutine was "CvCONST" then the decision about whether to
937 warn is influenced by an expectation about whether the new
938 subroutine will become a constant of similar value. That
939 expectation is determined by "const_svp". (Note that the call
940 to this function doesn't make the new subroutine "CvCONST" in
941 any case; that is left to the caller.) If "const_svp" is null
942 then it indicates that the new subroutine will not become a
943 constant. If "const_svp" is non-null then it indicates that
944 the new subroutine will become a constant, and it points to an
945 "SV*" that provides the constant value that the subroutine will
946 have.
947 If the subroutine has one of a few special names, such as
949 "BEGIN" or "END", then it will be claimed by the appropriate
950 queue for automatic running of phase-related subroutines. In
951 this case the relevant glob will be left not containing any
952 subroutine, even if it did contain one before. In the case of
953 "BEGIN", the subroutine will be executed and the reference to
954 it disposed of before this function returns, and also before
955 its prototype is set. If a "BEGIN" subroutine would not be
956 sufficiently constructed by this function to be ready for
957 execution then the caller must prevent this happening by giving
958 the subroutine a different name.
959 The function returns a pointer to the constructed subroutine.
961 If the sub is anonymous then ownership of one counted reference
962 to the subroutine is transferred to the caller. If the sub is
963 named then the caller does not get ownership of a reference.
964 In most such cases, where the sub has a non-phase name, the sub
965 will be alive at the point it is returned by virtue of being
966 contained in the glob that names it. A phase-named subroutine
967 will usually be alive by virtue of the reference owned by the
968 phase's automatic run queue. But a "BEGIN" subroutine, having
969 already been executed, will quite likely have been destroyed
970 already by the time this function returns, making it erroneous
971 for the caller to make any use of the returned pointer. It is
972 the caller's responsibility to ensure that it knows which of
973 these situations applies.
974 CV * newXS_len_flags(const char *name, STRLEN len,
976 XSUBADDR_t subaddr,
977 const char *const filename,
978 const char *const proto,
979 SV **const_svp, U32 flags)
980 optimize_optree
982 This function applies some optimisations to the optree in top-
983 down order. It is called before the peephole optimizer, which
984 processes ops in execution order. Note that finalize_optree()
985 also does a top-down scan, but is called *after* the peephole
986 optimizer.
987 void optimize_optree(OP* o)
989 traverse_op_tree
991 Return the next op in a depth-first traversal of the op tree,
992 returning NULL when the traversal is complete.
993 The initial call must supply the root of the tree as both top
995 and o.
996 For now it's static, but it may be exposed to the API in the
998 future.
999 OP* traverse_op_tree(OP* top, OP* o)
1001
1003 CX_CURPAD_SAVE
1004 Save the current pad in the given context block structure.
1005 void CX_CURPAD_SAVE(struct context)
1007 CX_CURPAD_SV
1009 Access the SV at offset "po" in the saved current pad in the
1010 given context block structure (can be used as an lvalue).
1011 SV * CX_CURPAD_SV(struct context, PADOFFSET po)
1013 PAD_BASE_SV
1015 Get the value from slot "po" in the base (DEPTH=1) pad of a
1016 padlist
1017 SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
1019 PAD_CLONE_VARS
1021 Clone the state variables associated with running and compiling
1022 pads.
1023 void PAD_CLONE_VARS(PerlInterpreter *proto_perl,
1025 CLONE_PARAMS* param)
1026 PAD_COMPNAME_FLAGS
1028 Return the flags for the current compiling pad name at offset
1029 "po". Assumes a valid slot entry.
1030 U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
1032 PAD_COMPNAME_GEN
1034 The generation number of the name at offset "po" in the current
1035 compiling pad (lvalue).
1036 STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
1038 PAD_COMPNAME_GEN_set
1040 Sets the generation number of the name at offset "po" in the
1041 current ling pad (lvalue) to "gen".
1042 STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
1043 PAD_COMPNAME_OURSTASH
1045 Return the stash associated with an "our" variable. Assumes
1046 the slot entry is a valid "our" lexical.
1047 HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
1049 PAD_COMPNAME_PV
1051 Return the name of the current compiling pad name at offset
1052 "po". Assumes a valid slot entry.
1053 char * PAD_COMPNAME_PV(PADOFFSET po)
1055 PAD_COMPNAME_TYPE
1057 Return the type (stash) of the current compiling pad name at
1058 offset "po". Must be a valid name. Returns null if not typed.
1059 HV * PAD_COMPNAME_TYPE(PADOFFSET po)
1061 PadnameIsOUR
1063 Whether this is an "our" variable.
1064 bool PadnameIsOUR(PADNAME * pn)
1066 PadnameIsSTATE
1068 Whether this is a "state" variable.
1069 bool PadnameIsSTATE(PADNAME * pn)
1071 PadnameOURSTASH
1073 The stash in which this "our" variable was declared.
1074 HV * PadnameOURSTASH()
1076 PadnameOUTER
1078 Whether this entry belongs to an outer pad. Entries for which
1079 this is true are often referred to as 'fake'.
1080 bool PadnameOUTER(PADNAME * pn)
1082 PadnameTYPE
1084 The stash associated with a typed lexical. This returns the
1085 %Foo:: hash for "my Foo $bar".
1086 HV * PadnameTYPE(PADNAME * pn)
1088 PAD_RESTORE_LOCAL
1090 Restore the old pad saved into the local variable "opad" by
1091 "PAD_SAVE_LOCAL()"
1092 void PAD_RESTORE_LOCAL(PAD *opad)
1094 PAD_SAVE_LOCAL
1096 Save the current pad to the local variable "opad", then make
1097 the current pad equal to "npad"
1098 void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
1100 PAD_SAVE_SETNULLPAD
1102 Save the current pad then set it to null.
1103 void PAD_SAVE_SETNULLPAD()
1105 PAD_SETSV
1107 Set the slot at offset "po" in the current pad to "sv"
1108 SV * PAD_SETSV(PADOFFSET po, SV* sv)
1110 PAD_SET_CUR
1112 Set the current pad to be pad "n" in the padlist, saving the
1113 previous current pad. NB currently this macro expands to a
1114 string too long for some compilers, so it's best to replace it
1115 with
1116 SAVECOMPPAD();
1118 PAD_SET_CUR_NOSAVE(padlist,n);
1119 void PAD_SET_CUR(PADLIST padlist, I32 n)
1122 PAD_SET_CUR_NOSAVE
1124 like PAD_SET_CUR, but without the save
1125 void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
1127 PAD_SV Get the value at offset "po" in the current pad
1129 SV * PAD_SV(PADOFFSET po)
1131 PAD_SVl Lightweight and lvalue version of "PAD_SV". Get or set the
1133 value at offset "po" in the current pad. Unlike "PAD_SV", does
1134 not print diagnostics with -DX. For internal use only.
1135 SV * PAD_SVl(PADOFFSET po)
1137 SAVECLEARSV
1139 Clear the pointed to pad value on scope exit. (i.e. the
1140 runtime action of "my")
1141 void SAVECLEARSV(SV **svp)
1143 SAVECOMPPAD
1145 save "PL_comppad" and "PL_curpad"
1146 void SAVECOMPPAD()
1148 SAVEPADSV
1150 Save a pad slot (used to restore after an iteration)
1151 XXX DAPM it would make more sense to make the arg a PADOFFSET
1153 void SAVEPADSV(PADOFFSET po)
1154
1156 PL_DBsingle
1157 When Perl is run in debugging mode, with the -d switch, this SV
1158 is a boolean which indicates whether subs are being single-
1159 stepped. Single-stepping is automatically turned on after
1160 every step. This is the C variable which corresponds to Perl's
1161 $DB::single variable. See "PL_DBsub".
1162 SV * PL_DBsingle
1164 PL_DBsub
1166 When Perl is run in debugging mode, with the -d switch, this GV
1167 contains the SV which holds the name of the sub being debugged.
1168 This is the C variable which corresponds to Perl's $DB::sub
1169 variable. See "PL_DBsingle".
1170 GV * PL_DBsub
1172 PL_DBtrace
1174 Trace variable used when Perl is run in debugging mode, with
1175 the -d switch. This is the C variable which corresponds to
1176 Perl's $DB::trace variable. See "PL_DBsingle".
1177 SV * PL_DBtrace
1179 PL_dowarn
1181 The C variable that roughly corresponds to Perl's $^W warning
1182 variable. However, $^W is treated as a boolean, whereas
1183 "PL_dowarn" is a collection of flag bits.
1184 U8 PL_dowarn
1186 PL_last_in_gv
1188 The GV which was last used for a filehandle input operation.
1189 ("<FH>")
1190 GV* PL_last_in_gv
1192 PL_ofsgv
1194 The glob containing the output field separator - "*," in Perl
1195 space.
1196 GV* PL_ofsgv
1198 PL_rs The input record separator - $/ in Perl space.
1200 SV* PL_rs
1202
1204 djSP Declare Just "SP". This is actually identical to "dSP", and
1205 declares a local copy of perl's stack pointer, available via
1206 the "SP" macro. See ""SP" in perlapi". (Available for
1207 backward source code compatibility with the old (Perl 5.005)
1208 thread model.)
1209 djSP();
1211 LVRET True if this op will be the return value of an lvalue
1213 subroutine
1214
1216 SVt_INVLIST
1217 Type flag for scalars. See "svtype" in perlapi.
1218
1220 An SV (or AV, HV, etc.) is allocated in two parts: the head (struct sv,
1221 av, hv...) contains type and reference count information, and for many
1222 types, a pointer to the body (struct xrv, xpv, xpviv...), which
1223 contains fields specific to each type. Some types store all they need
1224 in the head, so don't have a body.
1225 In all but the most memory-paranoid configurations (ex: PURIFY), heads
1227 and bodies are allocated out of arenas, which by default are
1228 approximately 4K chunks of memory parcelled up into N heads or bodies.
1229 Sv-bodies are allocated by their sv-type, guaranteeing size consistency
1230 needed to allocate safely from arrays.
1231 For SV-heads, the first slot in each arena is reserved, and holds a
1233 link to the next arena, some flags, and a note of the number of slots.
1234 Snaked through each arena chain is a linked list of free items; when
1235 this becomes empty, an extra arena is allocated and divided up into N
1236 items which are threaded into the free list.
1237 SV-bodies are similar, but they use arena-sets by default, which
1239 separate the link and info from the arena itself, and reclaim the 1st
1240 slot in the arena. SV-bodies are further described later.
1241 The following global variables are associated with arenas:
1243 PL_sv_arenaroot pointer to list of SV arenas
1245 PL_sv_root pointer to list of free SV structures
1246 PL_body_arenas head of linked-list of body arenas
1248 PL_body_roots[] array of pointers to list of free bodies of svtype
1249 arrays are indexed by the svtype needed
1250 A few special SV heads are not allocated from an arena, but are instead
1252 directly created in the interpreter structure, eg PL_sv_undef. The
1253 size of arenas can be changed from the default by setting
1254 PERL_ARENA_SIZE appropriately at compile time.
1255 The SV arena serves the secondary purpose of allowing still-live SVs to
1257 be located and destroyed during final cleanup.
1258 At the lowest level, the macros new_SV() and del_SV() grab and free an
1260 SV head. (If debugging with -DD, del_SV() calls the function
1261 S_del_sv() to return the SV to the free list with error checking.)
1262 new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the
1263 free list is empty. SVs in the free list have their SvTYPE field set
1264 to all ones.
1265 At the time of very final cleanup, sv_free_arenas() is called from
1267 perl_destruct() to physically free all the arenas allocated since the
1268 start of the interpreter.
1269 The function visit() scans the SV arenas list, and calls a specified
1271 function for each SV it finds which is still live - ie which has an
1272 SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is used by
1273 the following functions (specified as [function that calls visit()] /
1274 [function called by visit() for each SV]):
1275 sv_report_used() / do_report_used()
1277 dump all remaining SVs (debugging aid)
1278 sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
1280 do_clean_named_io_objs(),do_curse()
1281 Attempt to free all objects pointed to by RVs,
1282 try to do the same for all objects indir-
1283 ectly referenced by typeglobs too, and
1284 then do a final sweep, cursing any
1285 objects that remain. Called once from
1286 perl_destruct(), prior to calling sv_clean_all()
1287 below.
1288 sv_clean_all() / do_clean_all()
1290 SvREFCNT_dec(sv) each remaining SV, possibly
1291 triggering an sv_free(). It also sets the
1292 SVf_BREAK flag on the SV to indicate that the
1293 refcnt has been artificially lowered, and thus
1294 stopping sv_free() from giving spurious warnings
1295 about SVs which unexpectedly have a refcnt
1296 of zero. called repeatedly from perl_destruct()
1297 until there are no SVs left.
1298 sv_2num NOTE: this function is experimental and may change or be
1300 removed without notice.
1301 Return an SV with the numeric value of the source SV, doing any
1303 necessary reference or overload conversion. The caller is
1304 expected to have handled get-magic already.
1305 SV* sv_2num(SV *const sv)
1307 sv_add_arena
1309 Given a chunk of memory, link it to the head of the list of
1310 arenas, and split it into a list of free SVs.
1311 void sv_add_arena(char *const ptr, const U32 size,
1313 const U32 flags)
1314 sv_clean_all
1316 Decrement the refcnt of each remaining SV, possibly triggering
1317 a cleanup. This function may have to be called multiple times
1318 to free SVs which are in complex self-referential hierarchies.
1319 I32 sv_clean_all()
1321 sv_clean_objs
1323 Attempt to destroy all objects not yet freed.
1324 void sv_clean_objs()
1326 sv_free_arenas
1328 Deallocate the memory used by all arenas. Note that all the
1329 individual SV heads and bodies within the arenas must already
1330 have been freed.
1331 void sv_free_arenas()
1333 SvTHINKFIRST
1335 A quick flag check to see whether an "sv" should be passed to
1336 "sv_force_normal" to be "downgraded" before "SvIVX" or "SvPVX"
1337 can be modified directly.
1338 For example, if your scalar is a reference and you want to
1340 modify the "SvIVX" slot, you can't just do "SvROK_off", as that
1341 will leak the referent.
1342 This is used internally by various sv-modifying functions, such
1344 as "sv_setsv", "sv_setiv" and "sv_pvn_force".
1345 One case that this does not handle is a gv without SvFAKE set.
1347 After
1348 if (SvTHINKFIRST(gv)) sv_force_normal(gv);
1350 it will still be a gv.
1352 "SvTHINKFIRST" sometimes produces false positives. In those
1354 cases "sv_force_normal" does nothing.
1355 U32 SvTHINKFIRST(SV *sv)
1357
1359 These are various utility functions for manipulating UTF8-encoded
1360 strings. For the uninitiated, this is a method of representing
1361 arbitrary Unicode characters as a variable number of bytes, in such a
1362 way that characters in the ASCII range are unmodified, and a zero byte
1363 never appears within non-zero characters.
1364 find_uninit_var
1366 NOTE: this function is experimental and may change or be
1367 removed without notice.
1368 Find the name of the undefined variable (if any) that caused
1370 the operator to issue a "Use of uninitialized value" warning.
1371 If match is true, only return a name if its value matches
1372 "uninit_sv". So roughly speaking, if a unary operator (such as
1373 "OP_COS") generates a warning, then following the direct child
1374 of the op may yield an "OP_PADSV" or "OP_GV" that gives the
1375 name of the undefined variable. On the other hand, with
1376 "OP_ADD" there are two branches to follow, so we only print the
1377 variable name if we get an exact match. "desc_p" points to a
1378 string pointer holding the description of the op. This may be
1379 updated if needed.
1380 The name is returned as a mortal SV.
1382 Assumes that "PL_op" is the OP that originally triggered the
1384 error, and that "PL_comppad"/"PL_curpad" points to the
1385 currently executing pad.
1386 SV* find_uninit_var(const OP *const obase,
1388 const SV *const uninit_sv,
1389 bool match, const char **desc_p)
1390 isSCRIPT_RUN
1392 Returns a bool as to whether or not the sequence of bytes from
1393 "s" up to but not including "send" form a "script run".
1394 "utf8_target" is TRUE iff the sequence starting at "s" is to be
1395 treated as UTF-8. To be precise, except for two degenerate
1396 cases given below, this function returns TRUE iff all code
1397 points in it come from any combination of three "scripts" given
1398 by the Unicode "Script Extensions" property: Common, Inherited,
1399 and possibly one other. Additionally all decimal digits must
1400 come from the same consecutive sequence of 10.
1401 For example, if all the characters in the sequence are Greek,
1403 or Common, or Inherited, this function will return TRUE,
1404 provided any decimal digits in it are from the same block of
1405 digits in Common. (These are the ASCII digits "0".."9" and
1406 additionally a block for full width forms of these, and several
1407 others used in mathematical notation.) For scripts (unlike
1408 Greek) that have their own digits defined this will accept
1409 either digits from that set or from one of the Common digit
1410 sets, but not a combination of the two. Some scripts, such as
1411 Arabic, have more than one set of digits. All digits must come
1412 from the same set for this function to return TRUE.
1413 *ret_script, if "ret_script" is not NULL, will on return of
1415 TRUE contain the script found, using the "SCX_enum" typedef.
1416 Its value will be "SCX_INVALID" if the function returns FALSE.
1417 If the sequence is empty, TRUE is returned, but *ret_script (if
1419 asked for) will be "SCX_INVALID".
1420 If the sequence contains a single code point which is
1422 unassigned to a character in the version of Unicode being used,
1423 the function will return TRUE, and the script will be
1424 "SCX_Unknown". Any other combination of unassigned code points
1425 in the input sequence will result in the function treating the
1426 input as not being a script run.
1427 The returned script will be "SCX_Inherited" iff all the code
1429 points in it are from the Inherited script.
1430 Otherwise, the returned script will be "SCX_Common" iff all the
1432 code points in it are from the Inherited or Common scripts.
1433 bool isSCRIPT_RUN(const U8 *s, const U8 *send,
1435 const bool utf8_target)
1436 is_utf8_non_invariant_string
1438 Returns TRUE if "is_utf8_invariant_string" in perlapi returns
1439 FALSE for the first "len" bytes of the string "s", but they
1440 are, nonetheless, legal Perl-extended UTF-8; otherwise returns
1441 FALSE.
1442 A TRUE return means that at least one code point represented by
1444 the sequence either is a wide character not representable as a
1445 single byte, or the representation differs depending on whether
1446 the sequence is encoded in UTF-8 or not.
1447 See also ""is_utf8_invariant_string" in perlapi",
1449 ""is_utf8_string" in perlapi"
1450 bool is_utf8_non_invariant_string(const U8* const s,
1452 STRLEN len)
1453 report_uninit
1455 Print appropriate "Use of uninitialized variable" warning.
1456 void report_uninit(const SV *uninit_sv)
1458 utf8_to_uvuni_buf
1460 DEPRECATED! It is planned to remove this function from a
1461 future release of Perl. Do not use it for new code; remove it
1462 from existing code.
1463 Only in very rare circumstances should code need to be dealing
1465 in Unicode (as opposed to native) code points. In those few
1466 cases, use "NATIVE_TO_UNI(utf8_to_uvchr_buf(...))" instead. If
1467 you are not absolutely sure this is one of those cases, then
1468 assume it isn't and use plain "utf8_to_uvchr_buf" instead.
1469 Returns the Unicode (not-native) code point of the first
1471 character in the string "s" which is assumed to be in UTF-8
1472 encoding; "send" points to 1 beyond the end of "s". "retlen"
1473 will be set to the length, in bytes, of that character.
1474 If "s" does not point to a well-formed UTF-8 character and UTF8
1476 warnings are enabled, zero is returned and *retlen is set (if
1477 "retlen" isn't NULL) to -1. If those warnings are off, the
1478 computed value if well-defined (or the Unicode REPLACEMENT
1479 CHARACTER, if not) is silently returned, and *retlen is set (if
1480 "retlen" isn't NULL) so that ("s" + *retlen) is the next
1481 possible position in "s" that could begin a non-malformed
1482 character. See "utf8n_to_uvchr" in perlapi for details on when
1483 the REPLACEMENT CHARACTER is returned.
1484 UV utf8_to_uvuni_buf(const U8 *s, const U8 *send,
1486 STRLEN *retlen)
1487 uvoffuni_to_utf8_flags
1489 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
1490 CIRCUMSTANCES. Instead, Almost all code should use
1491 "uvchr_to_utf8" in perlapi or "uvchr_to_utf8_flags" in perlapi.
1492 This function is like them, but the input is a strict Unicode
1494 (as opposed to native) code point. Only in very rare
1495 circumstances should code not be using the native code point.
1496 For details, see the description for "uvchr_to_utf8_flags" in
1498 perlapi.
1499 U8* uvoffuni_to_utf8_flags(U8 *d, UV uv,
1501 const UV flags)
1502 valid_utf8_to_uvchr
1504 Like ""utf8_to_uvchr_buf" in perlapi", but should only be
1505 called when it is known that the next character in the input
1506 UTF-8 string "s" is well-formed (e.g., it passes ""isUTF8_CHAR"
1507 in perlapi". Surrogates, non-character code points, and non-
1508 Unicode code points are allowed.
1509 UV valid_utf8_to_uvchr(const U8 *s, STRLEN *retlen)
1511 variant_under_utf8_count
1513 This function looks at the sequence of bytes between "s" and
1514 "e", which are assumed to be encoded in ASCII/Latin1, and
1515 returns how many of them would change should the string be
1516 translated into UTF-8. Due to the nature of UTF-8, each of
1517 these would occupy two bytes instead of the single one in the
1518 input string. Thus, this function returns the precise number
1519 of bytes the string would expand by when translated to UTF-8.
1520 Unlike most of the other functions that have "utf8" in their
1522 name, the input to this function is NOT a UTF-8-encoded string.
1523 The function name is slightly odd to emphasize this.
1524 This function is internal to Perl because khw thinks that any
1526 XS code that would want this is probably operating too close to
1527 the internals. Presenting a valid use case could change that.
1528 See also ""is_utf8_invariant_string" in perlapi" and
1530 ""is_utf8_invariant_string_loc" in perlapi",
1531 Size_t variant_under_utf8_count(const U8* const s,
1533 const U8* const e)
1534
1536 The following functions are currently undocumented. If you use one of
1537 them, you may wish to consider creating and submitting documentation
1538 for it.
1539 ASCII_TO_NEED
1541 NATIVE_TO_NEED
1542 POPMARK
1543 PadnameIN_SCOPE
1544 PerlIO_restore_errno
1545 PerlIO_save_errno
1546 PerlLIO_dup2_cloexec
1547 PerlLIO_dup_cloexec
1548 PerlLIO_open3_cloexec
1549 PerlLIO_open_cloexec
1550 PerlProc_pipe_cloexec
1551 PerlSock_accept_cloexec
1552 PerlSock_socket_cloexec
1553 PerlSock_socketpair_cloexec
1554 ReANY
1555 Slab_Alloc
1556 Slab_Free
1557 Slab_to_ro
1558 Slab_to_rw
1559 TOPMARK
1560 _add_range_to_invlist
1561 _byte_dump_string
1562 _force_out_malformed_utf8_message
1563 _inverse_folds
1564 _invlistEQ
1565 _invlist_array_init
1566 _invlist_contains_cp
1567 _invlist_dump
1568 _invlist_intersection
1569 _invlist_intersection_maybe_complement_2nd
1570 _invlist_invert
1571 _invlist_len
1572 _invlist_search
1573 _invlist_subtract
1574 _invlist_union
1575 _invlist_union_maybe_complement_2nd
1576 _is_cur_LC_category_utf8
1577 _is_in_locale_category
1578 _is_uni_FOO
1579 _is_uni_perl_idcont
1580 _is_uni_perl_idstart
1581 _is_utf8_FOO
1582 _is_utf8_perl_idcont
1583 _is_utf8_perl_idstart
1584 _mem_collxfrm
1585 _new_invlist
1586 _new_invlist_C_array
1587 _setup_canned_invlist
1588 _to_fold_latin1
1589 _to_uni_fold_flags
1590 _to_upper_title_latin1
1591 _to_utf8_fold_flags
1592 _to_utf8_lower_flags
1593 _to_utf8_title_flags
1594 _to_utf8_upper_flags
1595 _utf8n_to_uvchr_msgs_helper
1596 _warn_problematic_locale
1597 abort_execution
1598 add_cp_to_invlist
1599 alloc_LOGOP
1600 allocmy
1601 amagic_cmp
1602 amagic_cmp_desc
1603 amagic_cmp_locale
1604 amagic_cmp_locale_desc
1605 amagic_i_ncmp
1606 amagic_i_ncmp_desc
1607 amagic_is_enabled
1608 amagic_ncmp
1609 amagic_ncmp_desc
1610 append_utf8_from_native_byte
1611 apply
1612 av_extend_guts
1613 av_nonelem
1614 av_reify
1615 bind_match
1616 boot_core_PerlIO
1617 boot_core_UNIVERSAL
1618 boot_core_mro
1619 cando
1620 check_utf8_print
1621 ck_anoncode
1622 ck_backtick
1623 ck_bitop
1624 ck_cmp
1625 ck_concat
1626 ck_defined
1627 ck_delete
1628 ck_each
1629 ck_entersub_args_core
1630 ck_eof
1631 ck_eval
1632 ck_exec
1633 ck_exists
1634 ck_ftst
1635 ck_fun
1636 ck_glob
1637 ck_grep
1638 ck_index
1639 ck_isa
1640 ck_join
1641 ck_length
1642 ck_lfun
1643 ck_listiob
1644 ck_match
1645 ck_method
1646 ck_null
1647 ck_open
1648 ck_prototype
1649 ck_readline
1650 ck_refassign
1651 ck_repeat
1652 ck_require
1653 ck_return
1654 ck_rfun
1655 ck_rvconst
1656 ck_sassign
1657 ck_select
1658 ck_shift
1659 ck_smartmatch
1660 ck_sort
1661 ck_spair
1662 ck_split
1663 ck_stringify
1664 ck_subr
1665 ck_substr
1666 ck_svconst
1667 ck_tell
1668 ck_trunc
1669 closest_cop
1670 cmp_desc
1671 cmp_locale_desc
1672 cmpchain_extend
1673 cmpchain_finish
1674 cmpchain_start
1675 cntrl_to_mnemonic
1676 coresub_op
1677 create_eval_scope
1678 croak_caller
1679 croak_memory_wrap
1680 croak_no_mem
1681 croak_popstack
1682 current_re_engine
1683 custom_op_get_field
1684 cv_ckproto_len_flags
1685 cv_clone_into
1686 cv_const_sv_or_av
1687 cv_undef_flags
1688 cvgv_from_hek
1689 cvgv_set
1690 cvstash_set
1691 deb_stack_all
1692 defelem_target
1693 delete_eval_scope
1694 delimcpy_no_escape
1695 die_unwind
1696 do_aexec
1697 do_aexec5
1698 do_eof
1699 do_exec
1700 do_exec3
1701 do_ipcctl
1702 do_ipcget
1703 do_msgrcv
1704 do_msgsnd
1705 do_ncmp
1706 do_open6
1707 do_open_raw
1708 do_print
1709 do_readline
1710 do_seek
1711 do_semop
1712 do_shmio
1713 do_sysseek
1714 do_tell
1715 do_trans
1716 do_uniprop_match
1717 do_vecget
1718 do_vecset
1719 do_vop
1720 does_utf8_overflow
1721 dofile
1722 drand48_init_r
1723 drand48_r
1724 dtrace_probe_call
1725 dtrace_probe_load
1726 dtrace_probe_op
1727 dtrace_probe_phase
1728 dump_all_perl
1729 dump_packsubs_perl
1730 dump_sub_perl
1731 dump_sv_child
1732 dup_warnings
1733 emulate_cop_io
1734 find_first_differing_byte_pos
1735 find_lexical_cv
1736 find_runcv_where
1737 find_script
1738 foldEQ_latin1_s2_folded
1739 foldEQ_utf8_flags
1740 form_alien_digit_msg
1741 form_cp_too_large_msg
1742 free_tied_hv_pool
1743 get_and_check_backslash_N_name
1744 get_db_sub
1745 get_debug_opts
1746 get_deprecated_property_msg
1747 get_hash_seed
1748 get_invlist_iter_addr
1749 get_invlist_offset_addr
1750 get_invlist_previous_index_addr
1751 get_no_modify
1752 get_opargs
1753 get_prop_definition
1754 get_prop_values
1755 get_re_arg
1756 get_re_gclass_nonbitmap_data
1757 get_regclass_nonbitmap_data
1758 get_regex_charset_name
1759 getenv_len
1760 grok_bin_oct_hex
1761 grok_bslash_c
1762 grok_bslash_o
1763 grok_bslash_x
1764 gv_fetchmeth_internal
1765 gv_override
1766 gv_setref
1767 gv_stashpvn_internal
1768 gv_stashsvpvn_cached
1769 hfree_next_entry
1770 hv_backreferences_p
1771 hv_kill_backrefs
1772 hv_placeholders_p
1773 hv_pushkv
1774 hv_undef_flags
1775 init_argv_symbols
1776 init_constants
1777 init_dbargs
1778 init_debugger
1779 init_i18nl10n
1780 init_i18nl14n
1781 init_named_cv
1782 init_uniprops
1783 invert
1784 invlist_array
1785 invlist_clear
1786 invlist_clone
1787 invlist_contents
1788 invlist_extend
1789 invlist_highest
1790 invlist_is_iterating
1791 invlist_iterfinish
1792 invlist_iterinit
1793 invlist_iternext
1794 invlist_lowest
1795 invlist_max
1796 invlist_previous_index
1797 invlist_set_len
1798 invlist_set_previous_index
1799 invlist_trim
1800 invmap_dump
1801 io_close
1802 isFF_OVERLONG
1803 isFOO_lc
1804 is_grapheme
1805 is_invlist
1806 is_utf8_char_helper
1807 is_utf8_common
1808 is_utf8_overlong_given_start_byte_ok
1809 jmaybe
1810 keyword
1811 keyword_plugin_standard
1812 list
1813 load_charnames
1814 localize
1815 lossless_NV_to_IV
1816 magic_clear_all_env
1817 magic_cleararylen_p
1818 magic_clearenv
1819 magic_clearisa
1820 magic_clearpack
1821 magic_clearsig
1822 magic_copycallchecker
1823 magic_existspack
1824 magic_freearylen_p
1825 magic_freeovrld
1826 magic_get
1827 magic_getarylen
1828 magic_getdebugvar
1829 magic_getdefelem
1830 magic_getnkeys
1831 magic_getpack
1832 magic_getpos
1833 magic_getsig
1834 magic_getsubstr
1835 magic_gettaint
1836 magic_getuvar
1837 magic_getvec
1838 magic_killbackrefs
1839 magic_nextpack
1840 magic_regdata_cnt
1841 magic_regdatum_get
1842 magic_regdatum_set
1843 magic_scalarpack
1844 magic_set
1845 magic_set_all_env
1846 magic_setarylen
1847 magic_setcollxfrm
1848 magic_setdbline
1849 magic_setdebugvar
1850 magic_setdefelem
1851 magic_setenv
1852 magic_setisa
1853 magic_setlvref
1854 magic_setmglob
1855 magic_setnkeys
1856 magic_setnonelem
1857 magic_setpack
1858 magic_setpos
1859 magic_setregexp
1860 magic_setsig
1861 magic_setsubstr
1862 magic_settaint
1863 magic_setutf8
1864 magic_setuvar
1865 magic_setvec
1866 magic_sizepack
1867 magic_wipepack
1868 malloc_good_size
1869 malloced_size
1870 mem_collxfrm
1871 mem_log_alloc
1872 mem_log_free
1873 mem_log_realloc
1874 mg_find_mglob
1875 mode_from_discipline
1876 more_bodies
1877 mortal_getenv
1878 mro_meta_dup
1879 mro_meta_init
1880 multiconcat_stringify
1881 multideref_stringify
1882 my_atof2
1883 my_atof3
1884 my_attrs
1885 my_clearenv
1886 my_lstat_flags
1887 my_memrchr
1888 my_mkostemp
1889 my_mkostemp_cloexec
1890 my_mkstemp
1891 my_mkstemp_cloexec
1892 my_stat_flags
1893 my_strerror
1894 my_unexec
1895 newGP
1896 newMETHOP_internal
1897 newSTUB
1898 newSVavdefelem
1899 newXS_deffile
1900 new_warnings_bitfield
1901 nextargv
1902 noperl_die
1903 notify_parser_that_changed_to_utf8
1904 oopsAV
1905 oopsHV
1906 op_clear
1907 op_integerize
1908 op_lvalue_flags
1909 op_refcnt_dec
1910 op_refcnt_inc
1911 op_relocate_sv
1912 op_std_init
1913 op_unscope
1914 opmethod_stash
1915 opslab_force_free
1916 opslab_free
1917 opslab_free_nopad
1918 package
1919 package_version
1920 pad_add_weakref
1921 padlist_store
1922 padname_free
1923 padnamelist_free
1924 parse_unicode_opts
1925 parser_free
1926 parser_free_nexttoke_ops
1927 path_is_searchable
1928 peep
1929 pmruntime
1930 populate_isa
1931 ptr_hash
1932 qerror
1933 re_exec_indentf
1934 re_indentf
1935 re_intuit_start
1936 re_intuit_string
1937 re_op_compile
1938 re_printf
1939 reg_named_buff
1940 reg_named_buff_iter
1941 reg_numbered_buff_fetch
1942 reg_numbered_buff_length
1943 reg_numbered_buff_store
1944 reg_qr_package
1945 reg_skipcomment
1946 reg_temp_copy
1947 regcurly
1948 regprop
1949 report_evil_fh
1950 report_redefined_cv
1951 report_wrongway_fh
1952 rpeep
1953 rsignal_restore
1954 rsignal_save
1955 rxres_save
1956 same_dirent
1957 save_strlen
1958 save_to_buffer
1959 sawparens
1960 scalar
1961 scalarvoid
1962 scan_str
1963 scan_word
1964 set_caret_X
1965 set_numeric_standard
1966 set_numeric_underlying
1967 set_padlist
1968 setfd_cloexec
1969 setfd_cloexec_for_nonsysfd
1970 setfd_cloexec_or_inhexec_by_sysfdness
1971 setfd_inhexec
1972 setfd_inhexec_for_sysfd
1973 should_warn_nl
1974 should_we_output_Debug_r
1975 sighandler
1976 sighandler1
1977 sighandler3
1978 skipspace_flags
1979 softref2xv
1980 sortsv_flags_impl
1981 sub_crush_depth
1982 sv_add_backref
1983 sv_buf_to_ro
1984 sv_del_backref
1985 sv_free2
1986 sv_i_ncmp
1987 sv_i_ncmp_desc
1988 sv_kill_backrefs
1989 sv_len_utf8_nomg
1990 sv_magicext_mglob
1991 sv_ncmp
1992 sv_ncmp_desc
1993 sv_only_taint_gmagic
1994 sv_or_pv_pos_u2b
1995 sv_resetpvn
1996 sv_sethek
1997 sv_setsv_cow
1998 sv_unglob
1999 tied_method
2000 tmps_grow_p
2001 to_uni_fold
2002 to_uni_lower
2003 to_uni_title
2004 to_uni_upper
2005 translate_substr_offsets
2006 try_amagic_bin
2007 try_amagic_un
2008 uiv_2buf
2009 unshare_hek
2010 utf16_to_utf8
2011 utf16_to_utf8_reversed
2012 utf8_to_uvchr_buf_helper
2013 utilize
2014 uvoffuni_to_utf8_flags_msgs
2015 uvuni_to_utf8
2016 valid_utf8_to_uvuni
2017 variant_byte_number
2018 varname
2019 vivify_defelem
2020 vivify_ref
2021 wait4pid
2022 was_lvalue_sub
2023 watch
2024 win32_croak_not_implemented
2025 write_to_stderr
2026 xs_boot_epilog
2027 xs_handshake
2028 yyerror
2029 yyerror_pv
2030 yyerror_pvn
2031 yylex
2032 yyparse
2033 yyquit
2034 yyunlex
2035
2037 The autodocumentation system was originally added to the Perl core by
2038 Benjamin Stuhl. Documentation is by whoever was kind enough to
2039 document their functions.
2040
2042 config.h perlapi perlapio perlcall perlclib perlfilter perlguts
2043 perlmroapi perlxs perlxstut warnings
2044perl v5.32.1 2021-03-31 PERLINTERN(1)