+-*- buffer-read-only: t -*-
+
+!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+This file is built by autodoc.pl extracting documentation from the C source
+files.
+
=head1 NAME
perlapi - autogenerated documentation for the perl public API
=for hackers
Found in file av.c
+=item av_create_and_push
+X<av_create_and_push>
+
+Push an SV onto the end of the array, creating the array if necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ void av_create_and_push(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
+=item av_create_and_unshift_one
+X<av_create_and_unshift_one>
+
+Unshifts an SV onto the beginning of the array, creating the array if
+necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ SV** av_create_and_unshift_one(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
=item av_delete
X<av_delete>
=item av_fill
X<av_fill>
-Ensure than an array has a given number of elements, equivalent to
+Set the highest index in the array to the given number, equivalent to
Perl's C<$#array = $fill;>.
+The number of elements in the an array will be C<fill + 1> after
+av_fill() returns. If the array was previously shorter then the
+additional elements appended are set to C<PL_sv_undef>. If the array
+was longer, then the excess elements are freed. C<av_fill(av, -1)> is
+the same as C<av_clear(av)>.
+
void av_fill(AV* ar, I32 fill)
=for hackers
=item av_len
X<av_len>
-Returns the highest index in the array. Returns -1 if the array is
-empty.
+Returns the highest index in the array. The number of elements in the
+array is C<av_len(av) + 1>. Returns -1 if the array is empty.
I32 av_len(const AV* ar)
AV* newAV()
=for hackers
-Found in file av.c
+Found in file av.h
=item sortsv
X<sortsv>
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->new doesn't.
+threads->create doesn't.
CLONEf_KEEP_PTR_TABLE
perl_clone keeps a ptr_table with the pointer of the old
=item get_cv
X<get_cv>
-Returns the CV of the specified Perl subroutine. If C<create> is set and
-the Perl subroutine does not exist then it will be declared (which has the
-same effect as saying C<sub name;>). If C<create> is not set and the
-subroutine does not exist then NULL is returned.
+Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cv(const char* name, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item get_cvn_flags
+X<get_cvn_flags>
+
+Returns the CV of the specified Perl subroutine. C<flags> are passed to
+C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
+exist then it will be declared (which has the same effect as saying
+C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
+then NULL is returned.
NOTE: the perl_ form of this function is deprecated.
- CV* get_cv(const char* name, I32 create)
+ CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
=for hackers
Found in file perl.c
=back
+=head1 Functions in file dump.c
+
+
+=over 8
+
+=item pv_display
+X<pv_display>
+
+ char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
+ STRLEN pvlim, U32 flags)
+
+Similar to
+
+ pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
+
+except that an additional "\0" will be appended to the string when
+len > cur and pv[cur] is "\0".
+
+Note that the final string may be up to 7 chars longer than pvlim.
+
+ char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
+
+=for hackers
+Found in file dump.c
+
+=item pv_escape
+X<pv_escape>
+
+ |const STRLEN count|const STRLEN max
+ |STRLEN const *escaped, const U32 flags
+
+Escapes at most the first "count" chars of pv and puts the results into
+dsv such that the size of the escaped string will not exceed "max" chars
+and will not contain any incomplete escape sequences.
+
+If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
+will also be escaped.
+
+Normally the SV will be cleared before the escaped string is prepared,
+but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
+
+If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
+if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
+using C<is_utf8_string()> to determine if it is Unicode.
+
+If PERL_PV_ESCAPE_ALL is set then all input chars will be output
+using C<\x01F1> style escapes, otherwise only chars above 255 will be
+escaped using this style, other non printable chars will use octal or
+common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
+then all chars below 255 will be treated as printable and
+will be output as literals.
+
+If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
+string will be escaped, regardles of max. If the string is utf8 and
+the chars value is >255 then it will be returned as a plain hex
+sequence. Thus the output will either be a single char,
+an octal escape sequence, a special escape like C<\n> or a 3 or
+more digit hex value.
+
+If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
+not a '\\'. This is because regexes very often contain backslashed
+sequences, whereas '%' is not a particularly common character in patterns.
+
+Returns a pointer to the escaped text as held by dsv.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+=item pv_pretty
+X<pv_pretty>
+
+ |const STRLEN count|const STRLEN max\
+ |const char const *start_color| const char const *end_color\
+ |const U32 flags
+
+Converts a string into something presentable, handling escaping via
+pv_escape() and supporting quoting and ellipses.
+
+If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
+double quoted with any double quotes in the string escaped. Otherwise
+if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
+angle brackets.
+
+If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
+string were output then an ellipsis C<...> will be appended to the
+string. Note that this happens AFTER it has been quoted.
+
+If start_color is non-null then it will be inserted after the opening
+quote (if there is one) but before the escaped text. If end_color
+is non-null then it will be inserted after the escaped text but before
+any quotes or ellipses.
+
+Returns a pointer to the prettified text as held by dsv.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+
+=back
+
=head1 Functions in file mathoms.c
=for hackers
Found in file mathoms.c
+=item pack_cat
+X<pack_cat>
+
+The engine implementing pack() Perl function. Note: parameters next_in_list and
+flags are not used. This call should not be used; use packlist instead.
+
+ void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+
+=for hackers
+Found in file mathoms.c
+
=item sv_2pvbyte_nolen
X<sv_2pvbyte_nolen>
=for hackers
Found in file mathoms.c
-=item sv_uv
-X<sv_uv>
+=item sv_usepvn
+X<sv_usepvn>
-A private implementation of the C<SvUVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+Tells an SV to use C<ptr> to find its string value. Implemented by
+calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
+magic. See C<sv_usepvn_flags>.
- UV sv_uv(SV* sv)
+ void sv_usepvn(SV* sv, char* ptr, STRLEN len)
=for hackers
Found in file mathoms.c
+=item sv_usepvn_mg
+X<sv_usepvn_mg>
-=back
-
-=head1 Functions in file pp_pack.c
-
-
-=over 8
-
-=item packlist
-X<packlist>
-
-The engine implementing pack() Perl function.
-
- void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
-
-=for hackers
-Found in file pp_pack.c
-
-=item pack_cat
-X<pack_cat>
-
-The engine implementing pack() Perl function. Note: parameters next_in_list and
-flags are not used. This call should not be used; use packlist instead.
+Like C<sv_usepvn>, but also handles 'set' magic.
- void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+ void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
=for hackers
-Found in file pp_pack.c
+Found in file mathoms.c
-=item unpackstring
-X<unpackstring>
+=item sv_uv
+X<sv_uv>
-The engine implementing unpack() Perl function. C<unpackstring> puts the
-extracted list items on the stack and returns the number of elements.
-Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
+A private implementation of the C<SvUVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
- I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
+ UV sv_uv(SV* sv)
=for hackers
-Found in file pp_pack.c
+Found in file mathoms.c
=item unpack_str
X<unpack_str>
I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
=for hackers
-Found in file pp_pack.c
+Found in file mathoms.c
=back
-=head1 Global Variables
+=head1 Functions in file pp_ctl.c
+
=over 8
-=item PL_modglobal
-X<PL_modglobal>
+=item find_runcv
+X<find_runcv>
-C<PL_modglobal> is a general purpose, interpreter global HV for use by
-extensions that need to keep information on a per-interpreter basis.
-In a pinch, it can also be used as a symbol table for extensions
-to share data among each other. It is a good idea to use keys
-prefixed by the package name of the extension that owns the data.
+Locate the CV corresponding to the currently executing sub or eval.
+If db_seqp is non_null, skip CVs that are in the DB package and populate
+*db_seqp with the cop sequence number at the point that the DB:: code was
+entered. (allows debuggers to eval in the scope of the breakpoint rather
+than in the scope of the debugger itself).
- HV* PL_modglobal
+ CV* find_runcv(U32 *db_seqp)
=for hackers
-Found in file intrpvar.h
+Found in file pp_ctl.c
-=item PL_na
-X<PL_na>
-
-A convenience variable which is typically used with C<SvPV> when one
-doesn't care about the length of the string. It is usually more efficient
-to either declare a local variable and use that instead or to use the
-C<SvPV_nolen> macro.
-
- STRLEN PL_na
-
-=for hackers
-Found in file thrdvar.h
-=item PL_sv_no
-X<PL_sv_no>
+=back
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
+=head1 Functions in file pp_pack.c
- SV PL_sv_no
-=for hackers
-Found in file intrpvar.h
+=over 8
-=item PL_sv_undef
-X<PL_sv_undef>
+=item packlist
+X<packlist>
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+The engine implementing pack() Perl function.
- SV PL_sv_undef
+ void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
=for hackers
-Found in file intrpvar.h
+Found in file pp_pack.c
-=item PL_sv_yes
-X<PL_sv_yes>
+=item unpackstring
+X<unpackstring>
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
+The engine implementing unpack() Perl function. C<unpackstring> puts the
+extracted list items on the stack and returns the number of elements.
+Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
- SV PL_sv_yes
+ I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
=for hackers
-Found in file intrpvar.h
+Found in file pp_pack.c
=back
The argument C<level> should be either 0 or -1. If C<level==0>, as a
side-effect creates a glob with the given C<name> in the given C<stash>
which in the case of success contains an alias for the subroutine, and sets
-up caching info for this glob. Similarly for all the searched stashes.
+up caching info for this glob.
This function grants C<"SUPER"> token as a postfix of the stash name. The
GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
=item gv_stashpv
X<gv_stashpv>
-Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string and must be null-terminated. If C<create> is set
-then the package will be created if it does not already exist. If C<create>
-is not set and the package does not exist then NULL is returned.
+Returns a pointer to the stash for a specified package. Uses C<strlen> to
+determine the length of C<name>, then calls C<gv_stashpvn()>.
- HV* gv_stashpv(const char* name, I32 create)
+ HV* gv_stashpv(const char* name, I32 flags)
=for hackers
Found in file gv.c
=item gv_stashpvn
X<gv_stashpvn>
-Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string. The C<namelen> parameter indicates the length of
-the C<name>, in bytes. If C<create> is set then the package will be
-created if it does not already exist. If C<create> is not set and the
-package does not exist then NULL is returned.
+Returns a pointer to the stash for a specified package. The C<namelen>
+parameter indicates the length of the C<name>, in bytes. C<flags> is passed
+to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
+created if it does not already exist. If the package does not exist and
+C<flags> is 0 (or any other setting that does not create packages) then NULL
+is returned.
- HV* gv_stashpvn(const char* name, U32 namelen, I32 create)
+
+ HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
=for hackers
Found in file gv.c
+=item gv_stashpvs
+X<gv_stashpvs>
+
+Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
+
+ HV* gv_stashpvs(const char* name, I32 create)
+
+=for hackers
+Found in file handy.h
+
=item gv_stashsv
X<gv_stashsv>
-Returns a pointer to the stash for a specified package, which must be a
-valid UTF-8 string. See C<gv_stashpv>.
+Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
- HV* gv_stashsv(SV* sv, I32 create)
+ HV* gv_stashsv(SV* sv, I32 flags)
=for hackers
Found in file gv.c
=item Nullch
X<Nullch>
-Null character pointer.
+Null character pointer. (No longer available when C<PERL_CORE> is defined.)
=for hackers
Found in file handy.h
=item Nullsv
X<Nullsv>
-Null SV pointer.
+Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
=for hackers
Found in file handy.h
variable. Remember though, that hash keys in perl are free to contain
embedded nulls, so using C<strlen()> or similar is not a good way to find
the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document.
+described elsewhere in this document. See also C<HeUTF8>.
+
+If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
+new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
+efficient.
char* HePV(HE* he, STRLEN len)
=item HeSVKEY
X<HeSVKEY>
-Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
+Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
contain an C<SV*> key.
SV* HeSVKEY(HE* he)
=for hackers
Found in file hv.h
+=item HeUTF8
+X<HeUTF8>
+
+Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
+doing any necessary dereferencing of possibly C<SV*> keys. The value returned
+will be 0 or non-0, not necessarily 1 (or even a value with any low bits set),
+so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
+typedef for C<char>.
+
+ char* HeUTF8(HE* he, STRLEN len)
+
+=for hackers
+Found in file hv.h
+
=item HeVAL
X<HeVAL>
=for hackers
Found in file hv.c
+=item hv_fetchs
+X<hv_fetchs>
+
+Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
+
+ SV** hv_fetchs(HV* tb, const char* key, I32 lval)
+
+=for hackers
+Found in file handy.h
+
=item hv_fetch_ent
X<hv_fetch_ent>
=for hackers
Found in file hv.c
+=item hv_stores
+X<hv_stores>
+
+Like C<hv_store>, but takes a literal string instead of a string/length pair
+and omits the hash parameter.
+
+ SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
+
+=for hackers
+Found in file handy.h
+
=item hv_store_ent
X<hv_store_ent>
HV* newHV()
=for hackers
-Found in file hv.c
+Found in file hv.h
=back
In 5.9.3, Newx() and friends replace the older New() API, and drops
the first parameter, I<x>, a debug aid which allowed callers to identify
-themselves. This aid has been superceded by a new build option,
+themselves. This aid has been superseded by a new build option,
PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
there for use in XS modules supporting older perls.
=item Poison
X<Poison>
-Fill up memory with a pattern (byte 0xAB over and over again) that
-hopefully catches attempts to access uninitialized memory.
+PoisonWith(0xEF) for catching access to freed memory.
void Poison(void* dest, int nitems, type)
=for hackers
Found in file handy.h
+=item PoisonFree
+X<PoisonFree>
+
+PoisonWith(0xEF) for catching access to freed memory.
+
+ void PoisonFree(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonNew
+X<PoisonNew>
+
+PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
+
+ void PoisonNew(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonWith
+X<PoisonWith>
+
+Fill up memory with a byte pattern (a byte repeated over and over
+again) that hopefully catches attempts to access uninitialized memory.
+
+ void PoisonWith(void* dest, int nitems, type, U8 byte)
+
+=for hackers
+Found in file handy.h
+
=item Renew
X<Renew>
Perl's version of what C<strndup()> would be if it existed. Returns a
pointer to a newly allocated string which is a duplicate of the first
-C<len> bytes from C<pv>. The memory allocated for the new string can be
-freed with the C<Safefree()> function.
+C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
+the new string can be freed with the C<Safefree()> function.
char* savepvn(const char* pv, I32 len)
=for hackers
Found in file util.c
+=item savepvs
+X<savepvs>
+
+Like C<savepvn>, but takes a literal string instead of a string/length pair.
+
+ char* savepvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
=item savesharedpv
X<savesharedpv>
=for hackers
Found in file util.c
+=item savesharedpvn
+X<savesharedpvn>
+
+A version of C<savepvn()> which allocates the duplicate string in memory
+which is shared between threads. (With the specific difference that a NULL
+pointer is not acceptable)
+
+ char* savesharedpvn(const char *const pv, const STRLEN len)
+
+=for hackers
+Found in file util.c
+
=item savesvpv
X<savesvpv>
X<fbm_instr>
Returns the location of the SV in the string delimited by C<str> and
-C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
+C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
does not have to be fbm_compiled, but the search will not be as fast
then.
=for hackers
Found in file util.c
+=item my_snprintf
+X<my_snprintf>
+
+The C library C<snprintf> functionality, if available and
+standards-compliant (uses C<vsnprintf>, actually). However, if the
+C<vsnprintf> is not available, will unfortunately use the unsafe
+C<vsprintf> which can overrun the buffer (there is an overrun check,
+but that may be too late). Consider using C<sv_vcatpvf> instead, or
+getting C<vsnprintf>.
+
+ int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
+
+=for hackers
+Found in file util.c
+
=item my_sprintf
X<my_sprintf>
=for hackers
Found in file util.c
-=item new_version
-X<new_version>
+=item my_vsnprintf
+X<my_vsnprintf>
-Returns a new version object based on the passed in SV:
+The C library C<vsnprintf> if available and standards-compliant.
+However, if if the C<vsnprintf> is not available, will unfortunately
+use the unsafe C<vsprintf> which can overrun the buffer (there is an
+overrun check, but that may be too late). Consider using
+C<sv_vcatpvf> instead, or getting C<vsnprintf>.
- SV *sv = new_version(SV *ver);
+ int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
+
+=for hackers
+Found in file util.c
+
+=item new_version
+X<new_version>
+
+Returns a new version object based on the passed in SV:
+
+ SV *sv = new_version(SV *ver);
Does not alter the passed in ver SV. See "upg_version" if you
want to upgrade the SV.
Function must be called with an already existing SV like
sv = newSV(0);
- s = scan_version(s,SV *sv, bool qv);
+ s = scan_version(s, SV *sv, bool qv);
Performs some preprocessing to the string to ensure that
it has the correct characteristics of a version. Flags the
object if it contains an underscore (which denotes this
-is a alpha version). The boolean qv denotes that the version
+is an alpha version). The boolean qv denotes that the version
should be interpreted as if it had multiple decimals, even if
it doesn't.
=for hackers
Found in file handy.h
+=item sv_destroyable
+X<sv_destroyable>
+
+Dummy routine which reports that object can be destroyed when there is no
+sharing module present. It ignores its single SV argument, and returns
+'true'. Exists to avoid test for a NULL function pointer and because it
+could potentially warn under some level of strict-ness.
+
+ bool sv_destroyable(SV *sv)
+
+=for hackers
+Found in file util.c
+
=item sv_nosharing
X<sv_nosharing>
In-place upgrade of the supplied SV to a version object.
- SV *sv = upg_version(SV *sv);
+ SV *sv = upg_version(SV *sv, bool qv);
-Returns a pointer to the upgraded SV.
+Returns a pointer to the upgraded SV. Set the boolean qv if you want
+to force this SV to be interpreted as an "extended" version.
- SV* upg_version(SV *ver)
+ SV* upg_version(SV *ver, bool qv)
=for hackers
Found in file util.c
=back
+=head1 MRO Functions
+
+=over 8
+
+=item mro_get_linear_isa
+X<mro_get_linear_isa>
+
+Returns either C<mro_get_linear_isa_c3> or
+C<mro_get_linear_isa_dfs> for the given stash,
+dependant upon which MRO is in effect
+for that stash. The return value is a
+read-only AV*.
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+ AV* mro_get_linear_isa(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+=item mro_method_changed_in
+X<mro_method_changed_in>
+
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
+
+Ideally, all instances of C<PL_sub_generation++> in
+perl source outside of C<mro.c> should be
+replaced by calls to this.
+
+Perl automatically handles most of the common
+ways a method might be redefined. However, there
+are a few ways you could change a method in a stash
+without the cache code noticing, in which case you
+need to call this method afterwards:
+
+1) Directly manipulating the stash HV entries from
+XS code.
+
+2) Assigning a reference to a readonly scalar
+constant into a stash entry in order to create
+a constant subroutine (like constant.pm
+does).
+
+This same method is available from pure perl
+via, C<mro::method_changed_in(classname)>.
+
+ void mro_method_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
=head1 Multicall Functions
=over 8
=for hackers
Found in file numeric.c
+=item Perl_signbit
+X<Perl_signbit>
+
+Return a non-zero integer if the sign bit on an NV is set, and 0 if
+it is not.
+
+If Configure detects this system has a signbit() that will work with
+our NVs, then we just use it via the #define in perl.h. Otherwise,
+fall back on this implementation. As a first pass, this gets everything
+right except -0.0. Alas, catching -0.0 is the main use for this function,
+so this is not too helpful yet. Still, at least we have the scaffolding
+in place to support other systems, should that prove useful.
+
+
+Configure notes: This function is called 'Perl_signbit' instead of a
+plain 'signbit' because it is easy to imagine a system having a signbit()
+function or macro that doesn't happen to work with our particular choice
+of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
+the standard system headers to be happy. Also, this is a no-context
+function (no pTHX_) because Perl_signbit() is usually re-#defined in
+perl.h as a simple macro call to the system's signbit().
+Users should just always call Perl_signbit().
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ int Perl_signbit(NV f)
+
+=for hackers
+Found in file numeric.c
+
=item scan_bin
X<scan_bin>
=item newXS
X<newXS>
-Used by C<xsubpp> to hook up XSUBs as Perl subs.
+Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
+static storage, as it is used directly as CvFILE(), without a copy being made.
=for hackers
Found in file op.c
=back
+=head1 Per-Interpreter Variables
+
+=over 8
+
+=item PL_modglobal
+X<PL_modglobal>
+
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
+ HV* PL_modglobal
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_na
+X<PL_na>
+
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_no
+X<PL_sv_no>
+
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_undef
+X<PL_sv_undef>
+
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_yes
+X<PL_sv_yes>
+
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
+
+=for hackers
+Found in file intrpvar.h
+
+
+=back
+
+=head1 REGEXP Functions
+
+=over 8
+
+=item SvRX
+X<SvRX>
+
+Convenience macro to get the REGEXP from a SV. This is approximately
+equivalent to the following snippet:
+
+ if (SvMAGICAL(sv))
+ mg_get(sv);
+ if (SvROK(sv) &&
+ (tmpsv = (SV*)SvRV(sv)) &&
+ SvTYPE(tmpsv) == SVt_PVMG &&
+ (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
+ {
+ return (REGEXP *)tmpmg->mg_obj;
+ }
+
+NULL will be returned if a REGEXP* is not found.
+
+ REGEXP * SvRX(SV *sv)
+
+=for hackers
+Found in file regexp.h
+
+=item SvRXOK
+X<SvRXOK>
+
+Returns a boolean indicating whether the SV contains qr magic
+(PERL_MAGIC_qr).
+
+If you want to do something with the REGEXP* later use SvRX instead
+and check for NULL.
+
+ bool SvRXOK(SV* sv)
+
+=for hackers
+Found in file regexp.h
+
+
+=back
+
=head1 Simple Exception Handling Macros
=over 8
X<mPUSHi>
Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
-and C<XPUSHi>.
+Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>.
void mPUSHi(IV iv)
X<mPUSHn>
Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
-and C<XPUSHn>.
+Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>.
void mPUSHn(NV nv)
X<mPUSHp>
Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Handles 'set' magic. Does
-
not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
+The C<len> indicates the length of the string. Does not use C<TARG>.
+See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
void mPUSHp(char* str, STRLEN len)
=for hackers
Found in file pp.h
+=item mPUSHs
+X<mPUSHs>
+
+Push an SV onto the stack and mortalizes the SV. The stack must have room
+for this element. Does not use C<TARG>. See also C<PUSHs> and C<mXPUSHs>.
+
+ void mPUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
=item mPUSHu
X<mPUSHu>
Push an unsigned integer onto the stack. The stack must have room for this
-element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
-C<mXPUSHu> and C<XPUSHu>.
+element. Does not use C<TARG>. See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>.
void mPUSHu(UV uv)
=item mXPUSHi
X<mXPUSHi>
-Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
-C<PUSHi>.
+Push an integer onto the stack, extending the stack if necessary.
+Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>.
void mXPUSHi(IV iv)
=item mXPUSHn
X<mXPUSHn>
-Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
-C<PUSHn>.
+Push a double onto the stack, extending the stack if necessary.
+Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>.
void mXPUSHn(NV nv)
X<mXPUSHp>
Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. Does not use
-C<
TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
+indicates the length of the string. Does not use C<TARG>. See also C<XPUSHp>,
+C<mPUSHp> and C<PUSHp>.
void mXPUSHp(char* str, STRLEN len)
=for hackers
Found in file pp.h
+=item mXPUSHs
+X<mXPUSHs>
+
+Push an SV onto the stack, extending the stack if necessary and mortalizes
+the SV. Does not use C<TARG>. See also C<XPUSHs> and C<mPUSHs>.
+
+ void mXPUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
=item mXPUSHu
X<mXPUSHu>
Push an unsigned integer onto the stack, extending the stack if necessary.
-Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
-and C<PUSHu>.
+Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>.
void mXPUSHu(UV uv)
X<PUSHmortal>
Push a new mortal SV onto the stack. The stack must have room for this
-element. Does not handle 'set' magic. Does not use C<TARG>. See also
-C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
+element. Does not use C<TARG>. See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
void PUSHmortal()
=item XPUSHmortal
X<XPUSHmortal>
-Push a new mortal SV onto the stack, extending the stack if necessary. Does
-not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>,
-C<PUSHmortal> and C<PUSHs>.
+Push a new mortal SV onto the stack, extending the stack if necessary.
+Does not use C<TARG>. See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>.
void XPUSHmortal()
=for hackers
Found in file perl.c
-=item looks_like_number
-X<looks_like_number>
-
-Test if the content of an SV looks like a number (or is a number).
-C<Inf> and C<Infinity> are treated as numbers (so will not issue a
-non-numeric warning), even if your atof() doesn't grok them.
-
- I32 looks_like_number(SV* sv)
-
-=for hackers
-Found in file sv.c
-
=item newRV_inc
X<newRV_inc>
=for hackers
Found in file sv.h
-=item newRV_noinc
-X<newRV_noinc>
+=item newSVpvn_utf8
+X<newSVpvn_utf8>
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
+Creates a new SV and copies a string into it. If utf8 is true, calls
+C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
- SV* newRV_noinc(SV *sv)
+ SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item NEWSV
-X<NEWSV>
+=item SvCUR
+X<SvCUR>
-Creates a new SV. A non-zero C<len> parameter indicates the number of
-bytes of preallocated string space the SV should have. An extra byte for a
-tailing 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.
-C<id> is an integer id between 0 and 1299 (used to identify leaks).
+Returns the length of the string which is in the SV. See C<SvLEN>.
- SV* NEWSV(int id, STRLEN len)
+ STRLEN SvCUR(SV* sv)
=for hackers
-Found in file handy.h
+Found in file sv.h
-=item newSV
-X<newSV>
+=item SvCUR_set
+X<SvCUR_set>
-Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
-with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
-macro.
+Set the current length of the string which is in the SV. See C<SvCUR>
+and C<SvIV_set>.
- SV* newSV(STRLEN len)
+ void SvCUR_set(SV* sv, STRLEN len)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVhek
-X<newSVhek>
+=item SvEND
+X<SvEND>
-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 the hek is NULL.
+Returns a pointer to the last character in the string which is in the SV.
+See C<SvCUR>. Access the character as *(SvEND(sv)).
- SV* newSVhek(const HEK *hek)
+ char* SvEND(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSViv
-X<newSViv>
+=item SvGAMAGIC
+X<SvGAMAGIC>
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
+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.
- SV* newSViv(IV i)
+ char* SvGAMAGIC(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVnv
-X<newSVnv>
+=item SvGROW
+X<SvGROW>
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
+Expands the character buffer in the SV so that it has room for the
+indicated number of bytes (remember to reserve space for an extra trailing
+NUL character). Calls C<sv_grow> to perform the expansion if necessary.
+Returns a pointer to the character buffer.
- SV* newSVnv(NV n)
+ char * SvGROW(SV* sv, STRLEN len)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVpv
-X<newSVpv>
+=item SvIOK
+X<SvIOK>
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero, Perl will compute the length using
-strlen(). For efficiency, consider using C<newSVpvn> instead.
+Returns a U32 value indicating whether the SV contains an integer.
- SV* newSVpv(const char* s, STRLEN len)
+ U32 SvIOK(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVpvf
-X<newSVpvf>
+=item SvIOKp
+X<SvIOKp>
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
+Returns a U32 value indicating whether the SV contains an integer. Checks
+the B<private> setting. Use C<SvIOK>.
- SV* newSVpvf(const char* pat, ...)
+ U32 SvIOKp(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVpvn
-X<newSVpvn>
+=item SvIOK_notUV
+X<SvIOK_notUV>
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
-string. You are responsible for ensuring that the source string is at least
-C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
+Returns a boolean indicating whether the SV contains a signed integer.
- SV* newSVpvn(const char* s, STRLEN len)
+ bool SvIOK_notUV(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item newSVpvn_share
-X<newSVpvn_share>
-
-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 READONLY and FAKE. The string's hash is stored in the UV
-slot of the SV; if the C<hash> parameter is non-zero, that value is used;
-otherwise the hash is computed. 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.
-
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
-
-=for hackers
-Found in file sv.c
-
-=item newSVrv
-X<newSVrv>
-
-Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
-it will be upgraded to one. If C<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.
-
- SV* newSVrv(SV* rv, const char* classname)
-
-=for hackers
-Found in file sv.c
-
-=item newSVsv
-X<newSVsv>
-
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>).
-
- SV* newSVsv(SV* old)
-
-=for hackers
-Found in file sv.c
-
-=item newSVuv
-X<newSVuv>
-
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
-
- SV* newSVuv(UV u)
-
-=for hackers
-Found in file sv.c
-
-=item SvCUR
-X<SvCUR>
-
-Returns the length of the string which is in the SV. See C<SvLEN>.
-
- STRLEN SvCUR(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvCUR_set
-X<SvCUR_set>
-
-Set the current length of the string which is in the SV. See C<SvCUR>
-and C<SvIV_set>.
-
- void SvCUR_set(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvEND
-X<SvEND>
-
-Returns a pointer to the last character in the string which is in the SV.
-See C<SvCUR>. Access the character as *(SvEND(sv)).
-
- char* SvEND(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvGROW
-X<SvGROW>
-
-Expands the character buffer in the SV so that it has room for the
-indicated number of bytes (remember to reserve space for an extra trailing
-NUL character). Calls C<sv_grow> to perform the expansion if necessary.
-Returns a pointer to the character buffer.
-
- char * SvGROW(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK
-X<SvIOK>
-
-Returns a boolean indicating whether the SV contains an integer.
-
- bool SvIOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOKp
-X<SvIOKp>
-
-Returns a boolean indicating whether the SV contains an integer. Checks
-the B<private> setting. Use C<SvIOK>.
-
- bool SvIOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_notUV
-X<SvIOK_notUV>
-
-Returns a boolean indicating whether the SV contains a signed integer.
-
- bool SvIOK_notUV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_off
-X<SvIOK_off>
+=item SvIOK_off
+X<SvIOK_off>
Unsets the IV status of an SV.
=item SvIV
X<SvIV>
-Coerces the given SV to an integer and returns it. See C<SvIVx> for a
+Coerces the given SV to an integer and returns it. See C<SvIVx> for a
version which guarantees to evaluate sv only once.
IV SvIV(SV* sv)
X<SvIVx>
Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvIV> otherwise.
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvIV>.
IV SvIVx(SV* sv)
=item SvNIOK
X<SvNIOK>
-Returns a boolean indicating whether the SV contains a number, integer or
+Returns a U32 value indicating whether the SV contains a number, integer or
double.
- bool SvNIOK(SV* sv)
+ U32 SvNIOK(SV* sv)
=for hackers
Found in file sv.h
=item SvNIOKp
X<SvNIOKp>
-Returns a boolean indicating whether the SV contains a number, integer or
+Returns a U32 value indicating whether the SV contains a number, integer or
double. Checks the B<private> setting. Use C<SvNIOK>.
- bool SvNIOKp(SV* sv)
+ U32 SvNIOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvNOK
X<SvNOK>
-Returns a boolean indicating whether the SV contains a double.
+Returns a U32 value indicating whether the SV contains a double.
- bool SvNOK(SV* sv)
+ U32 SvNOK(SV* sv)
=for hackers
Found in file sv.h
=item SvNOKp
X<SvNOKp>
-Returns a boolean indicating whether the SV contains a double. Checks the
+Returns a U32 value indicating whether the SV contains a double. Checks the
B<private> setting. Use C<SvNOK>.
- bool SvNOKp(SV* sv)
+ U32 SvNOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvNV
X<SvNV>
-Coerce the given SV to a double and return it. See C<SvNVx> for a version
+Coerce the given SV to a double and return it. See C<SvNVx> for a version
which guarantees to evaluate sv only once.
NV SvNV(SV* sv)
X<SvNVx>
Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvNV> otherwise.
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvNV>.
NV SvNVx(SV* sv)
=item SvOK
X<SvOK>
-Returns a boolean indicating whether the value is an SV. It also tells
+Returns a U32 value indicating whether the value is an SV. It also tells
whether the value is defined or not.
- bool SvOK(SV* sv)
+ U32 SvOK(SV* sv)
=for hackers
Found in file sv.h
=item SvOOK
X<SvOOK>
-Returns a boolean indicating whether the SvIVX is a valid offset value for
-the SvPVX. This hack is used internally to speed up removal of characters
-from the beginning of a SvPV. When SvOOK is true, then the start of the
-allocated string buffer is really (SvPVX - SvIVX).
+Returns a U32 indicating whether the pointer to the string buffer is offset.
+This hack is used internally to speed up removal of characters from the
+beginning of a SvPV. When SvOOK is true, then the start of the
+allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
+This offset used to be stored in SvIVX, but is now stored within the spare
+part of the buffer.
+
+ U32 SvOOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvOOK_offset
+X<SvOOK_offset>
+
+Reads into I<len> the offset from SvPVX back to the true start of the
+allocated buffer, which will be non-zero if C<sv_chop> has been used to
+efficiently remove characters from start of the buffer. Implemented as a
+macro, which takes the address of I<len>, which must be of type C<STRLEN>.
+Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
- bool SvOOK(SV* sv)
+ void SvOOK_offset(NN SV*sv, STRLEN len)
=for hackers
Found in file sv.h
=item SvPOK
X<SvPOK>
-Returns a boolean indicating whether the SV contains a character
+Returns a U32 value indicating whether the SV contains a character
string.
- bool SvPOK(SV* sv)
+ U32 SvPOK(SV* sv)
=for hackers
Found in file sv.h
=item SvPOKp
X<SvPOKp>
-Returns a boolean indicating whether the SV contains a character string.
+Returns a U32 value indicating whether the SV contains a character string.
Checks the B<private> setting. Use C<SvPOK>.
- bool SvPOKp(SV* sv)
+ U32 SvPOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvPVx
X<SvPVx>
-A version of C<SvPV> which guarantees to evaluate sv only once.
+A version of C<SvPV> which guarantees to evaluate C<sv> only once.
+Only use this if C<sv> is an expression with side effects, otherwise use the
+more efficient C<SvPVX>.
char* SvPVx(SV* sv, STRLEN len)
Increments the reference count of the given SV.
+All of the following SvREFCNT_inc* macros are optimized versions of
+SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
+
SV* SvREFCNT_inc(SV* sv)
=for hackers
Found in file sv.h
+=item SvREFCNT_inc_NN
+X<SvREFCNT_inc_NN>
+
+Same as SvREFCNT_inc, but can only be used if you know I<sv>
+is not NULL. Since we don't have to check the NULLness, it's faster
+and smaller.
+
+ SV* SvREFCNT_inc_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple
+X<SvREFCNT_inc_simple>
+
+Same as SvREFCNT_inc, but can only be used with expressions without side
+effects. Since we don't have to store a temporary value, it's faster.
+
+ SV* SvREFCNT_inc_simple(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_NN
+X<SvREFCNT_inc_simple_NN>
+
+Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
+is not NULL. Since we don't have to check the NULLness, it's faster
+and smaller.
+
+ SV* SvREFCNT_inc_simple_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void
+X<SvREFCNT_inc_simple_void>
+
+Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+return value. The macro doesn't need to return a meaningful value.
+
+ void SvREFCNT_inc_simple_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void_NN
+X<SvREFCNT_inc_simple_void_NN>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the return
+value, and you know that I<sv> is not NULL. The macro doesn't need
+to return a meaningful value, or check for NULLness, so it's smaller
+and faster.
+
+ void SvREFCNT_inc_simple_void_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void
+X<SvREFCNT_inc_void>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the
+return value. The macro doesn't need to return a meaningful value.
+
+ void SvREFCNT_inc_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void_NN
+X<SvREFCNT_inc_void_NN>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the return
+value, and you know that I<sv> is not NULL. The macro doesn't need
+to return a meaningful value, or check for NULLness, so it's smaller
+and faster.
+
+ void SvREFCNT_inc_void_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
=item SvROK
X<SvROK>
Tests if the SV is an RV.
- bool SvROK(SV* sv)
+ U32 SvROK(SV* sv)
=for hackers
Found in file sv.h
=item SvSTASH_set
X<SvSTASH_set>
-Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
+Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
+
+ void SvSTASH_set(SV* sv, HV* val)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINT
+X<SvTAINT>
+
+Taints an SV if tainting is enabled.
+
+ void SvTAINT(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED
+X<SvTAINTED>
+
+Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
+not.
+
+ bool SvTAINTED(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_off
+X<SvTAINTED_off>
+
+Untaints an SV. Be I<very> careful with this routine, as it short-circuits
+some of Perl's fundamental security features. XS module authors should not
+use this function unless they fully understand all the implications of
+unconditionally untainting the value. Untainting should be done in the
+standard perl fashion, via a carefully crafted regexp, rather than directly
+untainting variables.
+
+ void SvTAINTED_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_on
+X<SvTAINTED_on>
+
+Marks an SV as tainted if tainting is enabled.
+
+ void SvTAINTED_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTRUE
+X<SvTRUE>
+
+Returns a boolean indicating whether Perl would evaluate the SV as true or
+false, defined or undefined. Does not handle 'get' magic.
+
+ bool SvTRUE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTYPE
+X<SvTYPE>
+
+Returns the type of the SV. See C<svtype>.
+
+ svtype SvTYPE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUOK
+X<SvUOK>
+
+Returns a boolean indicating whether the SV contains an unsigned integer.
+
+ bool SvUOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUPGRADE
+X<SvUPGRADE>
+
+Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
+perform the upgrade if necessary. See C<svtype>.
+
+ void SvUPGRADE(SV* sv, svtype type)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8
+X<SvUTF8>
+
+Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
+Call this after SvPV() in case any call to string overloading updates the
+internal flag.
+
+ U32 SvUTF8(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8_off
+X<SvUTF8_off>
+
+Unsets the UTF-8 status of an SV.
+
+ void SvUTF8_off(SV *sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8_on
+X<SvUTF8_on>
+
+Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
+Do not use frivolously.
+
+ void SvUTF8_on(SV *sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV
+X<SvUV>
+
+Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
+for a version which guarantees to evaluate sv only once.
+
+ UV SvUV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUVX
+X<SvUVX>
+
+Returns the raw value in the SV's UV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvUV()>.
+
+ UV SvUVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUVx
+X<SvUVx>
+
+Coerces the given SV to an unsigned integer and returns it. Guarantees to
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvUV>.
+
+ UV SvUVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV_nomg
+X<SvUV_nomg>
+
+Like C<SvUV> but doesn't process magic.
+
+ UV SvUV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV_set
+X<SvUV_set>
+
+Set the value of the UV pointer in sv to val. See C<SvIV_set>.
+
+ void SvUV_set(SV* sv, UV val)
+
+=for hackers
+Found in file sv.h
+
+=item SvVOK
+X<SvVOK>
+
+Returns a boolean indicating whether the SV contains a v-string.
+
+ bool SvVOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item sv_catpvn_nomg
+X<sv_catpvn_nomg>
+
+Like C<sv_catpvn> but doesn't process magic.
+
+ void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item sv_catsv_nomg
+X<sv_catsv_nomg>
+
+Like C<sv_catsv> but doesn't process magic.
+
+ void sv_catsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item sv_derived_from
+X<sv_derived_from>
+
+Returns a boolean indicating whether the SV is derived from the specified class
+I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
+normal Perl method.
+
+ bool sv_derived_from(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
+=item sv_does
+X<sv_does>
+
+Returns a boolean indicating whether the SV performs a specific, named role.
+The SV can be a Perl object or the name of a Perl class.
+
+ bool sv_does(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
+=item sv_report_used
+X<sv_report_used>
+
+Dump the contents of all SVs not yet freed. (Debugging aid).
+
+ void sv_report_used()
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv_nomg
+X<sv_setsv_nomg>
+
+Like C<sv_setsv> but doesn't process magic.
+
+ void sv_setsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+
+=back
+
+=head1 SV-Body Allocation
+
+=over 8
+
+=item looks_like_number
+X<looks_like_number>
+
+Test if the content of an SV looks like a number (or is a number).
+C<Inf> and C<Infinity> are treated as numbers (so will not issue a
+non-numeric warning), even if your atof() doesn't grok them.
- void SvSTASH_set(SV* sv, STASH* val)
+ I32 looks_like_number(SV* sv)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTAINT
-X<SvTAINT>
+=item newRV_noinc
+X<newRV_noinc>
-Taints an SV if tainting is enabled.
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
- void SvTAINT(SV* sv)
+ SV* newRV_noinc(SV* sv)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTAINTED
-X<SvTAINTED>
+=item newSV
+X<newSV>
-Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
-not.
+Creates a new SV. A non-zero C<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.
- bool SvTAINTED(SV* sv)
+In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
+parameter, I<x>, a debug aid which allowed callers to identify themselves.
+This aid has been superseded by a new build option, PERL_MEM_LOG (see
+L<perlhack/PERL_MEM_LOG>). The older API is still there for use in XS
+modules supporting older perls.
+
+ SV* newSV(STRLEN len)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTAINTED_off
-X<SvTAINTED_off>
+=item newSVhek
+X<newSVhek>
-Untaints an SV. Be I<very> careful with this routine, as it short-circuits
-some of Perl's fundamental security features. XS module authors should not
-use this function unless they fully understand all the implications of
-unconditionally untainting the value. Untainting should be done in the
-standard perl fashion, via a carefully crafted regexp, rather than directly
-untainting variables.
+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 the hek is NULL.
- void SvTAINTED_off(SV* sv)
+ SV* newSVhek(const HEK *hek)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTAINTED_on
-X<SvTAINTED_on>
+=item newSViv
+X<newSViv>
-Marks an SV as tainted if tainting is enabled.
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
- void SvTAINTED_on(SV* sv)
+ SV* newSViv(IV i)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTRUE
-X<SvTRUE>
+=item newSVnv
+X<newSVnv>
-Returns a boolean indicating whether Perl would evaluate the SV as true or
-false, defined or undefined. Does not handle 'get' magic.
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
- bool SvTRUE(SV* sv)
+ SV* newSVnv(NV n)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvTYPE
-X<SvTYPE>
+=item newSVpv
+X<newSVpv>
-Returns the type of the SV. See C<svtype>.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
- svtype SvTYPE(SV* sv)
+ SV* newSVpv(const char* s, STRLEN len)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUOK
-X<SvUOK>
+=item newSVpvf
+X<newSVpvf>
-Returns a boolean indicating whether the SV contains an unsigned integer.
+Creates a new SV and initializes it with the string formatted like
+C<sprintf>.
- void SvUOK(SV* sv)
+ SV* newSVpvf(const char* pat, ...)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUPGRADE
-X<SvUPGRADE>
+=item newSVpvn
+X<newSVpvn>
-Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
-perform the upgrade if necessary. See C<svtype>.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
- void SvUPGRADE(SV* sv, svtype type)
+ SV* newSVpvn(const char* s, STRLEN len)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUTF8
-X<SvUTF8>
+=item newSVpvn_flags
+X<newSVpvn_flags>
+
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
+Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
+If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
+returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
+C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
-Returns a boolean indicating whether the SV contains UTF-8 encoded data.
+ #define newSVpvn_utf8(s, len, u) \
+ newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
- bool SvUTF8(SV* sv)
+ SV* newSVpvn_flags(const char* s, STRLEN len, U32 flags)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUTF8_off
-X<SvUTF8_off>
+=item newSVpvn_share
+X<newSVpvn_share>
-Unsets the UTF-8 status of an SV.
+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 READONLY and FAKE. If the C<hash> parameter is non-zero, that
+value is used; otherwise the hash is computed. The string's hash can be later
+be retrieved from the SV with the C<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.
- void SvUTF8_off(SV *sv)
+ SV* newSVpvn_share(const char* s, I32 len, U32 hash)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUTF8_on
-X<SvUTF8_on>
+=item newSVpvs
+X<newSVpvs>
-Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
-Do not use frivolously.
+Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
- void SvUTF8_on(SV *sv)
+ SV* newSVpvs(const char* s)
=for hackers
-Found in file sv.h
+Found in file handy.h
-=item SvUV
-X<SvUV>
+=item newSVpvs_flags
+X<newSVpvs_flags>
-Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
-for a version which guarantees to evaluate sv only once.
+Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
+pair.
- UV SvUV(SV* sv)
+ SV* newSVpvs_flags(const char* s, U32 flags)
=for hackers
-Found in file sv.h
+Found in file handy.h
-=item SvUVX
-X<SvUVX>
+=item newSVpvs_share
+X<newSVpvs_share>
-Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvUV()>.
+Like C<newSVpvn_share>, but takes a literal string instead of a string/length
+pair and omits the hash parameter.
- UV SvUVX(SV* sv)
+ SV* newSVpvs_share(const char* s)
=for hackers
-Found in file sv.h
+Found in file handy.h
-=item SvUVx
-X<SvUVx>
+=item newSVrv
+X<newSVrv>
-Coerces the given SV to an unsigned integer and returns it. Guarantees to
-evaluate sv only once. Use the more efficient C<SvUV> otherwise.
+Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
+it will be upgraded to one. If C<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.
- UV SvUVx(SV* sv)
+ SV* newSVrv(SV* rv, const char* classname)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUV_nomg
-X<SvUV_nomg>
+=item newSVsv
+X<newSVsv>
-Like C<SvUV> but doesn't process magic.
+Creates a new SV which is an exact duplicate of the original SV.
+(Uses C<sv_setsv>).
- UV SvUV_nomg(SV* sv)
+ SV* newSVsv(SV* old)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvUV_set
-X<SvUV_set>
+=item newSVuv
+X<newSVuv>
-Set the value of the UV pointer in sv to val. See C<SvIV_set>.
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
- void SvUV_set(SV* sv, UV val)
+ SV* newSVuv(UV u)
=for hackers
-Found in file sv.h
+Found in file sv.c
-=item SvVOK
-X<SvVOK>
+=item newSV_type
+X<newSV_type>
-Returns a boolean indicating whether the SV contains a v-string.
+Creates a new SV, of the type specified. The reference count for the new SV
+is set to 1.
- bool SvVOK(SV* sv)
+ SV* newSV_type(svtype type)
=for hackers
-Found in file sv.h
+Found in file sv.c
=item sv_2bool
X<sv_2bool>
=for hackers
Found in file sv.c
-=item sv_catpvn_nomg
-X<sv_catpvn_nomg>
+=item sv_catpvs
+X<sv_catpvs>
-Like C<sv_catpvn> but doesn't process magic.
+Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
- void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
+ void sv_catpvs(SV* sv, const char* s)
=for hackers
-Found in file sv.h
+Found in file handy.h
=item sv_catpv_mg
X<sv_catpv_mg>
=for hackers
Found in file sv.c
-=item sv_catsv_nomg
-X<sv_catsv_nomg>
-
-Like C<sv_catsv> but doesn't process magic.
-
- void sv_catsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
=item sv_chop
X<sv_chop>
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 C<sv_cmp_locale>. See also C<sv_cmp>.
+if necessary. See also C<sv_cmp>.
I32 sv_cmp_locale(SV* sv1, SV* sv2)
Copies a stringified representation of the source SV into the
destination SV. Automatically performs any necessary mg_get and
coercion of numeric values into strings. Guaranteed to preserve
-UTF-8 flag even from overloaded objects. Similar in nature to
+UTF8 flag even from overloaded objects. Similar in nature to
sv_2pv[_flags] but operates directly on an SV instead of just the
string. Mostly uses sv_2pv_flags to do its work, except when that
would lose the UTF-8'ness of the PV.
=for hackers
Found in file sv.c
-=item sv_derived_from
-X<sv_derived_from>
-
-Returns a boolean indicating whether the SV is derived from the specified
-class. This is the function that implements C<UNIVERSAL::isa>. It works
-for class names as well as for objects.
-
- bool sv_derived_from(SV* sv, const char* name)
-
-=for hackers
-Found in file universal.c
-
=item sv_eq
X<sv_eq>
Returns a string describing what the SV is a reference to.
- char* sv_reftype(const SV* sv, int ob)
+ const char* sv_reftype(const SV* sv, int ob)
=for hackers
Found in file sv.c
=for hackers
Found in file sv.c
-=item sv_report_used
-X<sv_report_used>
-
-Dump the contents of all SVs not yet freed. (Debugging aid).
-
- void sv_report_used()
-
-=for hackers
-Found in file sv.c
-
=item sv_reset
X<sv_reset>
Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
referred-to SV C<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.
+associated with that magic. If the RV is magical, set magic will be
+called after the RV is cleared.
SV* sv_rvweaken(SV *sv)
=for hackers
Found in file sv.c
+=item sv_setpvs
+X<sv_setpvs>
+
+Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
+
+ void sv_setpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
=item sv_setpv_mg
X<sv_setpv_mg>
Copies an integer into a new SV, optionally blessing the SV. The C<rv>
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
will have a reference count of 1, and the RV will be returned.
SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
Copies a double into a new SV, optionally blessing the SV. The C<rv>
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
will have a reference count of 1, and the RV will be returned.
SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
into the SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+blessing. Set C<classname> to C<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
string must be specified with C<n>. The C<rv> argument will be upgraded to
an RV. That RV will be modified to point to the new SV. The C<classname>
argument indicates the package for the blessing. Set C<classname> to
-C<Nullch> to avoid the blessing. The new SV will have a reference count
+C<NULL> to avoid the blessing. The new SV will have a reference count
of 1, and the RV will be returned.
Note that C<sv_setref_pv> copies the pointer while this copies the string.
Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
will have a reference count of 1, and the RV will be returned.
SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
=for hackers
Found in file sv.c
-=item sv_setsv_nomg
-X<sv_setsv_nomg>
-
-Like C<sv_setsv> but doesn't process magic.
-
- void sv_setsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
=item sv_setuv
X<sv_setuv>
SV, then copies across as much information as possible from the old body.
You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
- void sv_upgrade(SV* sv, U32 mt)
+ void sv_upgrade(SV* sv, svtype new_type)
=for hackers
Found in file sv.c
-=item sv_usepvn
-X<sv_usepvn>
-
-Tells an SV to use C<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.
-The C<ptr> should point to memory that was allocated by C<malloc>. The
-string length, C<len>, must be supplied. This function will realloc the
-memory pointed to by C<ptr>, so that pointer should not be freed or used by
-the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
-See C<sv_usepvn_mg>.
-
- void sv_usepvn(SV* sv, char* ptr, STRLEN len)
-
-=for hackers
-Found in file sv.c
+=item sv_usepvn_flags
+X<sv_usepvn_flags>
-=item sv_usepvn_mg
-X<sv_usepvn_mg>
+Tells an SV to use C<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. The C<ptr> should point to memory that was allocated
+by C<malloc>. The string length, C<len>, must be supplied. By default
+this function will realloc (i.e. move) the memory pointed to by C<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.
-Like C<sv_usepvn>, but also handles 'set' magic.
+If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
+SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
+will be skipped. (i.e. the buffer is actually at least 1 byte longer than
+C<len>, and already meets the requirements for storing in C<SvPVX>)
- void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+ void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
=for hackers
Found in file sv.c
X<utf8n_to_uvuni>
Bottom level UTF-8 decode routine.
-Returns the unicode code point value of the first character in the string C<s>
+Returns the Unicode code point value of the first character in the string C<s>
which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
C<retlen> will be set to the length, in bytes, of that character.
updates len to contain the new length.
Returns zero on failure, setting C<len> to -1.
+If you need a copy of the string, see C<bytes_from_utf8>.
+
NOTE: this function is experimental and may change or be
removed without notice.
sidestepping the normal C order of execution. See C<warn>.
If you want to throw an exception object, assign the object to
-C<$@> and then pass C<Nullch> to croak():
+C<$@> and then pass C<NULL> to croak():
errsv = get_sv("@", TRUE);
sv_setsv(errsv, exception_object);
- croak(Nullch);
+ croak(NULL);
void croak(const char* pat, ...)
perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
+=cut
+
+ ex: set ro:
https://perl5.git.perl.org / perl5.git / blobdiff