The types are:

    SVt_NULL
    SVt_IV
    SVt_NV
    SVt_RV
    SVt_PV
    SVt_PVIV
    SVt_PVNV
    SVt_PVMG
    SVt_INVLIST
    SVt_REGEXP
    SVt_PVGV
    SVt_PVLV
    SVt_PVAV
    SVt_PVHV
    SVt_PVCV
    SVt_PVFM
    SVt_PVIO
    SVt_PVOBJ

These are most easily explained from the bottom up.

SVt_PVOBJ is for object instances of the new `use feature 'class'` kind. SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays.

All the others are scalar types, that is, things that can be bound to a $ variable. For these, the internal types are mostly orthogonal to types in the Perl language.

Hence, checking SvTYPE(sv) < SVt_PVAV is the best way to see whether something is a scalar.

SVt_PVGV represents a typeglob. If !SvFAKE(sv), then it is a real, incoercible typeglob. If SvFAKE(sv), then it is a scalar to which a typeglob has been assigned. Assigning to it again will stop it from being a typeglob. SVt_PVLV represents a scalar that delegates to another scalar behind the scenes. It is used, e.g., for the return value of substr and for tied hash and array elements. It can hold any scalar value, including a typeglob. SVt_REGEXP is for regular expressions. SVt_INVLIST is for Perl core internal use only.

SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression, or delegate). Since most scalars do not need all the internal fields of a PVMG, we save memory by allocating smaller structs when possible. All the other types are just simpler forms of SVt_PVMG, with fewer internal fields. SVt_NULL can only hold undef. SVt_IV can hold undef, an integer, or a reference. (SVt_RV is an alias for SVt_IV, which exists for backward compatibility.) SVt_NV can hold undef or a double. (In builds that support headless NVs, these could also hold a reference via a suitable offset, in the same way that SVt_IV does, but this is not currently supported and seems to be a rare use case.) SVt_PV can hold undef, a string, or a reference. SVt_PVIV is a superset of SVt_PV and SVt_IV. SVt_PVNV is a superset of SVt_PV and SVt_NV. SVt_PVMG can hold anything SVt_PVNV can hold, but it may also be blessed or magical.

These all increment the reference count of the given SV. The ones without void in their names return the SV.

SvREFCNT_inc is the base operation; the rest are optimizations if various input constraints are known to be true; hence, all can be replaced with SvREFCNT_inc.

SvREFCNT_inc_NN can only be used if you know sv is not NULL. Since we don't have to check the NULLness, it's faster and smaller.

SvREFCNT_inc_void can only be used if you don't need the return value. The macro doesn't need to return a meaningful value.

SvREFCNT_inc_void_NN can only be used if you both don't need the return value, and you know that sv is not NULL. The macro doesn't need to return a meaningful value, or check for NULLness, so it's smaller and faster.

SvREFCNT_inc_simple can only be used with expressions without side effects. Since we don't have to store a temporary value, it's faster.

SvREFCNT_inc_simple_NN can only be used with expressions without side effects and you know sv is not NULL. Since we don't have to store a temporary value, nor check for NULLness, it's faster and smaller.

SvREFCNT_inc_simple_void can only be used with expressions without side effects and you don't need the return value.

SvREFCNT_inc_simple_void_NN can only be used with expressions without side effects, you don't need the return value, and you know sv is not NULL.

These decrement the reference count of the given SV.

SvREFCNT_dec_NN may only be used when sv is known to not be NULL.

The function SvREFCNT_dec_ret_NULL() is identical to the SvREFCNT_dec() except it returns a NULL SV *. It is used by SvREFCNT_dec_set_NULL() which is a macro which will, when passed a non-NULL argument, decrement the reference count of its argument and then set it to NULL. You can replace code of the following form:

    if (sv) {
       SvREFCNT_dec_NN(sv);
       sv = NULL;
    }

with

    SvREFCNT_dec_set_NULL(sv);

These return a pointer to the physical string in the SV. The SV must contain a string. Prior to 5.9.3 it is not safe to execute these unless the SV's type >= SVt_PV.

These are also used to store the name of an autoloaded subroutine in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in perlguts.

SvPVXx is identical to SvPVX.

SvPVX_mutable is merely a synonym for SvPVX, but its name emphasizes that the string is modifiable by the caller.

SvPVX_const differs in that the return value has been cast so that the compiler will complain if you were to try to modify the contents of the string, (unless you cast away const yourself).

Warning: If SvCUR is equal to SvLEN, then SvEND points to unallocated memory.

Set the value of the PV pointer in sv to the Perl allocated NUL-terminated string val. See also "SvIV_set".

Remember to free the previous PV buffer. There are many things to check. Beware that the existing pointer may be involved in copy-on-write or other mischief, so do SvOOK_off(sv) and use sv_force_normal or SvPV_force (or check the SvIsCOW flag) first to make sure this modification is safe. Then finally, if it is not a COW, call "SvPV_free" to free the previous PV buffer.

If you want to take into account the bytes pragma, use "DO_UTF8" instead.

Returns the vstring magic, or NULL if none

Remove any string offset.

Returns a boolean as to whether sv has overloading (active magic) enabled or not.

Returns true if the SV is one of the special boolean constants (PL_sv_yes or PL_sv_no), or is a regular SV whose last assignment stored a copy of one.

Returns true if the SV has get magic or overloading. If either is true then the scalar is active data, and has the potential to return a new value every time it is accessed. Hence you must be careful to only read it once per user logical operation and work with that returned value. If neither is true then the scalar's value cannot change unless written to.

A quick flag check to see whether an sv should be passed to sv_force_normal to be "downgraded" before SvIVX or SvPVX can be modified directly.

For example, if your scalar is a reference and you want to modify the SvIVX slot, you can't just do SvROK_off, as that will leak the referent.

This is used internally by various sv-modifying functions, such as sv_setsv, sv_setiv and sv_pvn_force.

One case that this does not handle is a gv without SvFAKE set. After

    if (SvTHINKFIRST(gv)) sv_force_normal(gv);

it will still be a gv.

SvTHINKFIRST sometimes produces false positives. In those cases sv_force_normal does nothing.

Trim any trailing unused memory in the PV of sv, which needs to have a real PV that is unencumbered by things like COW. Think first before using this functionality. Is the space saving really worth giving up COW? Will the needed size of sv stay the same?

If the answers are both yes, then use "SV_CHECK_THINKFIRST" or "SV_CHECK_THINKFIRST_COW_DROP" before calling this.

Frees the PV buffer in sv, leaving things in a precarious state, so should only be used as part of a larger operation

These are like "SvPV", returning the string in the SV, but will force the SV into containing a string ("SvPOK"), and only a string ("SvPOK_only"), by hook or by crook. You need to use one of these force routines if you are going to update the "SvPVX" directly.

Note that coercing an arbitrary scalar into a plain PV will potentially strip useful data from it. For example if the SV was SvROK, then the referent will have its reference count decremented, and the SV itself may be converted to an SvPOK scalar with a string buffer containing a value such as "ARRAY(0x1234)".

The differences between the forms are:

The forms with flags in their names allow you to use the flags parameter to specify to perform 'get' magic (by setting the SV_GMAGIC flag) or to skip 'get' magic (by clearing it). The other forms do perform 'get' magic, except for the ones with nomg in their names, which skip 'get' magic.

The forms that take a len parameter will set that variable to the byte length of the resultant string (these are macros, so don't use &len).

The forms with nolen in their names indicate they don't have a len parameter. They should be used only when it is known that the PV is a C string, terminated by a NUL byte, and without intermediate NUL characters; or when you don't care about its length.

The forms with mutable in their names are effectively the same as those without, but the name emphasizes that the string is modifiable by the caller, which it is in all the forms.

SvPVutf8_force is like SvPV_force, but converts sv to UTF-8 first if not already UTF-8.

SvPVutf8x_force is like SvPVutf8_force, but guarantees to evaluate sv only once; use the more efficient SvPVutf8_force otherwise.

SvPVbyte_force is like SvPV_force, but converts sv to byte representation first if currently encoded as UTF-8. If the SV cannot be downgraded from UTF-8, this croaks.

SvPVbytex_force is like SvPVbyte_force, but guarantees to evaluate sv only once; use the more efficient SvPVbyte_force otherwise.

These each return a pointer to the string in sv, or a stringified form of sv if it does not contain a string. The SV may cache the stringified version becoming SvPOK.

This is a very basic and common operation, so there are lots of slightly different versions of it.

Note that there is no guarantee that the return value of SvPV(sv), for example, is equal to SvPVX(sv), or that SvPVX(sv) contains valid data, or that successive calls to SvPV(sv) (or another of these forms) will return the same pointer value each time. This is due to the way that things like overloading and Copy-On-Write are handled. In these cases, the return value may point to a temporary buffer or similar. If you absolutely need the SvPVX field to be valid (for example, if you intend to write to it), then see "SvPV_force".

The differences between the forms are:

The forms with neither byte nor utf8 in their names (e.g., SvPV or SvPV_nolen) can expose the SV's internal string buffer. If that buffer consists entirely of bytes 0-255 and includes any bytes above 127, then you MUST consult SvUTF8 to determine the actual code points the string is meant to contain. Generally speaking, it is probably safer to prefer SvPVbyte, SvPVutf8, and the like. See "How do I pass a Perl string to a C library?" in perlguts for more details.

The forms with flags in their names allow you to use the flags parameter to specify to process 'get' magic (by setting the SV_GMAGIC flag) or to skip 'get' magic (by clearing it). The other forms process 'get' magic, except for the ones with nomg in their names, which skip 'get' magic.

The forms that take a len parameter will set that variable to the byte length of the resultant string (these are macros, so don't use &len).

The forms with nolen in their names indicate they don't have a len parameter. They should be used only when it is known that the PV is a C string, terminated by a NUL byte, and without intermediate NUL characters; or when you don't care about its length.

The forms with const in their names return const char * so that the compiler will hopefully complain if you were to try to modify the contents of the string (unless you cast away const yourself).

The other forms return a mutable pointer so that the string is modifiable by the caller; this is emphasized for the ones with mutable in their names.

As of 5.38, all forms are guaranteed to evaluate sv exactly once. For earlier Perls, use a form whose name ends with x for single evaluation.

SvPVutf8 is like SvPV, but converts sv to UTF-8 first if not already UTF-8. Similarly, the other forms with utf8 in their names correspond to their respective forms without.

SvPVutf8_or_null and SvPVutf8_or_null_nomg don't have corresponding non-utf8 forms. Instead they are like SvPVutf8_nomg, but when sv is undef, they return NULL.

SvPVbyte is like SvPV, but converts sv to byte representation first if currently encoded as UTF-8. If sv cannot be downgraded from UTF-8, it croaks. Similarly, the other forms with byte in their names correspond to their respective forms without.

SvPVbyte_or_null doesn't have a corresponding non-byte form. Instead it is like SvPVbyte, but when sv is undef, it returns NULL.

These return a boolean indicating whether Perl would evaluate the SV as true or false. See "SvOK" for a defined/undefined test.

As of Perl 5.32, all are guaranteed to evaluate sv only once. Prior to that release, only SvTRUEx guaranteed single evaluation; now SvTRUEx is identical to SvTRUE.

SvTRUE_nomg and TRUE_nomg_NN do not perform 'get' magic; the others do unless the scalar is already SvPOK, SvIOK, or SvNOK (the public, not the private flags).

SvTRUE_NN is like "SvTRUE", but sv is assumed to be non-null (NN). If there is a possibility that it is NULL, use plain SvTRUE.

SvTRUE_nomg_NN is like "SvTRUE_nomg", but sv is assumed to be non-null (NN). If there is a possibility that it is NULL, use plain SvTRUE_nomg.

Call this when you are about to replace the PV value in sv, which is potentially copy-on-write. It stops any sharing with other SVs, so that no Copy on Write (COW) actually happens. This COW would be useless, as it would immediately get changed to something else. This function also removes any other encumbrances that would be problematic when changing sv.

Remove any encumbrances from sv, that need to be taken care of before it is modifiable. For example if it is Copy on Write (COW), now is the time to make that copy.

If you know that you are about to change the PV value of sv, instead use "SV_CHECK_THINKFIRST_COW_DROP" to avoid the write that would be immediately written again.

These are identical. They create an RV wrapper for an SV. The reference count for the original SV is incremented.

if dsv is the same as ssv, these do nothing. Otherwise they all call some form of "sv_setsv". They may evaluate their arguments more than once.

The only differences are:

SvSetMagicSV and SvSetMagicSV_nosteal perform any required 'set' magic afterwards on the destination SV; SvSetSV and SvSetSV_nosteal do not.

SvSetSV_nosteal SvSetMagicSV_nosteal call a non-destructive version of sv_setsv.

You might mistakenly think that len is the number of bytes to add to the existing size, but instead it is the total size sv should be.

Like SvPVCLEAR, but optimized for newly-minted SVt_PV/PVIV/PVNV/PVMG that already have a PV buffer allocated, but no SvTHINKFIRST.

Returns a true SV if b is a true value, or a false SV if b is 0.

See also "PL_sv_yes" and "PL_sv_no".

These set an SV to a true or false boolean value, upgrading first if necessary.

They differ only in that sv_setbool_mg handles 'set' magic; sv_setbool does not.

Creates a new SV and copies a string (which may contain NUL (\0) characters) into it. If utf8 is true, calls SvUTF8_on on the new SV. Implemented as a wrapper around newSVpvn_flags.

Creates a new SV containing the pad name.

Reads into len the offset from SvPVX back to the true start of the allocated buffer, which will be non-zero if sv_chop has been used to efficiently remove characters from start of the buffer. Implemented as a macro, which takes the address of len, which must be of type STRLEN. Evaluates sv more than once. Sets len to 0 if SvOOK(sv) is false.

Create a new IO, setting the reference count to 1.

cpanm less

perl -MCPAN -e shell
install less