1PERLINTERN(1)          Perl Programmers Reference Guide          PERLINTERN(1)
2
3
4

NAME

6       perlintern - autogenerated documentation of purely internal
7       Perl functions
8

DESCRIPTION

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

Compile-time scope hooks

16       BhkENTRY
17               NOTE: this function is experimental and may change or be
18               removed without notice.
19
20               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
25                       void *  BhkENTRY(BHK *hk, which)
26
27       BhkFLAGS
28               NOTE: this function is experimental and may change or be
29               removed without notice.
30
31               Return the BHK's flags.
32
33                       U32     BhkFLAGS(BHK *hk)
34
35       CALL_BLOCK_HOOKS
36               NOTE: this function is experimental and may change or be
37               removed without notice.
38
39               Call all the registered block hooks for type "which".  "which"
40               is a preprocessing token; the type of "arg" depends on "which".
41
42                       void    CALL_BLOCK_HOOKS(which, arg)
43

Custom Operators

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
52                       SV *    core_prototype(SV *sv, const char *name,
53                                              const int code,
54                                              int * const opnum)
55

CV Manipulation Functions

57       docatch Check for the cases 0 or 3 of cur_env.je_ret, only used inside
58               an eval context.
59
60               0 is used as continue inside eval,
61
62               3 is used for a die caught by an inner eval - continue inner
63               loop
64
65               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
69                       OP*     docatch(Perl_ppaddr_t firstpp)
70

CV reference counts and CvOUTSIDE

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
85               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
91                   BEGIN { $a = sub { eval '$x' } }
92
93               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
101               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
109               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
118                   my $x = 123;
119                   sub tmp { sub { eval '$x' } }
120                   my $a = tmp();
121                   undef &tmp;
122                   print  $a->();
123
124                       bool    CvWEAKOUTSIDE(CV *cv)
125

Embedding Functions

127       cv_dump dump the contents of a CV
128
129                       void    cv_dump(CV *cv, const char *title)
130
131       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
139                       void    cv_forget_slab(CV *cv)
140
141       do_dump_pad
142               Dump the contents of a padlist
143
144                       void    do_dump_pad(I32 level, PerlIO *file,
145                                           PADLIST *padlist, int full)
146
147       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
156                       PADOFFSET pad_alloc_name(PADNAME *name, U32 flags,
157                                                HV *typestash, HV *ourstash)
158
159       pad_block_start
160               Update the pad compilation state variables on entry to a new
161               block.
162
163                       void    pad_block_start(int full)
164
165       pad_check_dup
166               Check for duplicate declarations: report any of:
167
168                    * 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
172               "is_our" indicates that the name to check is an "our"
173               declaration.
174
175                       void    pad_check_dup(PADNAME *name, U32 flags,
176                                             const HV *ourstash)
177
178       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
182               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
193               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
199                       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
206       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
211                       void    pad_fixup_inner_anons(PADLIST *padlist,
212                                                     CV *old_cv, CV *new_cv)
213
214       pad_free
215               Free the SV at offset po in the current pad.
216
217                       void    pad_free(PADOFFSET po)
218
219       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
224                       void    pad_leavemy()
225
226       padlist_dup
227               Duplicates a pad.
228
229                       PADLIST * padlist_dup(PADLIST *srcpad,
230                                             CLONE_PARAMS *param)
231
232       padname_dup
233               Duplicates a pad name.
234
235                       PADNAME * padname_dup(PADNAME *src, CLONE_PARAMS *param)
236
237       padnamelist_dup
238               Duplicates a pad name list.
239
240                       PADNAMELIST * padnamelist_dup(PADNAMELIST *srcpad,
241                                                     CLONE_PARAMS *param)
242
243       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
248                       void    pad_push(PADLIST *padlist, int depth)
249
250       pad_reset
251               Mark all the current temporaries for reuse
252
253                       void    pad_reset()
254
255       pad_swipe
256               Abandon the tmp in the current pad at offset "po" and replace
257               with a new one.
258
259                       void    pad_swipe(PADOFFSET po, bool refadjust)
260

GV Functions

262       gv_try_downgrade
263               NOTE: this function is experimental and may change or be
264               removed without notice.
265
266               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
276               If "gv" is a completely empty typeglob, it is deleted from the
277               stash.
278
279               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
283                       void    gv_try_downgrade(GV* gv)
284

Hash Manipulation Functions

286       hv_ename_add
287               Adds a name to a stash's internal list of effective names.  See
288               "hv_ename_delete".
289
290               This is called when a stash is assigned to a new location in
291               the symbol table.
292
293                       void    hv_ename_add(HV *hv, const char *name, U32 len,
294                                            U32 flags)
295
296       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
301               This is called when a stash is deleted from the symbol table.
302
303                       void    hv_ename_delete(HV *hv, const char *name,
304                                               U32 len, U32 flags)
305
306       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
311                       HV *    refcounted_he_chain_2hv(
312                                   const struct refcounted_he *c, U32 flags
313                               )
314
315       refcounted_he_fetch_pv
316               Like "refcounted_he_fetch_pvn", but takes a nul-terminated
317               string instead of a string/length pair.
318
319                       SV *    refcounted_he_fetch_pv(
320                                   const struct refcounted_he *chain,
321                                   const char *key, U32 hash, U32 flags
322                               )
323
324       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
335                       SV *    refcounted_he_fetch_pvn(
336                                   const struct refcounted_he *chain,
337                                   const char *keypv, STRLEN keylen, U32 hash,
338                                   U32 flags
339                               )
340
341       refcounted_he_fetch_pvs
342               Like "refcounted_he_fetch_pvn", but takes a literal string
343               instead of a string/length pair, and no precomputed hash.
344
345                       SV *    refcounted_he_fetch_pvs(
346                                   const struct refcounted_he *chain,
347                                   "literal string" key, U32 flags
348                               )
349
350       refcounted_he_fetch_sv
351               Like "refcounted_he_fetch_pvn", but takes a Perl scalar instead
352               of a string/length pair.
353
354                       SV *    refcounted_he_fetch_sv(
355                                   const struct refcounted_he *chain, SV *key,
356                                   U32 hash, U32 flags
357                               )
358
359       refcounted_he_free
360               Decrements the reference count of a "refcounted_he" by one.  If
361               the reference count reaches zero the structure's memory is
362               freed, which (recursively) causes a reduction of its parent
363               "refcounted_he"'s reference count.  It is safe to pass a null
364               pointer to this function: no action occurs in this case.
365
366                       void    refcounted_he_free(struct refcounted_he *he)
367
368       refcounted_he_inc
369               Increment the reference count of a "refcounted_he".  The
370               pointer to the "refcounted_he" is also returned.  It is safe to
371               pass a null pointer to this function: no action occurs and a
372               null pointer is returned.
373
374                       struct refcounted_he * refcounted_he_inc(
375                                                  struct refcounted_he *he
376                                              )
377
378       refcounted_he_new_pv
379               Like "refcounted_he_new_pvn", but takes a nul-terminated string
380               instead of a string/length pair.
381
382                       struct refcounted_he * refcounted_he_new_pv(
383                                                  struct refcounted_he *parent,
384                                                  const char *key, U32 hash,
385                                                  SV *value, U32 flags
386                                              )
387
388       refcounted_he_new_pvn
389               Creates a new "refcounted_he".  This consists of a single
390               key/value pair and a reference to an existing "refcounted_he"
391               chain (which may be empty), and thus forms a longer chain.
392               When using the longer chain, the new key/value pair takes
393               precedence over any entry for the same key further along the
394               chain.
395
396               The new key is specified by "keypv" and "keylen".  If "flags"
397               has the "REFCOUNTED_HE_KEY_UTF8" bit set, the key octets are
398               interpreted as UTF-8, otherwise they are interpreted as
399               Latin-1.  "hash" is a precomputed hash of the key string, or
400               zero if it has not been precomputed.
401
402               "value" is the scalar value to store for this key.  "value" is
403               copied by this function, which thus does not take ownership of
404               any reference to it, and later changes to the scalar will not
405               be reflected in the value visible in the "refcounted_he".
406               Complex types of scalar will not be stored with referential
407               integrity, but will be coerced to strings.  "value" may be
408               either null or &PL_sv_placeholder to indicate that no value is
409               to be associated with the key; this, as with any non-null
410               value, takes precedence over the existence of a value for the
411               key further along the chain.
412
413               "parent" points to the rest of the "refcounted_he" chain to be
414               attached to the new "refcounted_he".  This function takes
415               ownership of one reference to "parent", and returns one
416               reference to the new "refcounted_he".
417
418                       struct refcounted_he * refcounted_he_new_pvn(
419                                                  struct refcounted_he *parent,
420                                                  const char *keypv,
421                                                  STRLEN keylen, U32 hash,
422                                                  SV *value, U32 flags
423                                              )
424
425       refcounted_he_new_pvs
426               Like "refcounted_he_new_pvn", but takes a literal string
427               instead of a string/length pair, and no precomputed hash.
428
429                       struct refcounted_he * refcounted_he_new_pvs(
430                                                  struct refcounted_he *parent,
431                                                  "literal string" key,
432                                                  SV *value, U32 flags
433                                              )
434
435       refcounted_he_new_sv
436               Like "refcounted_he_new_pvn", but takes a Perl scalar instead
437               of a string/length pair.
438
439                       struct refcounted_he * refcounted_he_new_sv(
440                                                  struct refcounted_he *parent,
441                                                  SV *key, U32 hash, SV *value,
442                                                  U32 flags
443                                              )
444

IO Functions

446       start_glob
447               NOTE: this function is experimental and may change or be
448               removed without notice.
449
450               Function called by "do_readline" to spawn a glob (or do the
451               glob inside perl on VMS).  This code used to be inline, but now
452               perl uses "File::Glob" this glob starter is only used by
453               miniperl during the build process, or when PERL_EXTERNAL_GLOB
454               is defined.  Moving it away shrinks pp_hot.c; shrinking
455               pp_hot.c helps speed perl up.
456
457                       PerlIO* start_glob(SV *tmpglob, IO *io)
458

Lexer interface

460       validate_proto
461               NOTE: this function is experimental and may change or be
462               removed without notice.
463
464               This function performs syntax checking on a prototype, "proto".
465               If "warn" is true, any illegal characters or mismatched
466               brackets will trigger illegalproto warnings, declaring that
467               they were detected in the prototype for "name".
468
469               The return value is "true" if this is a valid prototype, and
470               "false" if it is not, regardless of whether "warn" was "true"
471               or "false".
472
473               Note that "NULL" is a valid "proto" and will always return
474               "true".
475
476               NOTE: the perl_ form of this function is deprecated.
477
478                       bool    validate_proto(SV *name, SV *proto, bool warn,
479                                              bool curstash)
480

Magical Functions

482       magic_clearhint
483               Triggered by a delete from "%^H", records the key to
484               "PL_compiling.cop_hints_hash".
485
486                       int     magic_clearhint(SV* sv, MAGIC* mg)
487
488       magic_clearhints
489               Triggered by clearing "%^H", resets
490               "PL_compiling.cop_hints_hash".
491
492                       int     magic_clearhints(SV* sv, MAGIC* mg)
493
494       magic_methcall
495               Invoke a magic method (like FETCH).
496
497               "sv" and "mg" are the tied thingy and the tie magic.
498
499               "meth" is the name of the method to call.
500
501               "argc" is the number of args (in addition to $self) to pass to
502               the method.
503
504               The "flags" can be:
505
506                   G_DISCARD     invoke method with G_DISCARD flag and don't
507                                 return a value
508                   G_UNDEF_FILL  fill the stack with argc pointers to
509                                 PL_sv_undef
510
511               The arguments themselves are any values following the "flags"
512               argument.
513
514               Returns the SV (if any) returned by the method, or "NULL" on
515               failure.
516
517                       SV*     magic_methcall(SV *sv, const MAGIC *mg,
518                                              SV *meth, U32 flags, U32 argc,
519                                              ...)
520
521       magic_sethint
522               Triggered by a store to "%^H", records the key/value pair to
523               "PL_compiling.cop_hints_hash".  It is assumed that hints aren't
524               storing anything that would need a deep copy.  Maybe we should
525               warn if we find a reference.
526
527                       int     magic_sethint(SV* sv, MAGIC* mg)
528
529       mg_localize
530               Copy some of the magic from an existing SV to new localized
531               version of that SV.  Container magic (e.g., %ENV, $1, "tie")
532               gets copied, value magic doesn't (e.g., "taint", "pos").
533
534               If "setmagic" is false then no set magic will be called on the
535               new (empty) SV.  This typically means that assignment will soon
536               follow (e.g. 'local $x = $y'), and that will handle the magic.
537
538                       void    mg_localize(SV* sv, SV* nsv, bool setmagic)
539

Miscellaneous Functions

541       free_c_backtrace
542               Deallocates a backtrace received from get_c_bracktrace.
543
544                       void    free_c_backtrace(Perl_c_backtrace* bt)
545
546       get_c_backtrace
547               Collects the backtrace (aka "stacktrace") into a single linear
548               malloced buffer, which the caller must
549               "Perl_free_c_backtrace()".
550
551               Scans the frames back by "depth + skip", then drops the "skip"
552               innermost, returning at most "depth" frames.
553
554                       Perl_c_backtrace* get_c_backtrace(int max_depth,
555                                                         int skip)
556

MRO Functions

558       mro_get_linear_isa_dfs
559               Returns the Depth-First Search linearization of @ISA the given
560               stash.  The return value is a read-only AV*.  "level" should be
561               0 (it is used internally in this function's recursion).
562
563               You are responsible for "SvREFCNT_inc()" on the return value if
564               you plan to store it anywhere semi-permanently (otherwise it
565               might be deleted out from under you the next time the cache is
566               invalidated).
567
568                       AV*     mro_get_linear_isa_dfs(HV* stash, U32 level)
569
570       mro_isa_changed_in
571               Takes the necessary steps (cache invalidations, mostly) when
572               the @ISA of the given package has changed.  Invoked by the
573               "setisa" magic, should not need to invoke directly.
574
575                       void    mro_isa_changed_in(HV* stash)
576
577       mro_package_moved
578               Call this function to signal to a stash that it has been
579               assigned to another spot in the stash hierarchy.  "stash" is
580               the stash that has been assigned.  "oldstash" is the stash it
581               replaces, if any.  "gv" is the glob that is actually being
582               assigned to.
583
584               This can also be called with a null first argument to indicate
585               that "oldstash" has been deleted.
586
587               This function invalidates isa caches on the old stash, on all
588               subpackages nested inside it, and on the subclasses of all
589               those, including non-existent packages that have corresponding
590               entries in "stash".
591
592               It also sets the effective names ("HvENAME") on all the stashes
593               as appropriate.
594
595               If the "gv" is present and is not in the symbol table, then
596               this function simply returns.  This checked will be skipped if
597               "flags & 1".
598
599                       void    mro_package_moved(HV * const stash,
600                                                 HV * const oldstash,
601                                                 const GV * const gv,
602                                                 U32 flags)
603

Numeric functions

605       grok_atoUV
606               parse a string, looking for a decimal unsigned integer.
607
608               On entry, "pv" points to the beginning of the string; "valptr"
609               points to a UV that will receive the converted value, if found;
610               "endptr" is either NULL or points to a variable that points to
611               one byte beyond the point in "pv" that this routine should
612               examine.  If "endptr" is NULL, "pv" is assumed to be NUL-
613               terminated.
614
615               Returns FALSE if "pv" doesn't represent a valid unsigned
616               integer value (with no leading zeros).  Otherwise it returns
617               TRUE, and sets *valptr to that value.
618
619               If you constrain the portion of "pv" that is looked at by this
620               function (by passing a non-NULL "endptr"), and if the intial
621               bytes of that portion form a valid value, it will return TRUE,
622               setting *endptr to the byte following the final digit of the
623               value.  But if there is no constraint at what's looked at, all
624               of "pv" must be valid in order for TRUE to be returned.
625
626               The only characters this accepts are the decimal digits
627               '0'..'9'.
628
629               As opposed to atoi(3) or strtol(3), "grok_atoUV" does NOT allow
630               optional leading whitespace, nor negative inputs.  If such
631               features are required, the calling code needs to explicitly
632               implement those.
633
634               Note that this function returns FALSE for inputs that would
635               overflow a UV, or have leading zeros.  Thus a single 0 is
636               accepted, but not 00 nor 01, 002, etc.
637
638               Background: "atoi" has severe problems with illegal inputs, it
639               cannot be used for incremental parsing, and therefore should be
640               avoided "atoi" and "strtol" are also affected by locale
641               settings, which can also be seen as a bug (global state
642               controlled by user environment).
643
644                       bool    grok_atoUV(const char* pv, UV* valptr,
645                                          const char** endptr)
646

Optree Manipulation Functions

648       finalize_optree
649               This function finalizes the optree.  Should be called directly
650               after the complete optree is built.  It does some additional
651               checking which can't be done in the normal "ck_"xxx functions
652               and makes the tree thread-safe.
653
654                       void    finalize_optree(OP* o)
655
656       newATTRSUB_x
657               Construct a Perl subroutine, also performing some surrounding
658               jobs.
659
660               This function is expected to be called in a Perl compilation
661               context, and some aspects of the subroutine are taken from
662               global variables associated with compilation.  In particular,
663               "PL_compcv" represents the subroutine that is currently being
664               compiled.  It must be non-null when this function is called,
665               and some aspects of the subroutine being constructed are taken
666               from it.  The constructed subroutine may actually be a reuse of
667               the "PL_compcv" object, but will not necessarily be so.
668
669               If "block" is null then the subroutine will have no body, and
670               for the time being it will be an error to call it.  This
671               represents a forward subroutine declaration such as
672               "sub foo ($$);".  If "block" is non-null then it provides the
673               Perl code of the subroutine body, which will be executed when
674               the subroutine is called.  This body includes any argument
675               unwrapping code resulting from a subroutine signature or
676               similar.  The pad use of the code must correspond to the pad
677               attached to "PL_compcv".  The code is not expected to include a
678               "leavesub" or "leavesublv" op; this function will add such an
679               op.  "block" is consumed by this function and will become part
680               of the constructed subroutine.
681
682               "proto" specifies the subroutine's prototype, unless one is
683               supplied as an attribute (see below).  If "proto" is null, then
684               the subroutine will not have a prototype.  If "proto" is non-
685               null, it must point to a "const" op whose value is a string,
686               and the subroutine will have that string as its prototype.  If
687               a prototype is supplied as an attribute, the attribute takes
688               precedence over "proto", but in that case "proto" should
689               preferably be null.  In any case, "proto" is consumed by this
690               function.
691
692               "attrs" supplies attributes to be applied the subroutine.  A
693               handful of attributes take effect by built-in means, being
694               applied to "PL_compcv" immediately when seen.  Other attributes
695               are collected up and attached to the subroutine by this route.
696               "attrs" may be null to supply no attributes, or point to a
697               "const" op for a single attribute, or point to a "list" op
698               whose children apart from the "pushmark" are "const" ops for
699               one or more attributes.  Each "const" op must be a string,
700               giving the attribute name optionally followed by parenthesised
701               arguments, in the manner in which attributes appear in Perl
702               source.  The attributes will be applied to the sub by this
703               function.  "attrs" is consumed by this function.
704
705               If "o_is_gv" is false and "o" is null, then the subroutine will
706               be anonymous.  If "o_is_gv" is false and "o" is non-null, then
707               "o" must point to a "const" op, which will be consumed by this
708               function, and its string value supplies a name for the
709               subroutine.  The name may be qualified or unqualified, and if
710               it is unqualified then a default stash will be selected in some
711               manner.  If "o_is_gv" is true, then "o" doesn't point to an
712               "OP" at all, but is instead a cast pointer to a "GV" by which
713               the subroutine will be named.
714
715               If there is already a subroutine of the specified name, then
716               the new sub will either replace the existing one in the glob or
717               be merged with the existing one.  A warning may be generated
718               about redefinition.
719
720               If the subroutine has one of a few special names, such as
721               "BEGIN" or "END", then it will be claimed by the appropriate
722               queue for automatic running of phase-related subroutines.  In
723               this case the relevant glob will be left not containing any
724               subroutine, even if it did contain one before.  In the case of
725               "BEGIN", the subroutine will be executed and the reference to
726               it disposed of before this function returns.
727
728               The function returns a pointer to the constructed subroutine.
729               If the sub is anonymous then ownership of one counted reference
730               to the subroutine is transferred to the caller.  If the sub is
731               named then the caller does not get ownership of a reference.
732               In most such cases, where the sub has a non-phase name, the sub
733               will be alive at the point it is returned by virtue of being
734               contained in the glob that names it.  A phase-named subroutine
735               will usually be alive by virtue of the reference owned by the
736               phase's automatic run queue.  But a "BEGIN" subroutine, having
737               already been executed, will quite likely have been destroyed
738               already by the time this function returns, making it erroneous
739               for the caller to make any use of the returned pointer.  It is
740               the caller's responsibility to ensure that it knows which of
741               these situations applies.
742
743                       CV *    newATTRSUB_x(I32 floor, OP *o, OP *proto,
744                                            OP *attrs, OP *block, bool o_is_gv)
745
746       newXS_len_flags
747               Construct an XS subroutine, also performing some surrounding
748               jobs.
749
750               The subroutine will have the entry point "subaddr".  It will
751               have the prototype specified by the nul-terminated string
752               "proto", or no prototype if "proto" is null.  The prototype
753               string is copied; the caller can mutate the supplied string
754               afterwards.  If "filename" is non-null, it must be a nul-
755               terminated filename, and the subroutine will have its "CvFILE"
756               set accordingly.  By default "CvFILE" is set to point directly
757               to the supplied string, which must be static.  If "flags" has
758               the "XS_DYNAMIC_FILENAME" bit set, then a copy of the string
759               will be taken instead.
760
761               Other aspects of the subroutine will be left in their default
762               state.  If anything else needs to be done to the subroutine for
763               it to function correctly, it is the caller's responsibility to
764               do that after this function has constructed it.  However,
765               beware of the subroutine potentially being destroyed before
766               this function returns, as described below.
767
768               If "name" is null then the subroutine will be anonymous, with
769               its "CvGV" referring to an "__ANON__" glob.  If "name" is non-
770               null then the subroutine will be named accordingly, referenced
771               by the appropriate glob.  "name" is a string of length "len"
772               bytes giving a sigilless symbol name, in UTF-8 if "flags" has
773               the "SVf_UTF8" bit set and in Latin-1 otherwise.  The name may
774               be either qualified or unqualified, with the stash defaulting
775               in the same manner as for "gv_fetchpvn_flags".  "flags" may
776               contain flag bits understood by "gv_fetchpvn_flags" with the
777               same meaning as they have there, such as "GV_ADDWARN".  The
778               symbol is always added to the stash if necessary, with
779               "GV_ADDMULTI" semantics.
780
781               If there is already a subroutine of the specified name, then
782               the new sub will replace the existing one in the glob.  A
783               warning may be generated about the redefinition.  If the old
784               subroutine was "CvCONST" then the decision about whether to
785               warn is influenced by an expectation about whether the new
786               subroutine will become a constant of similar value.  That
787               expectation is determined by "const_svp".  (Note that the call
788               to this function doesn't make the new subroutine "CvCONST" in
789               any case; that is left to the caller.)  If "const_svp" is null
790               then it indicates that the new subroutine will not become a
791               constant.  If "const_svp" is non-null then it indicates that
792               the new subroutine will become a constant, and it points to an
793               "SV*" that provides the constant value that the subroutine will
794               have.
795
796               If the subroutine has one of a few special names, such as
797               "BEGIN" or "END", then it will be claimed by the appropriate
798               queue for automatic running of phase-related subroutines.  In
799               this case the relevant glob will be left not containing any
800               subroutine, even if it did contain one before.  In the case of
801               "BEGIN", the subroutine will be executed and the reference to
802               it disposed of before this function returns, and also before
803               its prototype is set.  If a "BEGIN" subroutine would not be
804               sufficiently constructed by this function to be ready for
805               execution then the caller must prevent this happening by giving
806               the subroutine a different name.
807
808               The function returns a pointer to the constructed subroutine.
809               If the sub is anonymous then ownership of one counted reference
810               to the subroutine is transferred to the caller.  If the sub is
811               named then the caller does not get ownership of a reference.
812               In most such cases, where the sub has a non-phase name, the sub
813               will be alive at the point it is returned by virtue of being
814               contained in the glob that names it.  A phase-named subroutine
815               will usually be alive by virtue of the reference owned by the
816               phase's automatic run queue.  But a "BEGIN" subroutine, having
817               already been executed, will quite likely have been destroyed
818               already by the time this function returns, making it erroneous
819               for the caller to make any use of the returned pointer.  It is
820               the caller's responsibility to ensure that it knows which of
821               these situations applies.
822
823                       CV *    newXS_len_flags(const char *name, STRLEN len,
824                                               XSUBADDR_t subaddr,
825                                               const char *const filename,
826                                               const char *const proto,
827                                               SV **const_svp, U32 flags)
828
829       optimize_optree
830               This function applies some optimisations to the optree in top-
831               down order.  It is called before the peephole optimizer, which
832               processes ops in execution order. Note that finalize_optree()
833               also does a top-down scan, but is called *after* the peephole
834               optimizer.
835
836                       void    optimize_optree(OP* o)
837
838       traverse_op_tree
839               Return the next op in a depth-first traversal of the op tree,
840               returning NULL when the traversal is complete.
841
842               The initial call must supply the root of the tree as both top
843               and o.
844
845               For now it's static, but it may be exposed to the API in the
846               future.
847
848                               traverse_op_tree;
849

Pad Data Structures

851       CX_CURPAD_SAVE
852               Save the current pad in the given context block structure.
853
854                       void    CX_CURPAD_SAVE(struct context)
855
856       CX_CURPAD_SV
857               Access the SV at offset "po" in the saved current pad in the
858               given context block structure (can be used as an lvalue).
859
860                       SV *    CX_CURPAD_SV(struct context, PADOFFSET po)
861
862       PAD_BASE_SV
863               Get the value from slot "po" in the base (DEPTH=1) pad of a
864               padlist
865
866                       SV *    PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
867
868       PAD_CLONE_VARS
869               Clone the state variables associated with running and compiling
870               pads.
871
872                       void    PAD_CLONE_VARS(PerlInterpreter *proto_perl,
873                                              CLONE_PARAMS* param)
874
875       PAD_COMPNAME_FLAGS
876               Return the flags for the current compiling pad name at offset
877               "po".  Assumes a valid slot entry.
878
879                       U32     PAD_COMPNAME_FLAGS(PADOFFSET po)
880
881       PAD_COMPNAME_GEN
882               The generation number of the name at offset "po" in the current
883               compiling pad (lvalue).
884
885                       STRLEN  PAD_COMPNAME_GEN(PADOFFSET po)
886
887       PAD_COMPNAME_GEN_set
888               Sets the generation number of the name at offset "po" in the
889               current ling pad (lvalue) to "gen".
890                    STRLEN    PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
891
892       PAD_COMPNAME_OURSTASH
893               Return the stash associated with an "our" variable.  Assumes
894               the slot entry is a valid "our" lexical.
895
896                       HV *    PAD_COMPNAME_OURSTASH(PADOFFSET po)
897
898       PAD_COMPNAME_PV
899               Return the name of the current compiling pad name at offset
900               "po".  Assumes a valid slot entry.
901
902                       char *  PAD_COMPNAME_PV(PADOFFSET po)
903
904       PAD_COMPNAME_TYPE
905               Return the type (stash) of the current compiling pad name at
906               offset "po".  Must be a valid name.  Returns null if not typed.
907
908                       HV *    PAD_COMPNAME_TYPE(PADOFFSET po)
909
910       PadnameIsOUR
911               Whether this is an "our" variable.
912
913                       bool    PadnameIsOUR(PADNAME pn)
914
915       PadnameIsSTATE
916               Whether this is a "state" variable.
917
918                       bool    PadnameIsSTATE(PADNAME pn)
919
920       PadnameOURSTASH
921               The stash in which this "our" variable was declared.
922
923                       HV *    PadnameOURSTASH()
924
925       PadnameOUTER
926               Whether this entry belongs to an outer pad.  Entries for which
927               this is true are often referred to as 'fake'.
928
929                       bool    PadnameOUTER(PADNAME pn)
930
931       PadnameTYPE
932               The stash associated with a typed lexical.  This returns the
933               %Foo:: hash for "my Foo $bar".
934
935                       HV *    PadnameTYPE(PADNAME pn)
936
937       PAD_RESTORE_LOCAL
938               Restore the old pad saved into the local variable "opad" by
939               "PAD_SAVE_LOCAL()"
940
941                       void    PAD_RESTORE_LOCAL(PAD *opad)
942
943       PAD_SAVE_LOCAL
944               Save the current pad to the local variable "opad", then make
945               the current pad equal to "npad"
946
947                       void    PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
948
949       PAD_SAVE_SETNULLPAD
950               Save the current pad then set it to null.
951
952                       void    PAD_SAVE_SETNULLPAD()
953
954       PAD_SETSV
955               Set the slot at offset "po" in the current pad to "sv"
956
957                       SV *    PAD_SETSV(PADOFFSET po, SV* sv)
958
959       PAD_SET_CUR
960               Set the current pad to be pad "n" in the padlist, saving the
961               previous current pad.  NB currently this macro expands to a
962               string too long for some compilers, so it's best to replace it
963               with
964
965                   SAVECOMPPAD();
966                   PAD_SET_CUR_NOSAVE(padlist,n);
967
968
969                       void    PAD_SET_CUR(PADLIST padlist, I32 n)
970
971       PAD_SET_CUR_NOSAVE
972               like PAD_SET_CUR, but without the save
973
974                       void    PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
975
976       PAD_SV  Get the value at offset "po" in the current pad
977
978                       SV *    PAD_SV(PADOFFSET po)
979
980       PAD_SVl Lightweight and lvalue version of "PAD_SV".  Get or set the
981               value at offset "po" in the current pad.  Unlike "PAD_SV", does
982               not print diagnostics with -DX.  For internal use only.
983
984                       SV *    PAD_SVl(PADOFFSET po)
985
986       SAVECLEARSV
987               Clear the pointed to pad value on scope exit.  (i.e. the
988               runtime action of "my")
989
990                       void    SAVECLEARSV(SV **svp)
991
992       SAVECOMPPAD
993               save "PL_comppad" and "PL_curpad"
994
995                       void    SAVECOMPPAD()
996
997       SAVEPADSV
998               Save a pad slot (used to restore after an iteration)
999
1000               XXX DAPM it would make more sense to make the arg a PADOFFSET
1001                    void SAVEPADSV(PADOFFSET po)
1002

Per-Interpreter Variables

1004       PL_DBsingle
1005               When Perl is run in debugging mode, with the -d switch, this SV
1006               is a boolean which indicates whether subs are being single-
1007               stepped.  Single-stepping is automatically turned on after
1008               every step.  This is the C variable which corresponds to Perl's
1009               $DB::single variable.  See "PL_DBsub".
1010
1011                       SV *    PL_DBsingle
1012
1013       PL_DBsub
1014               When Perl is run in debugging mode, with the -d switch, this GV
1015               contains the SV which holds the name of the sub being debugged.
1016               This is the C variable which corresponds to Perl's $DB::sub
1017               variable.  See "PL_DBsingle".
1018
1019                       GV *    PL_DBsub
1020
1021       PL_DBtrace
1022               Trace variable used when Perl is run in debugging mode, with
1023               the -d switch.  This is the C variable which corresponds to
1024               Perl's $DB::trace variable.  See "PL_DBsingle".
1025
1026                       SV *    PL_DBtrace
1027
1028       PL_dowarn
1029               The C variable that roughly corresponds to Perl's $^W warning
1030               variable.  However, $^W is treated as a boolean, whereas
1031               "PL_dowarn" is a collection of flag bits.
1032
1033                       U8      PL_dowarn
1034
1035       PL_last_in_gv
1036               The GV which was last used for a filehandle input operation.
1037               ("<FH>")
1038
1039                       GV*     PL_last_in_gv
1040
1041       PL_ofsgv
1042               The glob containing the output field separator - "*," in Perl
1043               space.
1044
1045                       GV*     PL_ofsgv
1046
1047       PL_rs   The input record separator - $/ in Perl space.
1048
1049                       SV*     PL_rs
1050

Stack Manipulation Macros

1052       djSP    Declare Just "SP".  This is actually identical to "dSP", and
1053               declares a local copy of perl's stack pointer, available via
1054               the "SP" macro.  See ""SP" in perlapi".  (Available for
1055               backward source code compatibility with the old (Perl 5.005)
1056               thread model.)
1057
1058                               djSP;
1059
1060       LVRET   True if this op will be the return value of an lvalue
1061               subroutine
1062

SV Manipulation Functions

1064       An SV (or AV, HV, etc.) is allocated in two parts: the head (struct sv,
1065       av, hv...) contains type and reference count information, and for many
1066       types, a pointer to the body (struct xrv, xpv, xpviv...), which
1067       contains fields specific to each type.  Some types store all they need
1068       in the head, so don't have a body.
1069
1070       In all but the most memory-paranoid configurations (ex: PURIFY), heads
1071       and bodies are allocated out of arenas, which by default are
1072       approximately 4K chunks of memory parcelled up into N heads or bodies.
1073       Sv-bodies are allocated by their sv-type, guaranteeing size consistency
1074       needed to allocate safely from arrays.
1075
1076       For SV-heads, the first slot in each arena is reserved, and holds a
1077       link to the next arena, some flags, and a note of the number of slots.
1078       Snaked through each arena chain is a linked list of free items; when
1079       this becomes empty, an extra arena is allocated and divided up into N
1080       items which are threaded into the free list.
1081
1082       SV-bodies are similar, but they use arena-sets by default, which
1083       separate the link and info from the arena itself, and reclaim the 1st
1084       slot in the arena.  SV-bodies are further described later.
1085
1086       The following global variables are associated with arenas:
1087
1088        PL_sv_arenaroot     pointer to list of SV arenas
1089        PL_sv_root          pointer to list of free SV structures
1090
1091        PL_body_arenas      head of linked-list of body arenas
1092        PL_body_roots[]     array of pointers to list of free bodies of svtype
1093                            arrays are indexed by the svtype needed
1094
1095       A few special SV heads are not allocated from an arena, but are instead
1096       directly created in the interpreter structure, eg PL_sv_undef.  The
1097       size of arenas can be changed from the default by setting
1098       PERL_ARENA_SIZE appropriately at compile time.
1099
1100       The SV arena serves the secondary purpose of allowing still-live SVs to
1101       be located and destroyed during final cleanup.
1102
1103       At the lowest level, the macros new_SV() and del_SV() grab and free an
1104       SV head.  (If debugging with -DD, del_SV() calls the function
1105       S_del_sv() to return the SV to the free list with error checking.)
1106       new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the
1107       free list is empty.  SVs in the free list have their SvTYPE field set
1108       to all ones.
1109
1110       At the time of very final cleanup, sv_free_arenas() is called from
1111       perl_destruct() to physically free all the arenas allocated since the
1112       start of the interpreter.
1113
1114       The function visit() scans the SV arenas list, and calls a specified
1115       function for each SV it finds which is still live - ie which has an
1116       SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is used by
1117       the following functions (specified as [function that calls visit()] /
1118       [function called by visit() for each SV]):
1119
1120           sv_report_used() / do_report_used()
1121                               dump all remaining SVs (debugging aid)
1122
1123           sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
1124                             do_clean_named_io_objs(),do_curse()
1125                               Attempt to free all objects pointed to by RVs,
1126                               try to do the same for all objects indir-
1127                               ectly referenced by typeglobs too, and
1128                               then do a final sweep, cursing any
1129                               objects that remain.  Called once from
1130                               perl_destruct(), prior to calling sv_clean_all()
1131                               below.
1132
1133           sv_clean_all() / do_clean_all()
1134                               SvREFCNT_dec(sv) each remaining SV, possibly
1135                               triggering an sv_free(). It also sets the
1136                               SVf_BREAK flag on the SV to indicate that the
1137                               refcnt has been artificially lowered, and thus
1138                               stopping sv_free() from giving spurious warnings
1139                               about SVs which unexpectedly have a refcnt
1140                               of zero.  called repeatedly from perl_destruct()
1141                               until there are no SVs left.
1142
1143       sv_2num NOTE: this function is experimental and may change or be
1144               removed without notice.
1145
1146               Return an SV with the numeric value of the source SV, doing any
1147               necessary reference or overload conversion.  The caller is
1148               expected to have handled get-magic already.
1149
1150                       SV*     sv_2num(SV *const sv)
1151
1152       sv_add_arena
1153               Given a chunk of memory, link it to the head of the list of
1154               arenas, and split it into a list of free SVs.
1155
1156                       void    sv_add_arena(char *const ptr, const U32 size,
1157                                            const U32 flags)
1158
1159       sv_clean_all
1160               Decrement the refcnt of each remaining SV, possibly triggering
1161               a cleanup.  This function may have to be called multiple times
1162               to free SVs which are in complex self-referential hierarchies.
1163
1164                       I32     sv_clean_all()
1165
1166       sv_clean_objs
1167               Attempt to destroy all objects not yet freed.
1168
1169                       void    sv_clean_objs()
1170
1171       sv_free_arenas
1172               Deallocate the memory used by all arenas.  Note that all the
1173               individual SV heads and bodies within the arenas must already
1174               have been freed.
1175
1176                       void    sv_free_arenas()
1177
1178       SvTHINKFIRST
1179               A quick flag check to see whether an "sv" should be passed to
1180               "sv_force_normal" to be "downgraded" before "SvIVX" or "SvPVX"
1181               can be modified directly.
1182
1183               For example, if your scalar is a reference and you want to
1184               modify the "SvIVX" slot, you can't just do "SvROK_off", as that
1185               will leak the referent.
1186
1187               This is used internally by various sv-modifying functions, such
1188               as "sv_setsv", "sv_setiv" and "sv_pvn_force".
1189
1190               One case that this does not handle is a gv without SvFAKE set.
1191               After
1192
1193                   if (SvTHINKFIRST(gv)) sv_force_normal(gv);
1194
1195               it will still be a gv.
1196
1197               "SvTHINKFIRST" sometimes produces false positives.  In those
1198               cases "sv_force_normal" does nothing.
1199
1200                       U32     SvTHINKFIRST(SV *sv)
1201

Unicode Support

1203       find_uninit_var
1204               NOTE: this function is experimental and may change or be
1205               removed without notice.
1206
1207               Find the name of the undefined variable (if any) that caused
1208               the operator to issue a "Use of uninitialized value" warning.
1209               If match is true, only return a name if its value matches
1210               "uninit_sv".  So roughly speaking, if a unary operator (such as
1211               "OP_COS") generates a warning, then following the direct child
1212               of the op may yield an "OP_PADSV" or "OP_GV" that gives the
1213               name of the undefined variable.  On the other hand, with
1214               "OP_ADD" there are two branches to follow, so we only print the
1215               variable name if we get an exact match.  "desc_p" points to a
1216               string pointer holding the description of the op.  This may be
1217               updated if needed.
1218
1219               The name is returned as a mortal SV.
1220
1221               Assumes that "PL_op" is the OP that originally triggered the
1222               error, and that "PL_comppad"/"PL_curpad" points to the
1223               currently executing pad.
1224
1225                       SV*     find_uninit_var(const OP *const obase,
1226                                               const SV *const uninit_sv,
1227                                               bool match, const char **desc_p)
1228
1229       isSCRIPT_RUN
1230               Returns a bool as to whether or not the sequence of bytes from
1231               "s" up to but not including "send" form a "script run".
1232               "utf8_target" is TRUE iff the sequence starting at "s" is to be
1233               treated as UTF-8.  To be precise, except for two degenerate
1234               cases given below, this function returns TRUE iff all code
1235               points in it come from any combination of three "scripts" given
1236               by the Unicode "Script Extensions" property: Common, Inherited,
1237               and possibly one other.  Additionally all decimal digits must
1238               come from the same consecutive sequence of 10.
1239
1240               For example, if all the characters in the sequence are Greek,
1241               or Common, or Inherited, this function will return TRUE,
1242               provided any decimal digits in it are from the same block of
1243               digits in Common.  (These are the ASCII digits "0".."9" and
1244               additionally a block for full width forms of these, and several
1245               others used in mathematical notation.)   For scripts (unlike
1246               Greek) that have their own digits defined this will accept
1247               either digits from that set or from one of the Common digit
1248               sets, but not a combination of the two.  Some scripts, such as
1249               Arabic, have more than one set of digits.  All digits must come
1250               from the same set for this function to return TRUE.
1251
1252               *ret_script, if "ret_script" is not NULL, will on return of
1253               TRUE contain the script found, using the "SCX_enum" typedef.
1254               Its value will be "SCX_INVALID" if the function returns FALSE.
1255
1256               If the sequence is empty, TRUE is returned, but *ret_script (if
1257               asked for) will be "SCX_INVALID".
1258
1259               If the sequence contains a single code point which is
1260               unassigned to a character in the version of Unicode being used,
1261               the function will return TRUE, and the script will be
1262               "SCX_Unknown".  Any other combination of unassigned code points
1263               in the input sequence will result in the function treating the
1264               input as not being a script run.
1265
1266               The returned script will be "SCX_Inherited" iff all the code
1267               points in it are from the Inherited script.
1268
1269               Otherwise, the returned script will be "SCX_Common" iff all the
1270               code points in it are from the Inherited or Common scripts.
1271
1272                       bool    isSCRIPT_RUN(const U8 *s, const U8 *send,
1273                                            const bool utf8_target)
1274
1275       is_utf8_non_invariant_string
1276               Returns TRUE if "is_utf8_invariant_string" in perlapi returns
1277               FALSE for the first "len" bytes of the string "s", but they
1278               are, nonetheless, legal Perl-extended UTF-8; otherwise returns
1279               FALSE.
1280
1281               A TRUE return means that at least one code point represented by
1282               the sequence either is a wide character not representable as a
1283               single byte, or the representation differs depending on whether
1284               the sequence is encoded in UTF-8 or not.
1285
1286               See also ""is_utf8_invariant_string" in perlapi",
1287               ""is_utf8_string" in perlapi"
1288
1289                       bool    is_utf8_non_invariant_string(const U8* const s,
1290                                                            STRLEN len)
1291
1292       report_uninit
1293               Print appropriate "Use of uninitialized variable" warning.
1294
1295                       void    report_uninit(const SV *uninit_sv)
1296
1297       variant_under_utf8_count
1298               This function looks at the sequence of bytes between "s" and
1299               "e", which are assumed to be encoded in ASCII/Latin1, and
1300               returns how many of them would change should the string be
1301               translated into UTF-8.  Due to the nature of UTF-8, each of
1302               these would occupy two bytes instead of the single one in the
1303               input string.  Thus, this function returns the precise number
1304               of bytes the string would expand by when translated to UTF-8.
1305
1306               Unlike most of the other functions that have "utf8" in their
1307               name, the input to this function is NOT a UTF-8-encoded string.
1308               The function name is slightly odd to emphasize this.
1309
1310               This function is internal to Perl because khw thinks that any
1311               XS code that would want this is probably operating too close to
1312               the internals.  Presenting a valid use case could change that.
1313
1314               See also ""is_utf8_invariant_string" in perlapi" and
1315               ""is_utf8_invariant_string_loc" in perlapi",
1316
1317                       Size_t  variant_under_utf8_count(const U8* const s,
1318                                                        const U8* const e)
1319

Undocumented functions

1321       The following functions are currently undocumented.  If you use one of
1322       them, you may wish to consider creating and submitting documentation
1323       for it.
1324
1325       PerlIO_restore_errno
1326       PerlIO_save_errno
1327       PerlLIO_dup2_cloexec
1328       PerlLIO_dup_cloexec
1329       PerlLIO_open3_cloexec
1330       PerlLIO_open_cloexec
1331       PerlProc_pipe_cloexec
1332       PerlSock_accept_cloexec
1333       PerlSock_socket_cloexec
1334       PerlSock_socketpair_cloexec
1335       Slab_Alloc
1336       Slab_Free
1337       Slab_to_ro
1338       Slab_to_rw
1339       _add_range_to_invlist
1340       _byte_dump_string
1341       _get_regclass_nonbitmap_data
1342       _inverse_folds
1343       _invlistEQ
1344       _invlist_array_init
1345       _invlist_contains_cp
1346       _invlist_dump
1347       _invlist_intersection
1348       _invlist_intersection_maybe_complement_2nd
1349       _invlist_invert
1350       _invlist_len
1351       _invlist_search
1352       _invlist_subtract
1353       _invlist_union
1354       _invlist_union_maybe_complement_2nd
1355       _is_grapheme
1356       _is_in_locale_category
1357       _mem_collxfrm
1358       _new_invlist
1359       _new_invlist_C_array
1360       _setup_canned_invlist
1361       _to_fold_latin1
1362       _to_upper_title_latin1
1363       _warn_problematic_locale
1364       abort_execution
1365       add_cp_to_invlist
1366       alloc_LOGOP
1367       allocmy
1368       amagic_is_enabled
1369       append_utf8_from_native_byte
1370       apply
1371       av_extend_guts
1372       av_nonelem
1373       av_reify
1374       bind_match
1375       boot_core_PerlIO
1376       boot_core_UNIVERSAL
1377       boot_core_mro
1378       cando
1379       check_utf8_print
1380       ck_anoncode
1381       ck_backtick
1382       ck_bitop
1383       ck_cmp
1384       ck_concat
1385       ck_defined
1386       ck_delete
1387       ck_each
1388       ck_entersub_args_core
1389       ck_eof
1390       ck_eval
1391       ck_exec
1392       ck_exists
1393       ck_ftst
1394       ck_fun
1395       ck_glob
1396       ck_grep
1397       ck_index
1398       ck_join
1399       ck_length
1400       ck_lfun
1401       ck_listiob
1402       ck_match
1403       ck_method
1404       ck_null
1405       ck_open
1406       ck_prototype
1407       ck_readline
1408       ck_refassign
1409       ck_repeat
1410       ck_require
1411       ck_return
1412       ck_rfun
1413       ck_rvconst
1414       ck_sassign
1415       ck_select
1416       ck_shift
1417       ck_smartmatch
1418       ck_sort
1419       ck_spair
1420       ck_split
1421       ck_stringify
1422       ck_subr
1423       ck_substr
1424       ck_svconst
1425       ck_tell
1426       ck_trunc
1427       closest_cop
1428       compute_EXACTish
1429       coresub_op
1430       create_eval_scope
1431       croak_caller
1432       croak_no_mem
1433       croak_popstack
1434       current_re_engine
1435       custom_op_get_field
1436       cv_ckproto_len_flags
1437       cv_clone_into
1438       cv_const_sv_or_av
1439       cv_undef_flags
1440       cvgv_from_hek
1441       cvgv_set
1442       cvstash_set
1443       deb_stack_all
1444       defelem_target
1445       delete_eval_scope
1446       delimcpy_no_escape
1447       die_unwind
1448       do_aexec
1449       do_aexec5
1450       do_eof
1451       do_exec
1452       do_exec3
1453       do_ipcctl
1454       do_ipcget
1455       do_msgrcv
1456       do_msgsnd
1457       do_ncmp
1458       do_open6
1459       do_open_raw
1460       do_print
1461       do_readline
1462       do_seek
1463       do_semop
1464       do_shmio
1465       do_sysseek
1466       do_tell
1467       do_trans
1468       do_vecget
1469       do_vecset
1470       do_vop
1471       does_utf8_overflow
1472       dofile
1473       drand48_init_r
1474       drand48_r
1475       dtrace_probe_call
1476       dtrace_probe_load
1477       dtrace_probe_op
1478       dtrace_probe_phase
1479       dump_all_perl
1480       dump_packsubs_perl
1481       dump_sub_perl
1482       dump_sv_child
1483       dup_warnings
1484       emulate_cop_io
1485       feature_is_enabled
1486       find_lexical_cv
1487       find_runcv_where
1488       find_script
1489       foldEQ_latin1_s2_folded
1490       form_short_octal_warning
1491       free_tied_hv_pool
1492       get_and_check_backslash_N_name
1493       get_db_sub
1494       get_debug_opts
1495       get_hash_seed
1496       get_invlist_iter_addr
1497       get_invlist_offset_addr
1498       get_invlist_previous_index_addr
1499       get_no_modify
1500       get_opargs
1501       get_re_arg
1502       getenv_len
1503       grok_bslash_c
1504       grok_bslash_o
1505       grok_bslash_x
1506       gv_fetchmeth_internal
1507       gv_override
1508       gv_setref
1509       gv_stashpvn_internal
1510       gv_stashsvpvn_cached
1511       handle_named_backref
1512       handle_user_defined_property
1513       hfree_next_entry
1514       hv_backreferences_p
1515       hv_kill_backrefs
1516       hv_placeholders_p
1517       hv_pushkv
1518       hv_undef_flags
1519       init_argv_symbols
1520       init_constants
1521       init_dbargs
1522       init_debugger
1523       init_named_cv
1524       init_uniprops
1525       invert
1526       invlist_array
1527       invlist_clear
1528       invlist_clone
1529       invlist_highest
1530       invlist_is_iterating
1531       invlist_iterfinish
1532       invlist_iterinit
1533       invlist_max
1534       invlist_previous_index
1535       invlist_set_len
1536       invlist_set_previous_index
1537       invlist_trim
1538       io_close
1539       isFF_OVERLONG
1540       isFOO_lc
1541       is_invlist
1542       is_utf8_common
1543       is_utf8_common_with_len
1544       is_utf8_overlong_given_start_byte_ok
1545       isinfnansv
1546       jmaybe
1547       keyword
1548       keyword_plugin_standard
1549       list
1550       localize
1551       lossless_NV_to_IV
1552       magic_clear_all_env
1553       magic_cleararylen_p
1554       magic_clearenv
1555       magic_clearisa
1556       magic_clearpack
1557       magic_clearsig
1558       magic_copycallchecker
1559       magic_existspack
1560       magic_freearylen_p
1561       magic_freeovrld
1562       magic_get
1563       magic_getarylen
1564       magic_getdebugvar
1565       magic_getdefelem
1566       magic_getnkeys
1567       magic_getpack
1568       magic_getpos
1569       magic_getsig
1570       magic_getsubstr
1571       magic_gettaint
1572       magic_getuvar
1573       magic_getvec
1574       magic_killbackrefs
1575       magic_nextpack
1576       magic_regdata_cnt
1577       magic_regdatum_get
1578       magic_regdatum_set
1579       magic_scalarpack
1580       magic_set
1581       magic_set_all_env
1582       magic_setarylen
1583       magic_setcollxfrm
1584       magic_setdbline
1585       magic_setdebugvar
1586       magic_setdefelem
1587       magic_setenv
1588       magic_setisa
1589       magic_setlvref
1590       magic_setmglob
1591       magic_setnkeys
1592       magic_setnonelem
1593       magic_setpack
1594       magic_setpos
1595       magic_setregexp
1596       magic_setsig
1597       magic_setsubstr
1598       magic_settaint
1599       magic_setutf8
1600       magic_setuvar
1601       magic_setvec
1602       magic_sizepack
1603       magic_wipepack
1604       malloc_good_size
1605       malloced_size
1606       mem_collxfrm
1607       mem_log_alloc
1608       mem_log_free
1609       mem_log_realloc
1610       mg_find_mglob
1611       mode_from_discipline
1612       more_bodies
1613       mro_meta_dup
1614       mro_meta_init
1615       multiconcat_stringify
1616       multideref_stringify
1617       my_attrs
1618       my_clearenv
1619       my_lstat_flags
1620       my_memrchr
1621       my_mkostemp
1622       my_mkostemp_cloexec
1623       my_mkstemp
1624       my_mkstemp_cloexec
1625       my_stat_flags
1626       my_strerror
1627       my_unexec
1628       newGP
1629       newMETHOP_internal
1630       newSTUB
1631       newSVavdefelem
1632       newXS_deffile
1633       new_warnings_bitfield
1634       nextargv
1635       noperl_die
1636       notify_parser_that_changed_to_utf8
1637       oopsAV
1638       oopsHV
1639       op_clear
1640       op_integerize
1641       op_lvalue_flags
1642       op_refcnt_dec
1643       op_refcnt_inc
1644       op_relocate_sv
1645       op_std_init
1646       op_unscope
1647       opmethod_stash
1648       opslab_force_free
1649       opslab_free
1650       opslab_free_nopad
1651       package
1652       package_version
1653       pad_add_weakref
1654       padlist_store
1655       padname_free
1656       padnamelist_free
1657       parse_unicode_opts
1658       parse_uniprop_string
1659       parser_free
1660       parser_free_nexttoke_ops
1661       path_is_searchable
1662       peep
1663       pmruntime
1664       populate_isa
1665       ptr_hash
1666       qerror
1667       re_exec_indentf
1668       re_indentf
1669       re_op_compile
1670       re_printf
1671       reg_named_buff
1672       reg_named_buff_iter
1673       reg_numbered_buff_fetch
1674       reg_numbered_buff_length
1675       reg_numbered_buff_store
1676       reg_qr_package
1677       reg_skipcomment
1678       reg_temp_copy
1679       regcurly
1680       regprop
1681       report_evil_fh
1682       report_redefined_cv
1683       report_wrongway_fh
1684       rpeep
1685       rsignal_restore
1686       rsignal_save
1687       rxres_save
1688       same_dirent
1689       save_strlen
1690       save_to_buffer
1691       sawparens
1692       scalar
1693       scalarvoid
1694       scan_str
1695       scan_word
1696       set_caret_X
1697       set_numeric_standard
1698       set_numeric_underlying
1699       set_padlist
1700       setfd_cloexec
1701       setfd_cloexec_for_nonsysfd
1702       setfd_cloexec_or_inhexec_by_sysfdness
1703       setfd_inhexec
1704       setfd_inhexec_for_sysfd
1705       should_warn_nl
1706       sighandler
1707       skipspace_flags
1708       softref2xv
1709       ssc_add_range
1710       ssc_clear_locale
1711       ssc_cp_and
1712       ssc_intersection
1713       ssc_union
1714       sub_crush_depth
1715       sv_add_backref
1716       sv_buf_to_ro
1717       sv_del_backref
1718       sv_free2
1719       sv_kill_backrefs
1720       sv_len_utf8_nomg
1721       sv_magicext_mglob
1722       sv_mortalcopy_flags
1723       sv_only_taint_gmagic
1724       sv_or_pv_pos_u2b
1725       sv_resetpvn
1726       sv_sethek
1727       sv_setsv_cow
1728       sv_unglob
1729       swash_fetch
1730       swash_init
1731       tied_method
1732       tmps_grow_p
1733       translate_substr_offsets
1734       try_amagic_bin
1735       try_amagic_un
1736       uiv_2buf
1737       unshare_hek
1738       utf16_to_utf8
1739       utf16_to_utf8_reversed
1740       utilize
1741       varname
1742       vivify_defelem
1743       vivify_ref
1744       wait4pid
1745       was_lvalue_sub
1746       watch
1747       win32_croak_not_implemented
1748       write_to_stderr
1749       xs_boot_epilog
1750       xs_handshake
1751       yyerror
1752       yyerror_pv
1753       yyerror_pvn
1754       yylex
1755       yyparse
1756       yyquit
1757       yyunlex
1758

AUTHORS

1760       The autodocumentation system was originally added to the Perl core by
1761       Benjamin Stuhl.  Documentation is by whoever was kind enough to
1762       document their functions.
1763

SEE ALSO

1765       perlguts, perlapi
1766
1767
1768
1769perl v5.30.2                      2020-03-27                     PERLINTERN(1)
Impressum