Available only under threaded builds, this function allocates an entry in PL_stashpad for the stash passed to it.

Free an op and its children. Only use this when an op is no longer linked to from any optree.

Neutralizes an op when it is no longer needed, but is still linked to from other ops.

A general function for editing the structure of an existing chain of op_sibling nodes. By analogy with the perl-level splice() function, allows you to delete zero or more sequential nodes, replacing them with zero or more different nodes. Performs the necessary op_first/op_last housekeeping on the parent node and op_sibling manipulation on the children. The last deleted node will be marked as the last node by updating the op_sibling/op_sibparent or op_moresib field as appropriate.

Note that op_next is not manipulated, and nodes are not freed; that is the responsibility of the caller. It also won't create a new list op for an empty list etc; use higher-level functions like op_append_elem() for that.

parent is the parent node of the sibling chain. It may passed as NULL if the splicing doesn't affect the first or last op in the chain.

start is the node preceding the first node to be spliced. Node(s) following it will be deleted, and ops will be inserted after it. If it is NULL, the first node onwards is deleted, and nodes are inserted at the beginning.

del_count is the number of nodes to delete. If zero, no nodes are deleted. If -1 or greater than or equal to the number of remaining kids, all remaining kids are deleted.

insert is the first of a chain of nodes to be inserted in place of the nodes. If NULL, no nodes are inserted.

The head of the chain of deleted ops is returned, or NULL if no ops were deleted.

For example:

    action                    before      after         returns
    ------                    -----       -----         -------

                              P           P
    splice(P, A, 2, X-Y-Z)    |           |             B-C
                              A-B-C-D     A-X-Y-Z-D

                              P           P
    splice(P, NULL, 1, X-Y)   |           |             A
                              A-B-C-D     X-Y-B-C-D

                              P           P
    splice(P, NULL, 3, NULL)  |           |             A-B-C
                              A-B-C-D     D

                              P           P
    splice(P, B, 0, X-Y)      |           |             NULL
                              A-B-C-D     A-B-X-Y-C-D

For lower-level direct manipulation of op_sibparent and op_moresib, see "OpMORESIB_set", "OpLASTSIB_set", "OpMAYBESIB_set".

Returns the parent OP of o, if it has a parent. Returns NULL otherwise.

Applies a syntactic context to an op tree representing an expression. o is the op tree, and context must be G_SCALAR, G_ARRAY, or G_VOID to specify the context to apply. The modified op tree is returned.

This function applies some optimisations to the optree in top-down order. It is called before the peephole optimizer, which processes ops in execution order. Note that finalize_optree() also does a top-down scan, but is called *after* the peephole optimizer.

This function finalizes the optree. Should be called directly after the complete optree is built. It does some additional checking which can't be done in the normal ck_xxx functions and makes the tree thread-safe.

Return the next op in a depth-first traversal of the op tree, returning NULL when the traversal is complete.

The initial call must supply the root of the tree as both top and o.

For now it's static, but it may be exposed to the API in the future.

Propagate lvalue ("modifiable") context to an op and its children. type represents the context type, roughly based on the type of op that would do the modifying, although local() is represented by OP_NULL, because it has no op type of its own (it is signalled by a flag on the lvalue op).

This function detects things that can't be modified, such as $x+1, and generates errors for them. For example, $x+1 = 2 would cause it to be called with an op of type OP_ADD and a type argument of OP_SASSIGN.

It also flags things that need to behave specially in an lvalue context, such as $$x = 5 which might have to vivify a reference in $x.

Attempts to apply a list of attributes specified by the attrstr and len arguments to the subroutine identified by the cv argument which is expected to be associated with the package identified by the stashpv argument (see attributes). It gets this wrong, though, in that it does not correctly identify the boundaries of the individual attribute specifications within attrstr. This is not really intended for the public API, but has to be listed here for systems such as AIX which need an explicit export list for symbols. (It's called from XS code in support of the ATTRS: keyword from xsubpp.) Patches to fix it to respect attribute syntax properly would be welcome.

Wraps up an op tree with some additional ops so that at runtime a dynamic scope will be created. The original ops run in the new dynamic scope, and then, provided that they exit normally, the scope will be unwound. The additional ops used to create and unwind the dynamic scope will normally be an enter/leave pair, but a scope op may be used instead if the ops are simple enough to not need the full dynamic scope structure.

Handles compile-time scope entry. Arranges for hints to be restored on block exit and also handles pad sequence numbers to make lexical variables scope right. Returns a savestack index for use with block_end.

Handles compile-time scope exit. floor is the savestack index returned by block_start, and seq is the body of the block. Returns the block, possibly modified.

Register a set of hooks to be called when the Perl lexical scope changes at compile time. See "Compile-time scope hooks" in perlguts.

/* List constructors */

/* =for apidoc op_append_elem

Append an item to the list of ops contained directly within a list-type op, returning the lengthened list. first is the list-type op, and last is the op to append to the list. optype specifies the intended opcode for the list. If first is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Concatenate the lists of ops contained directly within two list-type ops, returning the combined list. first and last are the list-type ops to concatenate. optype specifies the intended opcode for the list. If either first or last is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Prepend an item to the list of ops contained directly within a list-type op, returning the lengthened list. first is the op to prepend to the list, and last is the list-type op. optype specifies the intended opcode for the list. If last is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Converts o into a list op if it is not one already, and then converts it into the specified type, calling its check function, allocating a target if it needs one, and folding constants.

A list-type op is usually constructed one kid at a time via newLISTOP, op_prepend_elem and op_append_elem. Then finally it is passed to op_convert_list to make it the right type.

Constructs, checks, and returns a new stub op, which represents an empty list expression.

Constructs, checks, and returns an op of any list type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically if required. first and last supply up to two ops to be direct children of the list op; they are consumed by this function and become part of the constructed op tree.

For most list operators, the check function expects all the kid ops to be present already, so calling newLISTOP(OP_JOIN, ...) (e.g.) is not appropriate. What you want to do in that case is create an op of type OP_LIST, append more children to it, and then call "op_convert_list". See "op_convert_list" for more information.

Constructs, checks, and returns an op of any base type (any type that has no extra fields). type is the opcode. flags gives the eight bits of op_flags, and, shifted up eight bits, the eight bits of op_private.

Constructs, checks, and returns an op of any unary type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically if required, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies an optional op to be the direct child of the unary op; it is consumed by this function and become part of the constructed op tree.

Similar to newUNOP, but creates an UNOP_AUX struct instead, with op_aux initialised to aux

Constructs, checks, and returns an op of method type with a method name evaluated at runtime. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. dynamic_meth supplies an op which evaluates method name; it is consumed by this function and become part of the constructed op tree. Supported optypes: OP_METHOD.

Constructs, checks, and returns an op of method type with a constant method name. type is the opcode. flags gives the eight bits of op_flags, and, shifted up eight bits, the eight bits of op_private. const_meth supplies a constant method name; it must be a shared COW string. Supported optypes: OP_METHOD_NAMED.

Constructs, checks, and returns an op of any binary type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required. first and last supply up to two ops to be the direct children of the binary op; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op of any pattern matching type. type is the opcode. flags gives the eight bits of op_flags and, shifted up eight bits, the eight bits of op_private.

Constructs, checks, and returns an op of any type that involves an embedded SV. type is the opcode. flags gives the eight bits of op_flags. sv gives the SV to embed in the op; this function takes ownership of one reference to it.

Constructs and returns an op to access $_.

Constructs, checks, and returns an op of any type that involves a reference to a pad element. type is the opcode. flags gives the eight bits of op_flags. A pad slot is automatically allocated, and is populated with sv; this function takes ownership of one reference to it.

This function only exists if Perl has been compiled to use ithreads.

Constructs, checks, and returns an op of any type that involves an embedded reference to a GV. type is the opcode. flags gives the eight bits of op_flags. gv identifies the GV that the op should reference; calling this function does not transfer ownership of any reference to it.

Constructs, checks, and returns an op of any type that involves an embedded C-level pointer (PV). type is the opcode. flags gives the eight bits of op_flags. pv supplies the C-level pointer. Depending on the op type, the memory referenced by pv may be freed when the op is destroyed. If the op is of a freeing type, pv must have been allocated using PerlMemShared_malloc.

Loads the module whose name is pointed to by the string part of name. Note that the actual module name, not its filename, should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if specified and not NULL, provides version semantics similar to use Foo::Bar VERSION. The optional trailing arguments can be used to specify arguments to the module's import() method, similar to use Foo::Bar VERSION LIST; their precise handling depends on the flags. The flags argument is a bitwise-ORed collection of any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags).

If PERL_LOADMOD_NOIMPORT is set, the module is loaded as if with an empty import list, as in use Foo::Bar (); this is the only circumstance in which the trailing optional arguments may be omitted entirely. Otherwise, if PERL_LOADMOD_IMPORT_OPS is set, the trailing arguments must consist of exactly one OP*, containing the op tree that produces the relevant import arguments. Otherwise, the trailing arguments must all be SV* values that will be used as import arguments; and the list must be terminated with (SV*) NULL. If neither PERL_LOADMOD_NOIMPORT nor PERL_LOADMOD_IMPORT_OPS is set, the trailing NULL pointer is needed even if no import arguments are desired. The reference count for each specified SV* argument is decremented. In addition, the name argument is modified.

If PERL_LOADMOD_DENY is set, the module is loaded as if with no rather than use.

Constructs, checks, and returns an lslice (list slice) op. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required. listval and subscript supply the parameters of the slice; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an assignment op. left and right supply the parameters of the assignment; they are consumed by this function and become part of the constructed op tree.

If optype is OP_ANDASSIGN, OP_ORASSIGN, or OP_DORASSIGN, then a suitable conditional optree is constructed. If optype is the opcode of a binary operator, such as OP_BIT_OR, then an op is constructed that performs the binary operation and assigns the result to the left argument. Either way, if optype is non-zero then flags has no effect.

If optype is zero, then a plain scalar or list assignment is constructed. Which type of assignment it is is automatically determined. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required.

Constructs a state op (COP). The state op is normally a nextstate op, but will be a dbstate op if debugging is enabled for currently-compiled code. The state op is populated from PL_curcop (or PL_compiling). If label is non-null, it supplies the name of a label to attach to the state op; this function takes ownership of the memory pointed at by label, and will free it. flags gives the eight bits of op_flags for the state op.

If o is null, the state op is returned. Otherwise the state op is combined with o into a lineseq list op, which is returned. o is consumed by this function and becomes part of the returned op tree.

Constructs, checks, and returns a logical (flow control) op. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies the expression controlling the flow, and other supplies the side (alternate) chain of ops; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns a conditional-expression (cond_expr) op. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies the expression selecting between the two branches, and trueop and falseop supply the branches; they are consumed by this function and become part of the constructed op tree.

Constructs and returns a conditional execution statement that implements the try/catch semantics. First the op tree in tryblock is executed, inside a context that traps exceptions. If an exception occurs then the optree in catchblock is executed, with the trapped exception set into the lexical variable given by catchvar (which must be an op of type OP_PADSV). All the optrees are consumed by this function and become part of the returned op tree.

The flags argument is currently ignored.

Constructs and returns a range op, with subordinate flip and flop ops. flags gives the eight bits of op_flags for the flip op and, shifted up eight bits, the eight bits of op_private for both the flip and range ops, except that the bit with value 1 is automatically set. left and right supply the expressions controlling the endpoints of the range; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op tree expressing a loop. This is only a loop in the control flow through the op tree; it does not have the heavyweight loop structure that allows exiting the loop by last and suchlike. flags gives the eight bits of op_flags for the top-level op, except that some bits will be set automatically as required. expr supplies the expression controlling loop iteration, and block supplies the body of the loop; they are consumed by this function and become part of the constructed op tree. debuggable is currently unused and should always be 1.

Constructs, checks, and returns an op tree expressing a while loop. This is a heavyweight loop, with structure that allows exiting the loop by last and suchlike.

loop is an optional preconstructed enterloop op to use in the loop; if it is null then a suitable op will be constructed automatically. expr supplies the loop's controlling expression. block supplies the main body of the loop, and cont optionally supplies a continue block that operates as a second half of the body. All of these optree inputs are consumed by this function and become part of the constructed op tree.

flags gives the eight bits of op_flags for the leaveloop op and, shifted up eight bits, the eight bits of op_private for the leaveloop op, except that (in both cases) some bits will be set automatically. debuggable is currently unused and should always be 1. has_my can be supplied as true to force the loop body to be enclosed in its own scope.

Constructs, checks, and returns an op tree expressing a foreach loop (iteration through a list of values). This is a heavyweight loop, with structure that allows exiting the loop by last and suchlike.

sv optionally supplies the variable that will be aliased to each item in turn; if null, it defaults to $_. expr supplies the list of values to iterate over. block supplies the main body of the loop, and cont optionally supplies a continue block that operates as a second half of the body. All of these optree inputs are consumed by this function and become part of the constructed op tree.

flags gives the eight bits of op_flags for the leaveloop op and, shifted up eight bits, the eight bits of op_private for the leaveloop op, except that (in both cases) some bits will be set automatically.

Constructs, checks, and returns a loop-exiting op (such as goto or last). type is the opcode. label supplies the parameter determining the target of the op; it is consumed by this function and becomes part of the constructed op tree.

Constructs, checks, and returns an op tree expressing a given block. cond supplies the expression to whose value $_ will be locally aliased, and block supplies the body of the given construct; they are consumed by this function and become part of the constructed op tree. defsv_off must be zero (it used to identity the pad slot of lexical $_).

Constructs, checks, and returns an op tree expressing a when block. cond supplies the test expression, and block supplies the block that will be executed if the test evaluates to true; they are consumed by this function and become part of the constructed op tree. cond will be interpreted DWIMically, often as a comparison against $_, and may be null to generate a default block.

If cv is a constant sub eligible for inlining, returns the constant value returned by the sub. Otherwise, returns NULL.

Constant subs can be created with newCONSTSUB or as described in "Constant Functions" in perlsub.

Construct a Perl subroutine, also performing some surrounding jobs.

This function is expected to be called in a Perl compilation context, and some aspects of the subroutine are taken from global variables associated with compilation. In particular, PL_compcv represents the subroutine that is currently being compiled. It must be non-null when this function is called, and some aspects of the subroutine being constructed are taken from it. The constructed subroutine may actually be a reuse of the PL_compcv object, but will not necessarily be so.

If block is null then the subroutine will have no body, and for the time being it will be an error to call it. This represents a forward subroutine declaration such as sub foo ($$);. If block is non-null then it provides the Perl code of the subroutine body, which will be executed when the subroutine is called. This body includes any argument unwrapping code resulting from a subroutine signature or similar. The pad use of the code must correspond to the pad attached to PL_compcv. The code is not expected to include a leavesub or leavesublv op; this function will add such an op. block is consumed by this function and will become part of the constructed subroutine.

proto specifies the subroutine's prototype, unless one is supplied as an attribute (see below). If proto is null, then the subroutine will not have a prototype. If proto is non-null, it must point to a const op whose value is a string, and the subroutine will have that string as its prototype. If a prototype is supplied as an attribute, the attribute takes precedence over proto, but in that case proto should preferably be null. In any case, proto is consumed by this function.

attrs supplies attributes to be applied the subroutine. A handful of attributes take effect by built-in means, being applied to PL_compcv immediately when seen. Other attributes are collected up and attached to the subroutine by this route. attrs may be null to supply no attributes, or point to a const op for a single attribute, or point to a list op whose children apart from the pushmark are const ops for one or more attributes. Each const op must be a string, giving the attribute name optionally followed by parenthesised arguments, in the manner in which attributes appear in Perl source. The attributes will be applied to the sub by this function. attrs is consumed by this function.

If o_is_gv is false and o is null, then the subroutine will be anonymous. If o_is_gv is false and o is non-null, then o must point to a const OP, which will be consumed by this function, and its string value supplies a name for the subroutine. The name may be qualified or unqualified, and if it is unqualified then a default stash will be selected in some manner. If o_is_gv is true, then o doesn't point to an OP at all, but is instead a cast pointer to a GV by which the subroutine will be named.

If there is already a subroutine of the specified name, then the new sub will either replace the existing one in the glob or be merged with the existing one. A warning may be generated about redefinition.

If the subroutine has one of a few special names, such as BEGIN or END, then it will be claimed by the appropriate queue for automatic running of phase-related subroutines. In this case the relevant glob will be left not containing any subroutine, even if it did contain one before. In the case of BEGIN, the subroutine will be executed and the reference to it disposed of before this function returns.

The function returns a pointer to the constructed subroutine. If the sub is anonymous then ownership of one counted reference to the subroutine is transferred to the caller. If the sub is named then the caller does not get ownership of a reference. In most such cases, where the sub has a non-phase name, the sub will be alive at the point it is returned by virtue of being contained in the glob that names it. A phase-named subroutine will usually be alive by virtue of the reference owned by the phase's automatic run queue. But a BEGIN subroutine, having already been executed, will quite likely have been destroyed already by the time this function returns, making it erroneous for the caller to make any use of the returned pointer. It is the caller's responsibility to ensure that it knows which of these situations applies.

This is the same as "newATTRSUB_x" in perlintern with its o_is_gv parameter set to FALSE. This means that if o is null, the new sub will be anonymous; otherwise the name will be derived from o in the way described (as with all other details) in "newATTRSUB_x" in perlintern.

Behaves like "newCONSTSUB_flags", except that name is nul-terminated rather than of counted length, and no flags are set. (This means that name is always interpreted as Latin-1.)

Construct a constant subroutine, also performing some surrounding jobs. A scalar constant-valued subroutine is eligible for inlining at compile-time, and in Perl code can be created by sub FOO () { 123 }. Other kinds of constant subroutine have other treatment.

The subroutine will have an empty prototype and will ignore any arguments when called. Its constant behaviour is determined by sv. If sv is null, the subroutine will yield an empty list. If sv points to a scalar, the subroutine will always yield that scalar. If sv points to an array, the subroutine will always yield a list of the elements of that array in list context, or the number of elements in the array in scalar context. This function takes ownership of one counted reference to the scalar or array, and will arrange for the object to live as long as the subroutine does. If sv points to a scalar then the inlining assumes that the value of the scalar will never change, so the caller must ensure that the scalar is not subsequently written to. If sv points to an array then no such assumption is made, so it is ostensibly safe to mutate the array or its elements, but whether this is really supported has not been determined.

The subroutine will have CvFILE set according to PL_curcop. Other aspects of the subroutine will be left in their default state. The caller is free to mutate the subroutine beyond its initial state after this function has returned.

If name is null then the subroutine will be anonymous, with its CvGV referring to an __ANON__ glob. If name is non-null then the subroutine will be named accordingly, referenced by the appropriate glob. name is a string of length len bytes giving a sigilless symbol name, in UTF-8 if flags has the SVf_UTF8 bit set and in Latin-1 otherwise. The name may be either qualified or unqualified. If the name is unqualified then it defaults to being in the stash specified by stash if that is non-null, or to PL_curstash if stash is null. The symbol is always added to the stash if necessary, with GV_ADDMULTI semantics.

flags should not have bits set other than SVf_UTF8.

If there is already a subroutine of the specified name, then the new sub will replace the existing one in the glob. A warning may be generated about the redefinition.

If the subroutine has one of a few special names, such as BEGIN or END, then it will be claimed by the appropriate queue for automatic running of phase-related subroutines. In this case the relevant glob will be left not containing any subroutine, even if it did contain one before. Execution of the subroutine will likely be a no-op, unless sv was a tied array or the caller modified the subroutine in some interesting way before it was executed. In the case of BEGIN, the treatment is buggy: the sub will be executed when only half built, and may be deleted prematurely, possibly causing a crash.

The function returns a pointer to the constructed subroutine. If the sub is anonymous then ownership of one counted reference to the subroutine is transferred to the caller. If the sub is named then the caller does not get ownership of a reference. In most such cases, where the sub has a non-phase name, the sub will be alive at the point it is returned by virtue of being contained in the glob that names it. A phase-named subroutine will usually be alive by virtue of the reference owned by the phase's automatic run queue. A BEGIN subroutine may have been destroyed already by the time this function returns, but currently bugs occur in that case before the caller gets control. It is the caller's responsibility to ensure that it knows which of these situations applies.

Used by xsubpp to hook up XSUBs as Perl subs. filename needs to be static storage, as it is used directly as CvFILE(), without a copy being made.

Construct an XS subroutine, also performing some surrounding jobs.

The subroutine will have the entry point subaddr. It will have the prototype specified by the nul-terminated string proto, or no prototype if proto is null. The prototype string is copied; the caller can mutate the supplied string afterwards. If filename is non-null, it must be a nul-terminated filename, and the subroutine will have its CvFILE set accordingly. By default CvFILE is set to point directly to the supplied string, which must be static. If flags has the XS_DYNAMIC_FILENAME bit set, then a copy of the string will be taken instead.

Other aspects of the subroutine will be left in their default state. If anything else needs to be done to the subroutine for it to function correctly, it is the caller's responsibility to do that after this function has constructed it. However, beware of the subroutine potentially being destroyed before this function returns, as described below.

If name is null then the subroutine will be anonymous, with its CvGV referring to an __ANON__ glob. If name is non-null then the subroutine will be named accordingly, referenced by the appropriate glob. name is a string of length len bytes giving a sigilless symbol name, in UTF-8 if flags has the SVf_UTF8 bit set and in Latin-1 otherwise. The name may be either qualified or unqualified, with the stash defaulting in the same manner as for gv_fetchpvn_flags. flags may contain flag bits understood by gv_fetchpvn_flags with the same meaning as they have there, such as GV_ADDWARN. The symbol is always added to the stash if necessary, with GV_ADDMULTI semantics.

If there is already a subroutine of the specified name, then the new sub will replace the existing one in the glob. A warning may be generated about the redefinition. If the old subroutine was CvCONST then the decision about whether to warn is influenced by an expectation about whether the new subroutine will become a constant of similar value. That expectation is determined by const_svp. (Note that the call to this function doesn't make the new subroutine CvCONST in any case; that is left to the caller.) If const_svp is null then it indicates that the new subroutine will not become a constant. If const_svp is non-null then it indicates that the new subroutine will become a constant, and it points to an SV* that provides the constant value that the subroutine will have.

If the subroutine has one of a few special names, such as BEGIN or END, then it will be claimed by the appropriate queue for automatic running of phase-related subroutines. In this case the relevant glob will be left not containing any subroutine, even if it did contain one before. In the case of BEGIN, the subroutine will be executed and the reference to it disposed of before this function returns, and also before its prototype is set. If a BEGIN subroutine would not be sufficiently constructed by this function to be ready for execution then the caller must prevent this happening by giving the subroutine a different name.

The function returns a pointer to the constructed subroutine. If the sub is anonymous then ownership of one counted reference to the subroutine is transferred to the caller. If the sub is named then the caller does not get ownership of a reference. In most such cases, where the sub has a non-phase name, the sub will be alive at the point it is returned by virtue of being contained in the glob that names it. A phase-named subroutine will usually be alive by virtue of the reference owned by the phase's automatic run queue. But a BEGIN subroutine, having already been executed, will quite likely have been destroyed already by the time this function returns, making it erroneous for the caller to make any use of the returned pointer. It is the caller's responsibility to ensure that it knows which of these situations applies.

Examines an op, which is expected to identify a subroutine at runtime, and attempts to determine at compile time which subroutine it identifies. This is normally used during Perl compilation to determine whether a prototype can be applied to a function call. cvop is the op being considered, normally an rv2cv op. A pointer to the identified subroutine is returned, if it could be determined statically, and a null pointer is returned if it was not possible to determine statically.

Currently, the subroutine can be identified statically if the RV that the rv2cv is to operate on is provided by a suitable gv or const op. A gv op is suitable if the GV's CV slot is populated. A const op is suitable if the constant value must be an RV pointing to a CV. Details of this process may change in future versions of Perl. If the rv2cv op has the OPpENTERSUB_AMPER flag set then no attempt is made to identify the subroutine statically: this flag is used to suppress compile-time magic on a subroutine call, forcing it to use default runtime behaviour.

If flags has the bit RV2CVOPCV_MARK_EARLY set, then the handling of a GV reference is modified. If a GV was examined and its CV slot was found to be empty, then the gv op has the OPpEARLY_CV flag set. If the op is not optimised away, and the CV slot is later populated with a subroutine having a prototype, that flag eventually triggers the warning "called too early to check prototype".

If flags has the bit RV2CVOPCV_RETURN_NAME_GV set, then instead of returning a pointer to the subroutine it returns a pointer to the GV giving the most appropriate name for the subroutine in this context. Normally this is just the CvGV of the subroutine, but for an anonymous (CvANON) subroutine that is referenced through a GV it will be the referencing GV. The resulting GV* is cast to CV* to be returned. A null pointer is returned as usual if there is no statically-determinable subroutine.

Performs the default fixup of the arguments part of an entersub op tree. This consists of applying list context to each of the argument ops. This is the standard treatment used on a call marked with &, or a method call, or a call through a subroutine reference, or any other call where the callee can't be identified at compile time, or a call where the callee has no prototype.

Performs the fixup of the arguments part of an entersub op tree based on a subroutine prototype. This makes various modifications to the argument ops, from applying context up to inserting refgen ops, and checking the number and syntactic types of arguments, as directed by the prototype. This is the standard treatment used on a subroutine call, not marked with &, where the callee can be identified at compile time and has a prototype.

protosv supplies the subroutine prototype to be applied to the call. It may be a normal defined scalar, of which the string value will be used. Alternatively, for convenience, it may be a subroutine object (a CV* that has been cast to SV*) which has a prototype. The prototype supplied, in whichever form, does not need to match the actual callee referenced by the op tree.

If the argument ops disagree with the prototype, for example by having an unacceptable number of arguments, a valid op tree is returned anyway. The error is reflected in the parser state, normally resulting in a single exception at the top level of parsing which covers all the compilation errors that occurred. In the error message, the callee is referred to by the name defined by the namegv parameter.

Performs the fixup of the arguments part of an entersub op tree either based on a subroutine prototype or using default list-context processing. This is the standard treatment used on a subroutine call, not marked with &, where the callee can be identified at compile time.

protosv supplies the subroutine prototype to be applied to the call, or indicates that there is no prototype. It may be a normal scalar, in which case if it is defined then the string value will be used as a prototype, and if it is undefined then there is no prototype. Alternatively, for convenience, it may be a subroutine object (a CV* that has been cast to SV*), of which the prototype will be used if it has one. The prototype (or lack thereof) supplied, in whichever form, does not need to match the actual callee referenced by the op tree.

If the argument ops disagree with the prototype, for example by having an unacceptable number of arguments, a valid op tree is returned anyway. The error is reflected in the parser state, normally resulting in a single exception at the top level of parsing which covers all the compilation errors that occurred. In the error message, the callee is referred to by the name defined by the namegv parameter.

Retrieves the function that will be used to fix up a call to cv. Specifically, the function is applied to an entersub op tree for a subroutine call, not marked with &, where the callee can be identified at compile time as cv.

The C-level function pointer is returned in *ckfun_p, an SV argument for it is returned in *ckobj_p, and control flags are returned in *ckflags_p. The function is intended to be called in this manner:

 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

In this call, entersubop is a pointer to the entersub op, which may be replaced by the check function, and namegv supplies the name that should be used by the check function to refer to the callee of the entersub op if it needs to emit any diagnostics. It is permitted to apply the check function in non-standard situations, such as to a call to a different subroutine or to a method call.

namegv may not actually be a GV. If the CALL_CHECKER_REQUIRE_GV bit is clear in *ckflags_p, it is permitted to pass a CV or other SV instead, anything that can be used as the first argument to "cv_name". If the CALL_CHECKER_REQUIRE_GV bit is set in *ckflags_p then the check function requires namegv to be a genuine GV.

By default, the check function is Perl_ck_entersub_args_proto_or_list, the SV parameter is cv itself, and the CALL_CHECKER_REQUIRE_GV flag is clear. This implements standard prototype processing. It can be changed, for a particular subroutine, by "cv_set_call_checker_flags".

If the CALL_CHECKER_REQUIRE_GV bit is set in gflags then it indicates that the caller only knows about the genuine GV version of namegv, and accordingly the corresponding bit will always be set in *ckflags_p, regardless of the check function's recorded requirements. If the CALL_CHECKER_REQUIRE_GV bit is clear in gflags then it indicates the caller knows about the possibility of passing something other than a GV as namegv, and accordingly the corresponding bit may be either set or clear in *ckflags_p, indicating the check function's recorded requirements.

gflags is a bitset passed into cv_get_call_checker_flags, in which only the CALL_CHECKER_REQUIRE_GV bit currently has a defined meaning (for which see above). All other bits should be clear.

The original form of "cv_get_call_checker_flags", which does not return checker flags. When using a checker function returned by this function, it is only safe to call it with a genuine GV as its namegv argument.

Sets the function that will be used to fix up a call to cv. Specifically, the function is applied to an entersub op tree for a subroutine call, not marked with &, where the callee can be identified at compile time as cv.

The C-level function pointer is supplied in ckfun, an SV argument for it is supplied in ckobj, and control flags are supplied in ckflags. The function should be defined like this:

    STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)

It is intended to be called in this manner:

    entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

In this call, entersubop is a pointer to the entersub op, which may be replaced by the check function, and namegv supplies the name that should be used by the check function to refer to the callee of the entersub op if it needs to emit any diagnostics. It is permitted to apply the check function in non-standard situations, such as to a call to a different subroutine or to a method call.

namegv may not actually be a GV. For efficiency, perl may pass a CV or other SV instead. Whatever is passed can be used as the first argument to "cv_name". You can force perl to pass a GV by including CALL_CHECKER_REQUIRE_GV in the ckflags.

ckflags is a bitset, in which only the CALL_CHECKER_REQUIRE_GV bit currently has a defined meaning (for which see above). All other bits should be clear.

The current setting for a particular CV can be retrieved by "cv_get_call_checker_flags".

The original form of "cv_set_call_checker_flags", which passes it the CALL_CHECKER_REQUIRE_GV flag for backward-compatibility. The effect of that flag setting is that the check function is guaranteed to get a genuine GV as its namegv argument.

This function assigns the prototype of the named core function to sv, or to a new mortal SV if sv is NULL. It returns the modified sv, or NULL if the core function has no prototype. code is a code as returned by keyword(). It must not be equal to 0.

These functions provide convenient and thread-safe means of manipulating hook variables.

Puts a C function into the chain of check functions for a specified op type. This is the preferred way to manipulate the "PL_check" array. opcode specifies which type of op is to be affected. new_checker is a pointer to the C function that is to be added to that opcode's check chain, and old_checker_p points to the storage location where a pointer to the next function in the chain will be stored. The value of new_checker is written into the "PL_check" array, while the value previously stored there is written to *old_checker_p.

"PL_check" is global to an entire process, and a module wishing to hook op checking may find itself invoked more than once per process, typically in different threads. To handle that situation, this function is idempotent. The location *old_checker_p must initially (once per process) contain a null pointer. A C variable of static duration (declared at file scope, typically also marked static to give it internal linkage) will be implicitly initialised appropriately, if it does not have an explicit initialiser. This function will only actually modify the check chain if it finds *old_checker_p to be null. This function is also thread safe on the small scale. It uses appropriate locking to avoid race conditions in accessing "PL_check".

When this function is called, the function referenced by new_checker must be ready to be called, except for *old_checker_p being unfilled. In a threading situation, new_checker may be called immediately, even before this function has returned. *old_checker_p will always be appropriately set before new_checker is called. If new_checker decides not to do anything special with an op that it is given (which is the usual case for most uses of op check hooking), it must chain the check function referenced by *old_checker_p.

Taken all together, XS code to hook an op checker should typically look something like this:

    static Perl_check_t nxck_frob;
    static OP *myck_frob(pTHX_ OP *op) {
        ...
        op = nxck_frob(aTHX_ op);
        ...
        return op;
    }
    BOOT:
        wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);

If you want to influence compilation of calls to a specific subroutine, then use "cv_set_call_checker_flags" rather than hooking checking of all entersub ops.

cpanm utf8

perl -MCPAN -e shell
install utf8