GV Handling and Stashes A GV is a structure which corresponds to to a Perl typeglob, ie *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.

Converts 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.

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.

flags can be set to SVf_UTF8 if name is a UTF-8 string, or the return value of SvUTF8(sv). It can also take the GV_ADDMULTI flag, which means to pretend that the GV has been seen before (i.e., suppress "Used once" warnings).

The old form of gv_init_pvn(). It does not work with UTF-8 strings, as it has no flags parameter. If the multi parameter is set, the GV_ADDMULTI flag will be passed to gv_init_pvn().

Same as gv_init_pvn(), but takes a nul-terminated string for the name instead of separate char * and length parameters.

Same as gv_init_pvn(), but takes an SV * for the name instead of separate char * and length parameters. flags is currently unused.

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.

stash is always searched (first), unless it is NULL.

If stash is NULL, or was searched but nothing was found in it, and the GV_SUPER bit is set in flags, stashes accessible via @ISA are searched next. Searching is conducted according to MRO order.

Finally, if no matches were found so far, and the GV_NOUNIVERSAL flag in flags is not set, UNIVERSAL:: is searched.

The argument level should be either 0 or -1. If -1, the function will return without any side effects or caching. If 0, the function makes sure there is a glob named name in stash, creating one if necessary. The subroutine slot in the glob will be set to any subroutine found in the stash and SUPER:: search, hence caching any SUPER:: result. Note that subroutines found in UNIVERSAL:: are not cached.

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.

The only other significant value for flags is SVf_UTF8, indicating that name is to be treated as being encoded in UTF-8.

Plain gv_fetchmeth lacks a flags parameter, hence always searches in stash, then UNIVERSAL::, and name is never UTF-8. Otherwise it is exactly like gv_fetchmeth_pvn.

The other forms do have a flags parameter, and differ only in how the glob name is specified.

In gv_fetchmeth_pv, name is a C language NUL-terminated string.

In gv_fetchmeth_pvn, 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, *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.

This is the old form of "gv_fetchmeth_pvn_autoload", which has no flags parameter.

Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string in the form of an SV instead of a string/length pair.

Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-terminated string instead of a string/length pair.

Same as gv_fetchmeth_pvn(), but looks for autoloaded subroutines too. Returns a glob for the subroutine.

For an autoloaded subroutine without a GV, will create a GV even if level < 0. For an autoloaded subroutine without a stub, GvCV() of the result may be zero.

Currently, the only significant value for flags is SVf_UTF8.

Returns 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 name (fully qualified). Also, if found and the GV's CV is an XSUB, the CV's PV will be set to 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.

The forms differ only in how name is specified.

In gv_autoload_pv, namepv is a C language NUL-terminated string.

In gv_autoload_pvn, 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.

Returns a pointer to the stash for a specified package. Uses strlen to determine the length of name, then calls gv_stashpvn().

Returns a pointer to the stash for a specified package. The namelen parameter indicates the length of the name, in bytes. 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-8

The most important of which are probably GV_ADD and SVf_UTF8.

Note, use of gv_stashsv instead of gv_stashpvn where possible is strongly recommended for performance reasons.

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.

Returns a pointer to the stash for a specified package. See "gv_stashpvn".

Note this interface is strongly preferred over gv_stashpvn 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 destructing is 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 succesfully 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

left is not to be used in this operation.

AMGf_noright

right is 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.

cpanm less

perl -MCPAN -e shell
install less