+-*- 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)
=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 elipses.
+
+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_ELIPSES flag is set and not all characters in
+string were output then an elipses 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 elipses.
+
+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_usepvn
+X<sv_usepvn>
+
+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>.
+
+ void sv_usepvn(SV* sv, char* ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_usepvn_mg
+X<sv_usepvn_mg>
+
+Like C<sv_usepvn>, but also handles 'set' magic.
+
+ void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
=item sv_uv
X<sv_uv>
=for hackers
Found in file mathoms.c
+=item unpack_str
+X<unpack_str>
+
+The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
+and ocnt are not used. This call should not be used, use unpackstring instead.
+
+ 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 mathoms.c
+
=back
=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.
-
- 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 pp_pack.c
-
=item unpackstring
X<unpackstring>
=for hackers
Found in file pp_pack.c
-=item unpack_str
-X<unpack_str>
-
-The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
-and ocnt are not used. This call should not be used, use unpackstring instead.
-
- 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
-
=back
=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
=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>
=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>
=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 my_vsnprintf
+X<my_vsnprintf>
+
+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>.
+
+ 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>
=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
=for hackers
Found in file sv.h
+=item SvGAMAGIC
+X<SvGAMAGIC>
+
+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.
+
+ char* SvGAMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
=item SvGROW
X<SvGROW>
=item SvIOK
X<SvIOK>
-Returns a boolean indicating whether the SV contains an integer.
+Returns a U32 value indicating whether the SV contains an integer.
- bool SvIOK(SV* sv)
+ U32 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
+Returns a U32 value indicating whether the SV contains an integer. Checks
the B<private> setting. Use C<SvIOK>.
- bool SvIOKp(SV* sv)
+ U32 SvIOKp(SV* sv)
=for hackers
Found in file sv.h
=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)
=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)
=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
+Returns a U32 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).
- bool SvOOK(SV* sv)
+ U32 SvOOK(SV* sv)
=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
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
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.
- SV* SvREFCNT_inc_simple_void(SV* sv)
+ 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
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.
- SV* SvREFCNT_inc_void(SV* sv)
+ void SvREFCNT_inc_void(SV* sv)
=for hackers
Found in file sv.h
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
- SV* SvREFCNT_inc_void_NN(SV* sv)
+ void SvREFCNT_inc_void_NN(SV* sv)
=for hackers
Found in file sv.h
Tests if the SV is an RV.
- bool SvROK(SV* sv)
+ U32 SvROK(SV* sv)
=for hackers
Found in file sv.h
Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
- void SvSTASH_set(SV* sv, STASH* val)
+ void SvSTASH_set(SV* sv, HV* val)
=for hackers
Found in file sv.h
Returns a boolean indicating whether the SV contains an unsigned integer.
- void SvUOK(SV* sv)
+ bool SvUOK(SV* sv)
=for hackers
Found in file sv.h
=item SvUTF8
X<SvUTF8>
-Returns a boolean indicating whether the SV contains UTF-8 encoded data.
+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.
- bool SvUTF8(SV* sv)
+ U32 SvUTF8(SV* sv)
=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. This is the function that implements C<UNIVERSAL::isa>. It works
-for class names as well as for objects.
+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>
Creates an RV wrapper for an SV. The reference count for the original
SV is B<not> incremented.
- SV* newRV_noinc(SV *sv)
+ SV* newRV_noinc(SV* sv)
=for hackers
Found in file sv.c
=for hackers
Found in file sv.c
+=item newSVpvs
+X<newSVpvs>
+
+Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
+
+ SV* newSVpvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item newSVpvs_share
+X<newSVpvs_share>
+
+Like C<newSVpvn_share>, but takes a literal string instead of a string/length
+pair and omits the hash parameter.
+
+ SV* newSVpvs_share(const char* s)
+
+=for hackers
+Found in file handy.h
+
=item newSVrv
X<newSVrv>
=for hackers
Found in file sv.c
+=item sv_catpvs
+X<sv_catpvs>
+
+Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
+
+ void sv_catpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
=item sv_catpv_mg
X<sv_catpv_mg>
(This is now used as a subroutine by C<sv_magic>.)
- MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen)
+ MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
=for hackers
Found in file sv.c
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
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>
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>
+=item sv_usepvn_flags
+X<sv_usepvn_flags>
-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>.
+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.
- void sv_usepvn(SV* sv, char* ptr, STRLEN len)
+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>)
-=for hackers
-Found in file sv.c
-
-=item sv_usepvn_mg
-X<sv_usepvn_mg>
-
-Like C<sv_usepvn>, but also handles 'set' magic.
-
- 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
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.
perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
+=cut
+
+ ex: set ro: