GV Handling and Stashes A GV is a structure which corresponds to a Perl typeglob, i.e., *foo. It is a structure that holds a pointer to a scalar, an array, a hash etc, corresponding to $foo, @foo, %foo.
GVs are usually found as values in stashes (symbol table hashes) where Perl stores its global variables.
A stash is a hash that contains all variables that are defined within a package. See "Stashes and Globs" in perlguts
Make sure there is a slot of type type in the GV gv.
These return the debugger glob for the file (compiled by Perl) whose name is given by the name parameter.
There are currently exactly two differences between these functions.
The name parameter to gv_fetchfile is a C string, meaning it is NUL-terminated; whereas the name parameter to gv_fetchfile_flags is a Perl string, whose length (in bytes) is passed in via the namelen parameter This means the name may contain embedded NUL characters. namelen doesn't exist in plain gv_fetchfile).
The other difference is that gv_fetchfile_flags has an extra flags parameter, which is currently completely ignored, but allows for possible future extensions.
If gv is a typeglob whose subroutine entry is a constant sub eligible for inlining, or gv is a placeholder reference that would be promoted to such a typeglob, then returns the value returned by the sub. Otherwise, returns NULL.
These each convert a scalar into a typeglob. This is an incoercible typeglob; assigning a reference to it will assign to one of its slots, instead of overwriting it as happens with typeglobs created by SvSetSV. Converting any scalar that is SvOK() may produce unpredictable results and is reserved for perl's internal use.
gv is the scalar to be converted.
stash is the parent stash/package, if any.
In gv_init and gv_init_pvn, name and len give the name. The name must be unqualified; that is, it must not include the package name. If gv is a stash element, it is the caller's responsibility to ensure that the name passed to this function matches the name of the element. If it does not match, perl's internal bookkeeping will get out of sync. name may contain embedded NUL characters.
gv_init_pv is identical to gv_init_pvn, but takes a NUL-terminated string for the name instead of separate char * and length parameters.
In gv_init_sv, the name is given by sv.
All but gv_init take a flags parameter. Set flags to include SVf_UTF8 if name is a UTF-8 string. In gv_init_sv, if SvUTF8(sv) is non-zero, name will be also be considered to be a UTF-8 string. It's unlikely to be a good idea to pass this particular flag to gv_init_sv, as that would potentially override the (presumaby known) state of sv.
flags can also take the GV_ADDMULTI flag, which means to pretend that the GV has been seen before (i.e., suppress "Used once" warnings).
gv_init is the old form of gv_init_pvn. It does not work with UTF-8 strings, as it has no flags parameter. Setting the multi parameter to non-zero has the same effect as setting the GV_ADDMULTI flag in the other forms.
These each look for a glob with name name, containing a defined subroutine, returning the GV of that glob if found, or NULL if not.
You probably want to use the "gv_fetchmethod" family of functions instead.
Searching is always done in the following order, with some steps skipped depending on various criteria. The first match found is used, ending the search. gv_fetchmeth_pv and gv_fetchmeth_pv_autoload lack a flags parameter, so in the following, consider flags to be zero for those two functions.
stashis searched first, unlessstasheither is NULL orGV_SUPERis set inflags.Stashes accessible via
@ISAare searched next.Searching is conducted according to
MROorder.UNIVERSAL::is searched unlessGV_NOUNIVERSALis set.Autoloaded subroutines are then looked for, but only for the forms whose names end in
_autoload, and whenstashis not NULL andGV_SUPERis not set.
The argument level should be either 0 or -1.
- If -1
-
No method caching is done.
- If 0
-
If
GV_SUPERis not set inflags, the method found is cached instash.If
GV_SUPERis set inflags, the method is cached in the super cache forstash.If the method is not found a negative cache entry is added.
Note that subroutines found in
UNIVERSAL::are not cached, though this may change.
The GV returned from these may be a method cache entry, which is not visible to Perl code. So when calling "call_sv", you should not use the GV directly; instead, you should use the method's CV, which can be obtained from the GV with the GvCV macro. For an autoloaded subroutine without a stub, GvCV() of the result may be zero.
The only other significant value for flags is SVf_UTF8, indicating that name is to be treated as being encoded in UTF-8. Since plain gv_fetchmeth and gv_fetchmeth_autoload lack a flags parameter, name is never UTF-8.
Otherwise, the functions behave identically, except as noted below.
In gv_fetchmeth_pv and gv_fetchmeth_pv_autoload, name is a C language NUL-terminated string.
In gv_fetchmeth, gv_fetchmeth_pvn, gv_fetchmeth_autoload, and gv_fetchmeth_pvn_autoload, name points to the first byte of the name, and an additional parameter, len, specifies its length in bytes. Hence, the name may contain embedded-NUL characters.
In gv_fetchmeth_sv and gv_fetchmeth_sv_autoload, *name is an SV, and the name is the PV extracted from that, using "SvPV". If the SV is marked as being in UTF-8, the extracted PV will also be. Including SVf_UTF8 in flags will force the name to be considered to be UTF-8 even if the SV is not so marked.
These each return the glob which contains the subroutine to call to invoke the method on the stash. In fact in the presence of autoloading this may be the glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is already setup.
The third parameter of gv_fetchmethod_autoload determines whether AUTOLOAD lookup is performed if the given method is not present: non-zero means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling gv_fetchmethod is equivalent to calling gv_fetchmethod_autoload with a non-zero autoload parameter.
These functions grant "SUPER" token as a prefix of the method name. Note that if you want to keep the returned glob for a long time, you need to check for it being "AUTOLOAD", since at the later time the call may load a different subroutine due to $AUTOLOAD changing its value. Use the glob created as a side effect to do this.
These functions have the same side-effects as gv_fetchmeth with level==0. The warning against passing the GV returned by gv_fetchmeth to call_sv applies equally to these functions.
These each search for an AUTOLOAD method, returning NULL if not found, or else returning a pointer to its GV, while setting the package $AUTOLOAD variable to the name (fully qualified). Also, if found and the GV's CV is an XSUB, the CV's PV will be set to the name, and its stash will be set to the stash of the GV.
Searching is done in MRO order, as specified in "gv_fetchmeth", beginning with stash if it isn't NULL.
gv_autoload4) has a method parameter; the others a flags one (both types explained below). Otherwise, the forms differ only in how the name is specified.
In gv_autoload_pv, namepv is a C language NUL-terminated string.
In gv_autoload_pvn and gv_autoload4), name points to the first byte of the name, and an additional parameter, len, specifies its length in bytes. Hence, *name may contain embedded-NUL characters.
In gv_autoload_sv, *namesv is an SV, and the name is the PV extracted from that using "SvPV". If the SV is marked as being in UTF-8, the extracted PV will also be.
The other way to indicate that the name is encoded as UTF-8 is to set the SVf_UTF8 bit in flags for the forms that have that parameter. The name is never considered to be UTF-8 in gv_autoload4.
The method parameter in gv_autoload4 is used only to indicate that the name is for a method (non-zero), or not (zero). The other forms use the GV_AUTOLOAD_ISMETHOD bit in flags to indicate this.
The only other significant value in flags currently is GV_SUPER to indicate, if set, to skip searching for the name in stash.
GV* Perl_gv_autoload_sv(pTHX_ HV *stash, SV* namesv, U32 flags) { char *namepv; STRLEN namelen; PERL_ARGS_ASSERT_GV_AUTOLOAD_SV; namepv = SvPV(namesv, namelen); if (SvUTF8(namesv)) flags |= SVf_UTF8; return gv_autoload_pvn(stash, namepv, namelen, flags); }
GV* Perl_gv_autoload_pv(pTHX_ HV *stash, const char *namepv, U32 flags) { PERL_ARGS_ASSERT_GV_AUTOLOAD_PV; return gv_autoload_pvn(stash, namepv, strlen(namepv), flags); }
GV* Perl_gv_autoload_pvn(pTHX_ HV *stash, const char *name, STRLEN len, U32 flags) { GV* gv; CV* cv; HV* varstash; GV* vargv; SV* varsv; SV *packname = NULL; U32 is_utf8 = flags & SVf_UTF8 ? SVf_UTF8 : 0;
PERL_ARGS_ASSERT_GV_AUTOLOAD_PVN;
if (len == S_autolen && memEQ(name, S_autoload, S_autolen))
return NULL;
if (stash) {
if (SvTYPE(stash) < SVt_PVHV) {
STRLEN packname_len = 0;
const char * const packname_ptr = SvPV_const(MUTABLE_SV(stash), packname_len);
packname = newSVpvn_flags(packname_ptr, packname_len,
SVs_TEMP | SvUTF8(stash));
stash = NULL;
}
else
packname = newSVhek_mortal(HvNAME_HEK(stash));
if (flags & GV_SUPER) sv_catpvs(packname, "::SUPER");
}
if (!(gv = gv_fetchmeth_pvn(stash, S_autoload, S_autolen, FALSE,
is_utf8 | (flags & GV_SUPER))))
return NULL;
cv = GvCV(gv);
if (!(CvROOT(cv) || CvXSUB(cv)))
return NULL;
/*
* Inheriting AUTOLOAD for non-methods no longer works
*/
if (
!(flags & GV_AUTOLOAD_ISMETHOD)
&& (GvCVGEN(gv) || GvSTASH(gv) != stash)
)
croak("Use of inherited AUTOLOAD for non-method %" SVf
"::%" UTF8f "() is no longer allowed",
SVfARG(packname),
UTF8fARG(is_utf8, len, name));
if (CvISXSUB(cv)) {
/* Instead of forcing the XSUB to do another lookup for $AUTOLOAD
* and split that value on the last '::', pass along the same data
* via the SvPVX field in the CV, and the stash in CvSTASH.
*
* Due to an unfortunate accident of history, the SvPVX field
* serves two purposes. It is also used for the subroutine's
* prototype. Since SvPVX has been documented as returning the sub
* name for a long time, but not as returning the prototype, we have to
* preserve the SvPVX AUTOLOAD behaviour and put the prototype
* elsewhere.
*
* We put the prototype in the same allocated buffer, but after
* the sub name. The SvPOK flag indicates the presence of a proto-
* type. The CvAUTOLOAD flag indicates the presence of a sub name.
* If both flags are on, then SvLEN is used to indicate the end of
* the prototype (artificially lower than what is actually allo-
* cated), at the risk of having to reallocate a few bytes unneces-
* sarily--but that should happen very rarely, if ever.
*
* We use SvUTF8 for both prototypes and sub names, so if one is
* UTF8, the other must be upgraded.
*/
CvSTASH_set(cv, stash);
if (SvPOK(cv)) { /* Ouch! */
SV * const tmpsv = newSVpvn_flags(name, len, is_utf8);
STRLEN ulen;
const char *proto = CvPROTO(cv);
assert(proto);
if (SvUTF8(cv))
sv_utf8_upgrade_flags_grow(tmpsv, 0, CvPROTOLEN(cv) + 2);
ulen = SvCUR(tmpsv);
SvCUR_set(tmpsv, SvCUR(tmpsv) + 1); /* include null in string */
sv_catpvn_flags(
tmpsv, proto, CvPROTOLEN(cv), SV_CATBYTES*!SvUTF8(cv)
);
SvTEMP_on(tmpsv); /* Allow theft */
sv_setsv_nomg((SV *)cv, tmpsv);
SvTEMP_off(tmpsv);
SvREFCNT_dec_NN(tmpsv);
SvLEN_set(cv, SvCUR(cv) + 1);
SvCUR_set(cv, ulen);
}
else {
sv_setpvn((SV *)cv, name, len);
SvPOK_off(cv);
if (is_utf8)
SvUTF8_on(cv);
else SvUTF8_off(cv);
}
CvAUTOLOAD_on(cv);
}
/*
* Given &FOO::AUTOLOAD, set $FOO::AUTOLOAD to desired function name.
* The subroutine's original name may not be "AUTOLOAD", so we don't
* use that, but for lack of anything better we will use the sub's
* original package to look up $AUTOLOAD.
*/
varstash = CvNAMED(cv) ? CvSTASH(cv) : GvSTASH(CvGV(cv));
vargv = *(GV**)hv_fetch(varstash, S_autoload, S_autolen, TRUE);
ENTER;
if (!isGV(vargv)) {
gv_init_pvn(vargv, varstash, S_autoload, S_autolen, 0);
#ifdef PERL_DONT_CREATE_GVSV
GvSV(vargv) = newSV_type(SVt_NULL);
#endif
}
LEAVE;
varsv = GvSVn(vargv);
SvTAINTED_off(varsv); /* previous $AUTOLOAD taint is obsolete */
/* XXX: this process is not careful to avoid extra magic gets and sets; tied $AUTOLOAD will get noise */
sv_setsv(varsv, packname);
sv_catpvs(varsv, "::");
/* Ensure SvSETMAGIC() is called if necessary. In particular, to clear
tainting if $FOO::AUTOLOAD was previously tainted, but is not now. */
sv_catpvn_flags(
varsv, name, len,
SV_SMAGIC|(is_utf8 ? SV_CATUTF8 : SV_CATBYTES)
);
if (is_utf8)
SvUTF8_on(varsv);
return gv;
}/* require_tie_mod() internal routine for requiring a module * that implements the logic of automatic ties like %! and %- * It loads the module and then calls the _tie_it subroutine * with the passed gv as an argument. * * The "gv" parameter should be the glob. * "varname" holds the 1-char name of the var, used for error messages. * "namesv" holds the module name. Its refcount will be decremented. * "flags": if flag & 1 then save the scalar before loading. * For the protection of $! to work (it is set by this routine) * the sv slot must already be magicalized. */ STATIC void S_require_tie_mod(pTHX_ GV *gv, const char varname, const char * name, STRLEN len, const U32 flags) { const SV * const target = varname == '[' ? GvSV(gv) : (SV *)GvHV(gv);
PERL_ARGS_ASSERT_REQUIRE_TIE_MOD;
/* If it is not tied */
if (!target || !SvRMAGICAL(target)
|| !mg_find(target,
varname == '[' ? PERL_MAGIC_tiedscalar : PERL_MAGIC_tied))
{
HV *stash;
GV **gvp;
dSP;
PUSHSTACKi(PERLSI_MAGIC);
ENTER;#define GET_HV_FETCH_TIE_FUNC \ ( (gvp = (GV **)hv_fetchs(stash, "_tie_it", 0)) \ && *gvp \ && ( (isGV(*gvp) && GvCV(*gvp)) \ || (SvROK(*gvp) && SvTYPE(SvRV(*gvp)) == SVt_PVCV) ) \ )
/* Load the module if it is not loaded. */
if (!(stash = gv_stashpvn(name, len, 0))
|| ! GET_HV_FETCH_TIE_FUNC)
{
SV * const module = newSVpvn(name, len);
const char type = varname == '[' ? '$' : '%';
if ( flags & 1 )
save_scalar(gv);
Perl_load_module(aTHX_ PERL_LOADMOD_NOIMPORT, module, NULL);
assert(sp == PL_stack_sp);
stash = gv_stashpvn(name, len, 0);
if (!stash)
croak("panic: Can't use %c%c because %s is not available",
type, varname, name);
else if (! GET_HV_FETCH_TIE_FUNC)
croak("panic: Can't use %c%c because %s does not define _tie_it",
type, varname, name);
}
/* Now call the tie function. It should be in *gvp. */
assert(gvp); assert(*gvp);
PUSHMARK(SP);
XPUSHs((SV *)gv);
PUTBACK;
call_sv((SV *)*gvp, G_VOID|G_DISCARD);
LEAVE;
POPSTACK;
}
}/* add a require_tie_mod_s - the _s suffix is similar to pvs type suffixes, * IOW it means we do STR_WITH_LEN() ourselves and the user should pass in * a true string WITHOUT a len. */ #define require_tie_mod_s(gv, varname, name, flags) \ S_require_tie_mod(aTHX_ gv, varname, STR_WITH_LEN(name), flags)
/* =for apidoc gv_stashpv =for apidoc_item gv_stashpvn =for apidoc_item gv_stashpvs =for apidoc_item gv_stashsv
Note gv_stashsv is strongly preferred for performance reasons.
These each return a pointer to the stash for a specified package.
In gv_stashsv, the package is specified by sv.
In gv_stashpvs, the package is specified by the literal C string enclosed in double quotes.
In the other forms, name specifies the package. In gv_stashpvn, namelen gives the length of the name in bytes, so it may include embedded NUL characters. In gv_stashpv, name ends at the first NUL character.
flags is passed to gv_fetchpvn_flags(), so if set to GV_ADD then the package will be created if it does not already exist. If the package does not exist and flags is 0 (or any other setting that does not create packages) then NULL is returned.
Flags may be one of:
GV_ADD Create and initialize the package if doesn't
already exist
GV_NOADD_NOINIT Don't create the package,
GV_ADDMG GV_ADD iff the GV is magical
GV_NOINIT GV_ADD, but don't initialize
GV_NOEXPAND Don't expand SvOK() entries to PVGV
SVf_UTF8 The name is in UTF-8The most important of which are probably GV_ADD and SVf_UTF8.
Returns a pointer to the stash for a specified package, possibly cached. Implements both "gv_stashpvn" in perlapi and "gv_stashsv" in perlapi.
Requires one of either namesv or namepv to be non-null.
If the flag GV_CACHE_ONLY is set, return the stash only if found in the cache; see "gv_stashpvn" in perlapi for details on the other flags.
Note it is strongly preferred for namesv to be non-null, for performance reasons.
These all return the GV of type sv_type whose name is given by the inputs, or NULL if no GV of that name and type could be found. See "Stashes and Globs" in perlguts.
The only differences are how the input name is specified, and if 'get' magic is normally used in getting that name.
Don't be fooled by the fact that only one form has flags in its name. They all have a flags parameter in fact, and all the flag bits have the same meanings for all
If any of the flags GV_ADD, GV_ADDMG, GV_ADDWARN, GV_ADDMULTI, or GV_NOINIT is set, a GV is created if none already exists for the input name and type. However, GV_ADDMG will only do the creation for magical GV's. For all of these flags except GV_NOINIT, "gv_init_pvn" is called after the addition. GV_ADDWARN is used when the caller expects that adding won't be necessary because the symbol should already exist; but if not, add it anyway, with a warning that it was unexpectedly absent. The GV_ADDMULTI flag means to pretend that the GV has been seen before (i.e., suppress "Used once" warnings).
The flag GV_NOADD_NOINIT causes "gv_init_pvn" not be to called if the GV existed but isn't PVGV.
If the SVf_UTF8 bit is set, the name is treated as being encoded in UTF-8; otherwise the name won't be considered to be UTF-8 in the pv-named forms, and the UTF-8ness of the underlying SVs will be used in the sv forms.
If the flag GV_NOTQUAL is set, the caller warrants that the input name is a plain symbol name, not qualified with a package, otherwise the name is checked for being a qualified one.
In gv_fetchpv, nambeg is a C string, NUL-terminated with no intermediate NULs.
In gv_fetchpvs, name is a literal C string, hence is enclosed in double quotes.
gv_fetchpvn and gv_fetchpvn_flags are identical. In these, <nambeg> is a Perl string whose byte length is given by full_len, and may contain embedded NULs.
In gv_fetchsv and gv_fetchsv_nomg, the name is extracted from the PV of the input name SV. The only difference between these two forms is that 'get' magic is normally done on name in gv_fetchsv, and always skipped with gv_fetchsv_nomg. Including GV_NO_SVGMAGIC in the flags parameter to gv_fetchsv makes it behave identically to gv_fetchsv_nomg.
Place the full package name of gv into sv. The gv_e* forms return instead the effective package name (see "HvENAME").
If prefix is non-NULL, it is considered to be a C language NUL-terminated string, and the stored name will be prefaced with it.
The other difference between the functions is that the *4 forms have an extra parameter, keepmain. If true an initial main:: in the name is kept; if false it is stripped. With the *3 forms, it is always kept.
Create a new, guaranteed to be unique, GV in the package given by the NUL-terminated C language string pack, and return a pointer to it.
For newGVgen or if flags in newGVgen_flags is 0, pack is to be considered to be encoded in Latin-1. The only other legal flags value is SVf_UTF8, which indicates pack is to be considered to be encoded in UTF-8.
Recalculates overload magic in the package given by stash.
Returns:
- 1 on success and there is some overload
- 0 if there is no overload
- -1 if some error occurred and it couldn't croak (because
destructingis true).
Implements StashHANDLER, which you should use instead
Check sv to see if the overloaded (active magic) operation method applies to it. If the sv is not SvROK or it is not an object then returns false, otherwise checks if the object is blessed into a class supporting overloaded operations, and returns true if a call to amagic_call() with this SV and the given method would trigger an amagic operation, including via the overload fallback rules or via nomethod. Thus a call like:
amagic_applies(sv, string_amg, AMG_unary)would return true for an object with overloading set up in any of the following ways:
use overload q("") => sub { ... };
use overload q(0+) => sub { ... }, fallback => 1;and could be used to tell if a given object would stringify to something other than the normal default ref stringification.
Note that the fact that this function returns TRUE does not mean you can successfully perform the operation with amagic_call(), for instance any overloaded method might throw a fatal exception, however if this function returns FALSE you can be confident that it will NOT perform the given overload operation.
method is an integer enum, one of the values found in overload.h, for instance string_amg.
flags should be set to AMG_unary for unary operations.
Perform method overloading dereferencing on ref, returning the dereferenced result. method must be one of the dereference operations given in overload.h.
If overloading is inactive on ref, returns ref itself.
Perform the overloaded (active magic) operation given by method. method is one of the values found in overload.h.
flags affects how the operation is performed, as follows:
AMGf_noleft-
leftis not to be used in this operation. AMGf_noright-
rightis not to be used in this operation. AMGf_unary-
The operation is done only on just one operand.
AMGf_assign-
The operation changes one of the operands, e.g., $x += 1
Set the name for GV gv to name which is len bytes long. Thus it may contain embedded NUL characters.
If flags contains SVf_UTF8, the name is treated as being encoded in UTF-8; otherwise not.
If the typeglob gv can be expressed more succinctly, by having something other than a real GV in its place in the stash, replace it with the optimised form. Basic requirements for this are that gv is a real typeglob, is sufficiently ordinary, and is only referenced from its package. This function is meant to be used when a GV has been looked up in part to see what was there, causing upgrading, but based on what was found it turns out that the real GV isn't required after all.
If gv is a completely empty typeglob, it is deleted from the stash.
If gv is a typeglob containing only a sufficiently-ordinary constant sub, the typeglob is replaced with a scalar-reference placeholder that more compactly represents the same thing.