In all but the most memory-paranoid configurations (ex: PURIFY), heads and bodies are allocated out of arenas, which by default are approximately 4K chunks of memory parcelled up into N heads or bodies. Sv-bodies are allocated by their sv-type, guaranteeing size consistency needed to allocate safely from arrays.

For SV-heads, the first slot in each arena is reserved, and holds a link to the next arena, some flags, and a note of the number of slots. Snaked through each arena chain is a linked list of free items; when this becomes empty, an extra arena is allocated and divided up into N items which are threaded into the free list.

SV-bodies are similar, but they use arena-sets by default, which separate the link and info from the arena itself, and reclaim the 1st slot in the arena. SV-bodies are further described later.

The following global variables are associated with arenas:

 PL_sv_arenaroot     pointer to list of SV arenas
 PL_sv_root          pointer to list of free SV structures

 PL_body_arenas      head of linked-list of body arenas
 PL_body_roots[]     array of pointers to list of free bodies of svtype
                     arrays are indexed by the svtype needed

A few special SV heads are not allocated from an arena, but are instead directly created in the interpreter structure, eg PL_sv_undef. The size of arenas can be changed from the default by setting PERL_ARENA_SIZE appropriately at compile time.

The SV arena serves the secondary purpose of allowing still-live SVs to be located and destroyed during final cleanup.

At the lowest level, the macros new_SV() and del_SV() grab and free an SV head. (If debugging with -DD, del_SV() calls the function S_del_sv() to return the SV to the free list with error checking.) new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the free list is empty. SVs in the free list have their SvTYPE field set to all ones.

At the time of very final cleanup, sv_free_arenas() is called from perl_destruct() to physically free all the arenas allocated since the start of the interpreter.

The internal function visit() scans the SV arenas list, and calls a specified function for each SV it finds which is still live, i.e. which has an SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is used by the following functions (specified as [function that calls visit()] / [function called by visit() for each SV]):

    sv_report_used() / do_report_used()
                        dump all remaining SVs (debugging aid)

    sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
                      do_clean_named_io_objs(),do_curse()
                        Attempt to free all objects pointed to by RVs,
                        try to do the same for all objects indir-
                        ectly referenced by typeglobs too, and
                        then do a final sweep, cursing any
                        objects that remain.  Called once from
                        perl_destruct(), prior to calling sv_clean_all()
                        below.

    sv_clean_all() / do_clean_all()
                        SvREFCNT_dec(sv) each remaining SV, possibly
                        triggering an sv_free(). It also sets the
                        SVf_BREAK flag on the SV to indicate that the
                        refcnt has been artificially lowered, and thus
                        stopping sv_free() from giving spurious warnings
                        about SVs which unexpectedly have a refcnt
                        of zero.  called repeatedly from perl_destruct()
                        until there are no SVs left.

Arena allocator API Summary

Private API to rest of sv.c

    new_SV(),  del_SV(),

    new_XPVNV(), del_XPVGV(),
    etc

Public API:

    sv_report_used(), sv_clean_objs(), sv_clean_all(), sv_free_arenas()

Given a chunk of memory, link it to the head of the list of arenas, and split it into a list of free SVs.

Dump the contents of all SVs not yet freed (debugging aid).

Attempt to destroy all objects not yet freed.

Decrement the refcnt of each remaining SV, possibly triggering a cleanup. This function may have to be called multiple times to free SVs which are in complex self-referential hierarchies.

Deallocate the memory used by all arenas. Note that all the individual SV heads and bodies within the arenas must already have been freed.

Upgrade an SV to a more complex form. Generally adds a new body type to the SV, then copies across as much information as possible from the old body. It croaks if the SV is already in a more complex form than requested. You generally want to use the SvUPGRADE macro wrapper, which checks the type before calling sv_upgrade, and hence does not croak. See also "svtype".

Remove any string offset. You should normally use the SvOOK_off macro wrapper instead.

Expands the character buffer in the SV. If necessary, uses sv_unref and upgrades the SV to SVt_PV. Returns a pointer to the character buffer. Use the SvGROW wrapper instead.

These copy an integer into the given SV, upgrading first if necessary.

They differ only in that sv_setiv_mg handles 'set' magic; sv_setiv does not.

These copy an unsigned integer into the given SV, upgrading first if necessary.

They differ only in that sv_setuv_mg handles 'set' magic; sv_setuv does not.

These copy a double into the given SV, upgrading first if necessary.

They differ only in that sv_setnv_mg handles 'set' magic; sv_setnv does not.

Test if the content of an SV looks like a number (or is a number). Inf and Infinity are treated as numbers (so will not issue a non-numeric warning), even if your atof() doesn't grok them. Get-magic is ignored.

Return the integer value of an SV, doing any necessary string conversion. If flags has the SV_GMAGIC bit set, does an mg_get() first. Normally used via the SvIV(sv) and SvIVx(sv) macros.

Return the unsigned integer value of an SV, doing any necessary string conversion. If flags has the SV_GMAGIC bit set, does an mg_get() first. Normally used via the SvUV(sv) and SvUVx(sv) macros.

Return the num value of an SV, doing any necessary string or integer conversion. If flags has the SV_GMAGIC bit set, does an mg_get() first. Normally used via the SvNV(sv) and SvNVx(sv) macros.

Return an SV with the numeric value of the source SV, doing any necessary reference or overload conversion. The caller is expected to have handled get-magic already.

Returns a pointer to the string value of an SV, and sets *lp to its length. If flags has the SV_GMAGIC bit set, does an mg_get() first. Coerces sv to a string if necessary. Normally invoked via the SvPV_flags macro. sv_2pv() and sv_2pv_nomg usually end up here too.

These copy a stringified representation of the source SV into the destination SV. They automatically perform coercion of numeric values into strings. Guaranteed to preserve the UTF8 flag even from overloaded objects. Similar in nature to sv_2pv[_flags] but they operate directly on an SV instead of just the string. Mostly they use "sv_2pv_flags" in perlintern to do the work, except when that would lose the UTF-8'ness of the PV.

The three forms differ only in whether or not they perform 'get magic' on sv. sv_copypv_nomg skips 'get magic'; sv_copypv performs it; and sv_copypv_flags either performs it (if the SV_GMAGIC bit is set in flags) or doesn't (if that bit is cleared).

Returns a pointer to the byte-encoded representation of the SV, and set *lp to its length. If the SV is marked as being encoded as UTF-8, it will downgrade it to a byte string as a side-effect, if possible. If the SV cannot be downgraded, this croaks.

Processes 'get' magic.

Usually accessed via the SvPVbyte macro.

Return a pointer to the UTF-8-encoded representation of the SV, and set *lp to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.

Usually accessed via the SvPVutf8 macro.

This macro is only used by sv_true() or its macro equivalent, and only if the latter's argument is neither SvPOK, SvIOK nor SvNOK. It calls sv_2bool_flags with the SV_GMAGIC flag.

This function is only used by sv_true() and friends, and only if the latter's argument is neither SvPOK, SvIOK nor SvNOK. If the flags contain SV_GMAGIC, then it does an mg_get() first.

These convert the PV of an SV to its UTF-8-encoded form. The SV is forced to string form if it is not already. They always set the SvUTF8 flag to avoid future validity checks even if the whole string is the same in UTF-8 as not. They return the number of bytes in the converted string

The forms differ in just two ways. The main difference is whether or not they perform 'get magic' on sv. sv_utf8_upgrade_nomg skips 'get magic'; sv_utf8_upgrade performs it; and sv_utf8_upgrade_flags and sv_utf8_upgrade_flags_grow either perform it (if the SV_GMAGIC bit is set in flags) or don't (if that bit is cleared).

The other difference is that sv_utf8_upgrade_flags_grow has an additional parameter, extra, which allows the caller to specify an amount of space to be reserved as spare beyond what is needed for the actual conversion. This is used when the caller knows it will soon be needing yet more space, and it is more efficient to request space from the system in a single call. This form is otherwise identical to sv_utf8_upgrade_flags.

These are not a general purpose byte encoding to Unicode interface: use the Encode extension for that.

The SV_FORCE_UTF8_UPGRADE flag is now ignored.

These attempt to convert the PV of an SV from characters to bytes. If the PV contains a character that cannot fit in a byte, this conversion will fail; in this case, FALSE is returned if fail_ok is true; otherwise they croak.

They are not a general purpose Unicode to byte encoding interface: use the Encode extension for that.

They differ only in that:

sv_utf8_downgrade processes 'get' magic on sv.

sv_utf8_downgrade_nomg does not.

sv_utf8_downgrade_flags has an additional flags parameter in which you can specify SV_GMAGIC to process 'get' magic, or leave it cleared to not proccess 'get' magic.

Converts the PV of an SV to UTF-8, but then turns the SvUTF8 flag off so that it looks like octets again.

If the PV of the SV is an octet sequence in Perl's extended UTF-8 and contains a multiple-byte character, the SvUTF8 flag is turned on so that it looks like a character. If the PV contains only single-byte characters, the SvUTF8 flag stays off. Scans PV for validity and returns FALSE if the PV is invalid UTF-8.

These copy the contents of the source SV ssv into the destination SV dsv. ssv may be destroyed if it is mortal, so don't use these functions if the source SV needs to be reused. Loosely speaking, they perform a copy-by-value, obliterating any previous content of the destination.

They differ only in that:

sv_setsv calls 'get' magic on ssv, but skips 'set' magic on dsv.

sv_setsv_mg calls both 'get' magic on ssv and 'set' magic on dsv.

sv_setsv_nomg skips all magic.

sv_setsv_flags has a flags parameter which you can use to specify any combination of magic handling, and also you can specify SV_NOSTEAL so that the buffers of temps will not be stolen.

You probably want to instead use one of the assortment of wrappers, such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and "SvSetMagicSV_nosteal".

sv_setsv_flags is the primary function for copying scalars, and most other copy-ish functions and macros use it underneath.

Equivalent to sv_setsv(sv, &PL_sv_undef), but more efficient. Doesn't handle set magic.

The perl equivalent is $sv = undef;. Note that it doesn't free any string buffer, unlike undef $sv.

Introduced in perl 5.25.12.

Sets the SV to be a string of cur bytes length, with at least len bytes available. Ensures that there is a null byte at SvEND. Returns a char * pointer to the SvPV buffer.

These copy a string (possibly containing embedded NUL characters) into an SV. The len parameter indicates the number of bytes to be copied. If the ptr argument is NULL the SV will become undefined.

The UTF-8 flag is not changed by these functions. A terminating NUL byte is guaranteed.

They differ only in that:

sv_setpvn does not handle 'set' magic; sv_setpvn_mg does.

These copy a string into an SV. The string must be terminated with a NUL character, and not contain embeded NUL's.

They differ only in that:

sv_setpv does not handle 'set' magic; sv_setpv_mg does.

Tells an SV to use ptr to find its string value. Normally the string is stored inside the SV, but sv_usepvn allows the SV to use an outside string. ptr should point to memory that was allocated by Newx. It must be the start of a Newx-ed block of memory, and not a pointer to the middle of it (beware of OOK and copy-on-write), and not be from a non-Newx memory allocator like malloc. The string length, len, must be supplied. By default this function will Renew (i.e. realloc, move) the memory pointed to by ptr, so that pointer should not be freed or used by the programmer after giving it to sv_usepvn, and neither should any pointers from "behind" that pointer (e.g. ptr + 1) be used.

If flags & SV_SMAGIC is true, will call SvSETMAGIC. If flags & SV_HAS_TRAILING_NUL is true, then ptr[len] must be NUL, and the realloc will be skipped (i.e. the buffer is actually at least 1 byte longer than len, and already meets the requirements for storing in SvPVX).

Undo various types of fakery on an SV, where fakery means "more than" a string: if the PV is a shared string, make a private copy; if we're a ref, stop refing; if we're a glob, downgrade to an xpvmg; if we're a copy-on-write scalar, this is the on-write time when we do the copy, and is also used locally; if this is a vstring, drop the vstring magic. If SV_COW_DROP_PV is set then a copy-on-write scalar drops its PV buffer (if any) and becomes SvPOK_off rather than making a copy. (Used where this scalar is about to be set to some other value.) In addition, the flags parameter gets passed to sv_unref_flags() when unreffing. sv_force_normal calls this function with flags set to 0.

This function is expected to be used to signal to perl that this SV is about to be written to, and any extra book-keeping needs to be taken care of. Hence, it croaks on read-only values.

Efficient removal of characters from the beginning of the string buffer. SvPOK(sv), or at least SvPOKp(sv), must be true and ptr must be a pointer to somewhere inside the string buffer. ptr becomes the first character of the adjusted string. Uses the OOK hack. On return, only SvPOK(sv) and SvPOKp(sv) among the OK flags will be true.

Beware: after this function returns, ptr and SvPVX_const(sv) may no longer refer to the same chunk of data.

The unfortunate similarity of this function's name to that of Perl's chop operator is strictly coincidental. This function works from the left; chop works from the right.

These concatenate the len bytes of the string beginning at ptr onto the end of the string which is in dsv. The caller must make sure ptr contains at least len bytes.

For all but sv_catpvn_flags, the string appended is assumed to be valid UTF-8 if the SV has the UTF-8 status set, and a string of bytes otherwise.

They differ in that:

sv_catpvn_mg performs both 'get' and 'set' magic on dsv.

sv_catpvn performs only 'get' magic.

sv_catpvn_nomg skips all magic.

sv_catpvn_flags has an extra flags parameter which allows you to specify any combination of magic handling (using SV_GMAGIC and/or SV_SMAGIC) and to also override the UTF-8 handling. By supplying the SV_CATBYTES flag, the appended string is interpreted as plain bytes; by supplying instead the SV_CATUTF8 flag, it will be interpreted as UTF-8, and the dsv will be upgraded to UTF-8 if necessary.

sv_catpvn, sv_catpvn_mg, and sv_catpvn_nomg are implemented in terms of sv_catpvn_flags.

These concatenate the string from SV sstr onto the end of the string in SV dsv. If sstr is null, these are no-ops; otherwise only dsv is modified.

They differ only in what magic they perform:

sv_catsv_mg performs 'get' magic on both SVs before the copy, and 'set' magic on dsv afterwards.

sv_catsv performs just 'get' magic, on both SVs.

sv_catsv_nomg skips all magic.

sv_catsv_flags has an extra flags parameter which allows you to use SV_GMAGIC and/or SV_SMAGIC to specify any combination of magic handling (although either both or neither SV will have 'get' magic applied to it.)

sv_catsv, sv_catsv_mg, and sv_catsv_nomg are implemented in terms of sv_catsv_flags.

These concatenate the NUL-terminated string sstr onto the end of the string which is in the SV. If the SV has the UTF-8 status set, then the bytes appended should be valid UTF-8.

They differ only in how they handle magic:

sv_catpv_mg performs both 'get' and 'set' magic.

sv_catpv performs only 'get' magic.

sv_catpv_nomg skips all magic.

sv_catpv_flags has an extra flags parameter which allows you to specify any combination of magic handling (using SV_GMAGIC and/or SV_SMAGIC), and to also override the UTF-8 handling. By supplying the SV_CATUTF8 flag, the appended string is forced to be interpreted as UTF-8; by supplying instead the SV_CATBYTES flag, it will be interpreted as just bytes. Either the SV or the string appended will be upgraded to UTF-8 if necessary.

Creates a new SV. A non-zero len parameter indicates the number of bytes of preallocated string space the SV should have. An extra byte for a trailing NUL is also reserved. (SvPOK is not set for the SV even if string space is allocated.) The reference count for the new SV is set to 1.

In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first parameter, x, a debug aid which allowed callers to identify themselves. This aid has been superseded by a new build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The older API is still there for use in XS modules supporting older perls.

Adds magic to an SV, upgrading it if necessary. Applies the supplied vtable and returns a pointer to the magic added.

Note that sv_magicext will allow things that sv_magic will not. In particular, you can add magic to SvREADONLY SVs, and add more than one instance of the same how.

If namlen is greater than zero then a savepvn copy of name is stored, if namlen is zero then name is stored as-is and - as another special case - if (name && namlen == HEf_SVKEY) then name is assumed to contain an SV* and is stored as-is with its REFCNT incremented.

(This is now used as a subroutine by sv_magic.)

Adds magic to an SV. First upgrades sv to type SVt_PVMG if necessary, then adds a new magic item of type how to the head of the magic list.

See "sv_magicext" (which sv_magic now calls) for a description of the handling of the name and namlen arguments.

You need to use sv_magicext to add magic to SvREADONLY SVs and also to add more than one instance of the same how.

Removes all magic of type type from an SV.

Removes all magic of type type with the specified vtbl from an SV.

Weaken a reference: set the SvWEAKREF flag on this RV; give the referred-to SV PERL_MAGIC_backref magic if it hasn't already; and push a back-reference to this RV onto the array of backreferences associated with that magic. If the RV is magical, set magic will be called after the RV is cleared. Silently ignores undef and warns on already-weak references.

Unweaken a reference: Clear the SvWEAKREF flag on this RV; remove the backreference to this RV from the array of backreferences associated with the target SV, increment the refcount of the target. Silently ignores undef and warns on non-weak references.

If sv is the target of a weak reference then it returns the back references structure associated with the sv; otherwise return NULL.

When returning a non-null result the type of the return is relevant. If it is an AV then the elements of the AV are the weak reference RVs which point at this item. If it is any other type then the item itself is the weak reference.

See also Perl_sv_add_backref(), Perl_sv_del_backref(), Perl_sv_kill_backrefs()

Inserts and/or replaces a string at the specified offset/length within the SV. Similar to the Perl substr() function, with littlelen bytes starting at little replacing len bytes of the string in bigstr starting at offset. Handles get magic.

Same as sv_insert, but the extra flags are passed to the SvPV_force_flags that applies to bigstr.

Make the first argument a copy of the second, then delete the original. The target SV physically takes over ownership of the body of the source SV and inherits its flags; however, the target keeps any magic it owns, and any magic in the source is discarded. Note that this is a rather specialist SV copying operation; most of the time you'll want to use sv_setsv or one of its many macro front-ends.

Clear an SV: call any destructors, free up any memory used by the body, and free the body itself. The SV's head is not freed, although its type is set to all 1's so that it won't inadvertently be assumed to be live during global destruction etc. This function should only be called when REFCNT is zero. Most of the time you'll want to call sv_free() (or its macro wrapper SvREFCNT_dec) instead.

Increment an SV's reference count. Use the SvREFCNT_inc() wrapper instead.

Decrement an SV's reference count, and if it drops to zero, call sv_clear to invoke destructors and free up any memory used by the body; finally, deallocating the SV's head itself. Normally called via a wrapper macro SvREFCNT_dec.

Returns the length of the string in the SV. Handles magic and type coercion and sets the UTF8 flag appropriately. See also "SvCUR", which gives raw access to the xpv_cur slot.

Returns the number of characters in the string in an SV, counting wide UTF-8 bytes as a single character. Handles magic and type coercion.

Converts the offset from a count of UTF-8 chars from the start of the string, to a count of the equivalent number of bytes; if lenp is non-zero, it does the same to lenp, but this time starting from offset, rather than from the start of the string. Handles type coercion. flags is passed to SvPV_flags, and usually should be SV_GMAGIC|SV_CONST_RETURN to handle magic.

Converts the value pointed to by offsetp from a count of UTF-8 chars from the start of the string, to a count of the equivalent number of bytes; if lenp is non-zero, it does the same to lenp, but this time starting from the offset, rather than from the start of the string. Handles magic and type coercion.

Use sv_pos_u2b_flags in preference, which correctly handles strings longer than 2Gb.

Converts offset from a count of bytes from the start of the string, to a count of the equivalent number of UTF-8 chars. Handles type coercion. flags is passed to SvPV_flags, and usually should be SV_GMAGIC|SV_CONST_RETURN to handle magic.

Converts the value pointed to by offsetp from a count of bytes from the start of the string, to a count of the equivalent number of UTF-8 chars. Handles magic and type coercion.

Use sv_pos_b2u_flags in preference, which correctly handles strings longer than 2Gb.

Returns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary.

Returns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8 and 'use bytes' aware and coerces its args to strings if necessary. If the flags has the SV_GMAGIC bit set, it handles get-magic, too.

Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in sv1 is less than, equal to, or greater than the string in sv2. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary. See also "sv_cmp_locale".

Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in sv1 is less than, equal to, or greater than the string in sv2. Is UTF-8 and 'use bytes' aware and will coerce its args to strings if necessary. If the flags has the SV_GMAGIC bit set, it handles get magic. See also "sv_cmp_locale_flags".

Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary. See also "sv_cmp".

Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes' aware and will coerce its args to strings if necessary. If the flags contain SV_GMAGIC, it handles get magic. See also "sv_cmp_flags".

This calls sv_collxfrm_flags with the SV_GMAGIC flag. See "sv_collxfrm_flags".

Add Collate Transform magic to an SV if it doesn't already have it. If the flags contain SV_GMAGIC, it handles get-magic.

Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the scalar data of the variable, but transformed to such a format that a normal memory comparison can be used to compare the data according to the locale settings.

Get a line from the filehandle and store it into the SV, optionally appending to the currently-stored string. If append is not 0, the line is appended to the SV instead of overwriting it. append should be set to the byte offset that the appended string should start at in the SV (typically, SvCUR(sv) is a suitable choice).

These auto-increment the value in the SV, doing string to numeric conversion if necessary. They both handle operator overloading.

They differ only in that sv_inc performs 'get' magic; sv_inc_nomg skips any magic.

These auto-decrement the value in the SV, doing string to numeric conversion if necessary. They both handle operator overloading.

They differ only in that:

sv_dec handles 'get' magic; sv_dec_nomg skips 'get' magic.

Creates a new SV which is a copy of the original SV (using sv_setsv). The new SV is marked as mortal. It will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. See also "sv_newmortal" and "sv_2mortal".

Like sv_mortalcopy, but the extra flags are passed to the sv_setsv_flags.

Creates a new null SV which is mortal. The reference count of the SV is set to 1. It will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. See also "sv_mortalcopy" and "sv_2mortal".

Creates a new SV and copies a string (which may contain NUL (\0) characters) into it. The reference count for the SV is set to 1. Note that if len is zero, Perl will create a zero length string. You are responsible for ensuring that the source string is at least len bytes long. If the s argument is NULL the new SV will be undefined. Currently the only flag bits accepted are SVf_UTF8 and SVs_TEMP. If SVs_TEMP is set, then sv_2mortal() is called on the result before returning. If SVf_UTF8 is set, s is considered to be in UTF-8 and the SVf_UTF8 flag will be set on the new SV. newSVpvn_utf8() is a convenience wrapper for this function, defined as

    #define newSVpvn_utf8(s, len, u)                    \
        newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)

Marks an existing SV as mortal. The SV will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. SvTEMP() is turned on which means that the SV's string buffer can be "stolen" if this SV is copied. See also "sv_newmortal" and "sv_mortalcopy".

Creates a new SV and copies a string (which may contain NUL (\0) characters) into it. The reference count for the SV is set to 1. If len is zero, Perl will compute the length using strlen(), (which means if you use this option, that s can't have embedded NUL characters and has to have a terminating NUL byte).

This function can cause reliability issues if you are likely to pass in empty strings that are not null terminated, because it will run strlen on the string and potentially run past valid memory.

Using "newSVpvn" is a safer alternative for non NUL terminated strings. For string literals use "newSVpvs" instead. This function will work fine for NUL terminated strings, but if you want to avoid the if statement on whether to call strlen use newSVpvn instead (calling strlen yourself).

Creates a new SV and copies a string into it, which may contain NUL characters (\0) and other binary data. The reference count for the SV is set to 1. Note that if len is zero, Perl will create a zero length (Perl) string. You are responsible for ensuring that the source buffer is at least len bytes long. If the buffer argument is NULL the new SV will be undefined.

Creates a new SV from the hash key structure. It will generate scalars that point to the shared string table where possible. Returns a new (undefined) SV if hek is NULL.

Creates a new SV with its SvPVX_const pointing to a shared string in the string table. If the string does not already exist in the table, it is created first. Turns on the SvIsCOW flag (or READONLY and FAKE in 5.16 and earlier). If the hash parameter is non-zero, that value is used; otherwise the hash is computed. The string's hash can later be retrieved from the SV with the "SvSHARED_HASH" macro. The idea here is that as the string table is used for shared hash keys these strings will have SvPVX_const == HeKEY and hash lookup will avoid string compare.

Like newSVpvn_share, but takes a NUL-terminated string instead of a string/length pair.

Creates a new SV and initializes it with the string formatted like sv_catpvf.

Creates a new SV and copies a floating point value into it. The reference count for the SV is set to 1.

Creates a new SV and copies an integer into it. The reference count for the SV is set to 1.

Creates a new SV and copies an unsigned integer into it. The reference count for the SV is set to 1.

Creates a new SV, of the type specified. The reference count for the new SV is set to 1.

Creates an RV wrapper for an SV. The reference count for the original SV is not incremented.

These create a new SV which is an exact duplicate of the original SV (using sv_setsv.)

They differ only in that newSVsv performs 'get' magic; newSVsv_nomg skips any magic; and newSVsv_flags allows you to explicitly set a flags parameter.

Underlying implementation for the reset Perl function. Note that the perl-level function is vaguely deprecated.

Using various gambits, try to get an IO from an SV: the IO slot if its a GV; or the recursive result if we're an RV; or the IO slot of the symbol named after the PV if we're a string.

'Get' magic is ignored on the sv passed in, but will be called on SvRV(sv) if sv is an RV.

Using various gambits, try to get a CV from an SV; in addition, try if possible to set *st and *gvp to the stash and GV associated with it. The flags in lref are passed to gv_fetchsv.

Returns true if the SV has a true value by Perl's rules. Use the SvTRUE macro instead, which may call sv_true() or may instead use an in-line version.

Get a sensible string out of the SV somehow. A private implementation of the SvPV_force macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

Get a sensible string out of the SV somehow. If flags has the SV_GMAGIC bit set, will "mg_get" on sv if appropriate, else not. sv_pvn_force and sv_pvn_force_nomg are implemented in terms of this function. You normally want to use the various wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg".

The backend for the SvPVbytex_force macro. Always use the macro instead. If the SV cannot be downgraded from UTF-8, this croaks.

The backend for the SvPVutf8x_force macro. Always use the macro instead.

Returns a string describing what the SV is a reference to.

If ob is true and the SV is blessed, the string is the class name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.

Returns a SV describing what the SV passed in is a reference to.

dst can be a SV to be set to the description or NULL, in which case a mortal SV is returned.

If ob is true and the SV is blessed, the description is the class name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.

Returns a boolean indicating whether the SV is an RV pointing to a blessed object. If the SV is not an RV, or if the object is not blessed, then this will return false.

Returns a boolean indicating whether the SV is blessed into the specified class.

This does not check for subtypes or method overloading. Use sv_isa_sv to verify an inheritance relationship in the same way as the isa operator by respecting any isa() method overloading; or sv_derived_from_sv to test directly on the actual object type.

Creates a new SV for the existing RV, rv, to point to. If rv is not an RV then it will be upgraded to one. If classname is non-null then the new SV will be blessed in the specified package. The new SV is returned and its reference count is 1. The reference count 1 is owned by rv. See also newRV_inc() and newRV_noinc() for creating a new RV properly.

Copies a pointer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. If the pv argument is NULL, then PL_sv_undef will be placed into the SV. The classname argument indicates the package for the blessing. Set classname to NULL to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Do not use with other Perl types such as HV, AV, SV, CV, because those objects will become corrupted by the pointer copy process.

Note that sv_setref_pvn copies the string while this copies the pointer.

Copies an integer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to NULL to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Copies an unsigned integer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to NULL to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Copies a double into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to NULL to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Copies a string into a new SV, optionally blessing the SV. The length of the string must be specified with n. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to NULL to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Note that sv_setref_pv copies the pointer while this copies the string.

Blesses an SV into a specified package. The SV must be an RV. The package must be designated by its stash (see "gv_stashpv"). The reference count of the SV is unaffected.

Unsets the RV status of the SV, and decrements the reference count of whatever was being referenced by the RV. This can almost be thought of as a reversal of newSVrv. The cflags argument can contain SV_IMMEDIATE_UNREF to force the reference count to be decremented (otherwise the decrementing is conditional on the reference count being different from one or the reference being a readonly SV). See "SvROK_off".

Untaint an SV. Use SvTAINTED_off instead.

Test an SV for taintedness. Use SvTAINTED instead.

These copy an integer into the given SV, also updating its string value.

They differ only in that sv_setpviv_mg performs 'set' magic; sv_setpviv skips any magic.

These work like "sv_catpvf" but copy the text into the SV instead of appending it.

The differences between these are:

sv_setpvf and sv_setpvf_nocontext do not handle 'set' magic; sv_setpvf_mg and sv_setpvf_mg_nocontext do.

sv_setpvf_nocontext and sv_setpvf_mg_nocontext do not take a thread context (aTHX) parameter, so are used in situations where the caller doesn't already have the thread context.

These work like "sv_vcatpvf" but copy the text into the SV instead of appending it.

They differ only in that sv_vsetpvf_mg performs 'set' magic; sv_vsetpvf skips all magic.

They are usually used via their frontends, "sv_setpvf" and "sv_setpvf_mg".

These process their arguments like sprintf, and append the formatted output to an SV. As with sv_vcatpvfn, argument reordering is not supporte when called with a non-null C-style variable argument list.

If the appended data contains "wide" characters (including, but not limited to, SVs with a UTF-8 PV formatted with %s, and characters >255 formatted with %c), the original SV might get upgraded to UTF-8.

If the original SV was UTF-8, the pattern should be valid UTF-8; if the original SV was bytes, the pattern should be too.

All perform 'get' magic, but only sv_catpvf_mg and sv_catpvf_mg_nocontext perform 'set' magic.

sv_catpvf_nocontext and sv_catpvf_mg_nocontext do not take a thread context (aTHX) parameter, so are used in situations where the caller doesn't already have the thread context.

These process their arguments like sv_vcatpvfn called with a non-null C-style variable argument list, and append the formatted output to sv.

They differ only in that sv_vcatpvf_mg performs 'set' magic; sv_vcatpvf skips 'set' magic.

Both perform 'get' magic.

They are usually accessed via their frontends "sv_catpvf" and "sv_catpvf_mg".

Works like sv_vcatpvfn but copies the text into the SV instead of appending it.

Usually used via one of its frontends sv_vsetpvf and sv_vsetpvf_mg.

These process their arguments like vsprintf(3) and append the formatted output to an SV. They use an array of SVs if the C-style variable argument list is missing (NULL). Argument reordering (using format specifiers like %2$d or %*2$d) is supported only when using an array of SVs; using a C-style va_list argument list with a format string that uses argument reordering will yield an exception.

When running with taint checks enabled, they indicate via maybe_tainted if results are untrustworthy (often due to the use of locales).

They assume that pat has the same utf8-ness as sv. It's the caller's responsibility to ensure that this is so.

They differ in that sv_vcatpvfn_flags has a flags parameter in which you can set or clear the SV_GMAGIC and/or SV_SMAGIC flags, to specify which magic to handle or not handle; whereas plain sv_vcatpvfn always specifies both 'get' and 'set' magic.

They are usually used via one of the frontends sv_vcatpvf and sv_vcatpvf_mg.

Create and return a new interpreter by cloning the current one.

perl_clone takes these flags as parameters:

CLONEf_COPY_STACKS - is used to, well, copy the stacks also, without it we only clone the data and zero the stacks, with it we copy the stacks and the new perl interpreter is ready to run at the exact same point as the previous one. The pseudo-fork code uses COPY_STACKS while the threads->create doesn't.

CLONEf_KEEP_PTR_TABLE - perl_clone keeps a ptr_table with the pointer of the old variable as a key and the new variable as a value, this allows it to check if something has been cloned and not clone it again, but rather just use the value and increase the refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill the ptr_table using the function ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;. A reason to keep it around is if you want to dup some of your own variables which are outside the graph that perl scans.

CLONEf_CLONE_HOST - This is a win32 thing, it is ignored on unix, it tells perl's win32host code (which is c++) to clone itself, this is needed on win32 if you want to run two threads at the same time, if you just want to do some stuff in a separate perl interpreter and then throw it away and return to the original one, you don't need to do anything.

encoding is assumed to be an Encode object, on entry the PV of sv is assumed to be octets in that encoding, and sv will be converted into Unicode (and UTF-8).

If sv already is UTF-8 (or if it is not POK), or if encoding is not a reference, nothing is done to sv. If encoding is not an Encode::XS Encoding object, bad things will happen. (See cpan/Encode/encoding.pm and Encode.)

The PV of sv is returned.

encoding is assumed to be an Encode object, the PV of ssv is assumed to be octets in that encoding and decoding the input starts from the position which (PV + *offset) pointed to. dsv will be concatenated with the decoded UTF-8 string from ssv. Decoding will terminate when the string tstr appears in decoding output or the input ends on the PV of ssv. The value which offset points will be modified to the last input position on ssv.

Returns TRUE if the terminator was found, else returns FALSE.

Find the name of the undefined variable (if any) that caused the operator to issue a "Use of uninitialized value" warning. If match is true, only return a name if its value matches uninit_sv. So roughly speaking, if a unary operator (such as OP_COS) generates a warning, then following the direct child of the op may yield an OP_PADSV or OP_GV that gives the name of the undefined variable. On the other hand, with OP_ADD there are two branches to follow, so we only print the variable name if we get an exact match. desc_p points to a string pointer holding the description of the op. This may be updated if needed.

The name is returned as a mortal SV.

Assumes that PL_op is the OP that originally triggered the error, and that PL_comppad/PL_curpad points to the currently executing pad.

Print appropriate "Use of uninitialized variable" warning.

cpanm utf8

perl -MCPAN -e shell
install utf8