=item av_delete
Deletes the element indexed by C<key> from the array. Returns the
-deleted element. C<flags> is currently ignored.
+deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
+and null is returned.
SV* av_delete(AV* ar, I32 key, I32 flags)
Returns the highest index in the array. Returns -1 if the array is
empty.
- I32 av_len(AV* ar)
+ I32 av_len(const AV* ar)
=for hackers
Found in file av.c
=for hackers
Found in file av.c
-=item Nullav
-
-Null AV pointer.
-
-
-=for hackers
-Found in file av.h
-
=item sortsv
Sort an array. Here is an example:
sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
+See lib/sort.pm for details about controlling the sorting algorithm.
+
void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
=for hackers
Create and return a new interpreter by cloning the current one.
+perl_clone takes these flags as parameters:
+
+CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
+without it we only clone the data and zero the stacks,
+with it we copy the stacks and the new perl interpreter is
+ready to run at the exact same point as the previous one.
+The pseudo-fork code uses COPY_STACKS while the
+threads->new doesn't.
+
+CLONEf_KEEP_PTR_TABLE
+perl_clone keeps a ptr_table with the pointer of the old
+variable as a key and the new variable as a value,
+this allows it to check if something has been cloned and not
+clone it again but rather just use the value and increase the
+refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
+the ptr_table using the function
+C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
+reason to keep it around is if you want to dup some of your own
+variable who are outside the graph perl scans, example of this
+code is in threads.xs create
+
+CLONEf_CLONE_HOST
+This is a win32 thing, it is ignored on unix, it tells perls
+win32host code (which is c++) to clone itself, this is needed on
+win32 if you want to run two threads at the same time,
+if you just want to do some stuff in a separate perl interpreter
+and then throw it away and return to the original one,
+you don't need to do anything.
+
PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
=for hackers
=for hackers
Found in file perl.c
-=item Nullcv
-Null CV pointer.
+=back
+=head1 Embedding Functions
-=for hackers
-Found in file cv.h
+=over 8
+=item cv_undef
-=back
+Clear out all the active components of a CV. This can happen either
+by an explicit C<undef &foo>, or by the reference count going to zero.
+In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
+children can still follow the full lexical scope chain.
-=head1 Embedding Functions
+ void cv_undef(CV* cv)
-=over 8
+=for hackers
+Found in file op.c
=item load_module
Tells Perl to C<require> the file named by the string argument. It is
analogous to the Perl code C<eval "require '$file'">. It's even
-implemented that way; consider using Perl_load_module instead.
+implemented that way; consider using load_module instead.
NOTE: the perl_ form of this function is deprecated.
=over 8
-=item pack_cat
+=item packlist
The engine implementing pack() Perl function.
- void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+ 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
+
+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
+
+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.
+
+ I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
=for hackers
Found in file pp_pack.c
=item unpack_str
-The engine implementing unpack() Perl function.
+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(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
+ 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
=item gv_stashpv
Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string. If C<create> is set then the package will be
+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.
+
+ HV* gv_stashpv(const char* name, I32 create)
+
+=for hackers
+Found in file gv.c
+
+=item 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.
- HV* gv_stashpv(const char* name, I32 create)
+ HV* gv_stashpvn(const char* name, U32 namelen, I32 create)
=for hackers
Found in file gv.c
=over 8
-=item HEf_SVKEY
-
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains an C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+=item Nullav
+Null AV pointer.
=for hackers
-Found in file hv.h
+Found in file av.h
-=item Nullch
+=item Nullch
Null character pointer.
+
=for hackers
Found in file handy.h
+=item Nullcv
+
+Null CV pointer.
+
+=for hackers
+Found in file cv.h
+
+=item Nullhv
+
+Null HV pointer.
+
+=for hackers
+Found in file hv.h
+
=item Nullsv
Null SV pointer.
=for hackers
Found in file perl.c
+=item HEf_SVKEY
+
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains an C<SV*> pointer where a C<char*> pointer
+is to be expected. (For information only--not to be used).
+
+=for hackers
+Found in file hv.h
+
=item HeHASH
Returns the computed hash stored in the hash entry.
=for hackers
Found in file hv.h
+=item hv_assert
+
+Check that a hash is in an internally consistent state.
+
+ void hv_assert(HV* tb)
+
+=for hackers
+Found in file hv.c
+
=item hv_clear
Clears a hash, making it empty.
=for hackers
Found in file hv.c
+=item hv_clear_placeholders
+
+Clears any placeholders from a hash. If a restricted hash has any of its keys
+marked as readonly and the key is subsequently deleted, the key is not actually
+deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
+it so it will be ignored by future operations such as iterating over the hash,
+but will still allow the hash to have a value reassigned to the key at some
+future point. This function clears any such placeholder keys from the hash.
+See Hash::Util::lock_keys() for an example of its use.
+
+ void hv_clear_placeholders(HV* hb)
+
+=for hackers
+Found in file hv.c
+
=item hv_delete
Deletes a key/value pair in the hash. The value SV is removed from the
hash buckets that happen to be in use. If you still need that esoteric
value, you can get it through the macro C<HvFILL(tb)>.
+
I32 hv_iterinit(HV* tb)
=for hackers
Returns entries from a hash iterator. See C<hv_iterinit>.
+You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator. Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it. Your iterator is flagged
+to free the entry on the next call to C<hv_iternext>, so you must not discard
+your iterator immediately else the entry will leak - call C<hv_iternext> to
+trigger the resource deallocation.
+
HE* hv_iternext(HV* tb)
=for hackers
=for hackers
Found in file hv.c
+=item hv_iternext_flags
+
+Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
+The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys. By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is
+C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ HE* hv_iternext_flags(HV* tb, I32 flags)
+
+=for hackers
+Found in file hv.c
+
=item hv_iterval
Returns the value from the current position of the hash iterator. See
=for hackers
Found in file hv.c
+=item hv_scalar
+
+Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
+
+ SV* hv_scalar(HV* hv)
+
+=for hackers
+Found in file hv.c
+
=item hv_store
Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
stored within the hash (as in the case of tied hashes). Otherwise it can
be dereferenced to get the original C<SV*>. Note that the caller is
responsible for suitably incrementing the reference count of C<val> before
-the call, and decrementing it if the function returned NULL.
+the call, and decrementing it if the function returned NULL. Effectively
+a successful hv_store takes ownership of one reference to C<val>. This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, hv_store
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up. hv_store is not implemented as a call to
+hv_store_ent, and does not create a temporary SV for the key, so if your
+key data is not already in SV form then use hv_store in preference to
+hv_store_ent.
See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
information on how to use this function on tied hashes.
contents of the return value can be accessed using the C<He?> macros
described here. Note that the caller is responsible for suitably
incrementing the reference count of C<val> before the call, and
-decrementing it if the function returned NULL.
+decrementing it if the function returned NULL. Effectively a successful
+hv_store_ent takes ownership of one reference to C<val>. This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, hv_store
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up. Note that hv_store_ent only reads the C<key>;
+unlike C<val> it does not take ownership of it, so maintaining the correct
+reference count on C<key> is entirely the caller's responsibility. hv_store
+is not implemented as a call to hv_store_ent, and does not create a temporary
+SV for the key, so if your key data is not already in SV form then use
+hv_store in preference to hv_store_ent.
See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
information on how to use this function on tied hashes.
=for hackers
Found in file hv.c
-=item Nullhv
-
-Null HV pointer.
-
-
-=for hackers
-Found in file hv.h
-
=back
Finds the magic pointer for type matching the SV. See C<sv_magic>.
- MAGIC* mg_find(SV* sv, int type)
+ MAGIC* mg_find(const SV* sv, int type)
=for hackers
Found in file mg.c
=item SvSetMagicSV_nosteal
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
+Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
=for hackers
Found in file sv.h
+=item SvUNLOCK
+
+Releases a mutual exclusion lock on sv if a suitable module
+has been loaded.
+
+ void SvUNLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
=back
=for hackers
Found in file handy.h
+=item CopyD
+
+Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * CopyD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
=item Move
The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
=for hackers
Found in file handy.h
+=item MoveD
+
+Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * MoveD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
=item New
The XSUB-writer's interface to the C C<malloc> function.
=for hackers
Found in file handy.h
-=item NEWSV
-
-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).
+=item Newz
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>.
- SV* NEWSV(int id, STRLEN len)
+ void Newz(int id, void* ptr, int nitems, type)
=for hackers
Found in file handy.h
-=item Newz
+=item Poison
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>.
+Fill up memory with a pattern (byte 0xAB over and over again) that
+hopefully catches attempts to access uninitialized memory.
- void Newz(int id, void* ptr, int nitems, type)
+ void Poison(void* dest, int nitems, type)
=for hackers
Found in file handy.h
=item savepv
-Copy a string to a safe spot. This does not use an SV.
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
+be freed with the C<Safefree()> function.
- char* savepv(const char* sv)
+ char* savepv(const char* pv)
=for hackers
Found in file util.c
=item savepvn
-Copy a string to a safe spot. The C<len> indicates number of bytes to
-copy. If pointer is NULL allocate space for a string of size specified.
-This does not use an SV.
+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.
- char* savepvn(const char* sv, I32 len)
+ char* savepvn(const char* pv, I32 len)
=for hackers
Found in file util.c
=item savesharedpv
-Copy a string to a safe spot in memory shared between threads.
-This does not use an SV.
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
- char* savesharedpv(const char* sv)
+ char* savesharedpv(const char* pv)
+
+=for hackers
+Found in file util.c
+
+=item savesvpv
+
+A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
+the passed in SV using C<SvPV()>
+
+ char* savesvpv(SV* sv)
=for hackers
Found in file util.c
=for hackers
Found in file handy.h
+=item ZeroD
+
+Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * ZeroD(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
=back
=for hackers
Found in file util.c
+=item 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.
+
+ SV* new_version(SV *ver)
+
+=for hackers
+Found in file util.c
+
+=item scan_version
+
+Returns a pointer to the next character after the parsed
+version string, as well as upgrading the passed in SV to
+an RV.
+
+Function must be called with an already existing SV like
+
+ sv = newSV(0);
+ 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
+should be interpreted as if it had multiple decimals, even if
+it doesn't.
+
+ char* scan_version(const char *vstr, SV *sv, bool qv)
+
+=for hackers
+Found in file util.c
+
=item strEQ
Test two strings to see if they are equal. Returns true or false.
=for hackers
Found in file handy.h
+=item sv_nolocking
+
+Dummy routine which "locks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nolocking(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nosharing
+
+Dummy routine which "shares" an SV when there is no sharing module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nosharing(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nounlocking
+
+Dummy routine which "unlocks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nounlocking(SV *)
+
+=for hackers
+Found in file util.c
+
+=item upg_version
+
+In-place upgrade of the supplied SV to a version object.
+
+ SV *sv = upg_version(SV *sv);
+
+Returns a pointer to the upgraded SV.
+
+ SV* upg_version(SV *ver)
+
+=for hackers
+Found in file util.c
+
+=item vcmp
+
+Version object aware cmp. Both operands must already have been
+converted into version objects.
+
+ int vcmp(SV *lvs, SV *rvs)
+
+=for hackers
+Found in file util.c
+
+=item vnormal
+
+Accepts a version object and returns the normalized string
+representation. Call like:
+
+ sv = vnormal(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+ SV* vnormal(SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vnumify
+
+Accepts a version object and returns the normalized floating
+point representation. Call like:
+
+ sv = vnumify(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+ SV* vnumify(SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vstringify
+
+In order to maintain maximum compatibility with earlier versions
+of Perl, this function will return either the floating point
+notation or the multiple dotted notation, depending on whether
+the original version contained 1 or more dots, respectively
+
+ SV* vstringify(SV *vs)
+
+=for hackers
+Found in file util.c
+
=back
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
-If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
-The hex number may optionally be prefixed with "0b" or "b" unless
+The binary number may optionally be prefixed with "0b" or "b" unless
C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
number may use '_' characters to separate digits.
- UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
+ UV grok_bin(const char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
Found in file numeric.c
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first non-hex-digit character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
number may use '_' characters to separate digits.
- UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
+ UV grok_hex(const char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
Found in file numeric.c
=item grok_oct
+converts a string representing an octal number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+number may use '_' characters to separate digits.
- UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
+ UV grok_oct(const char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
Found in file numeric.c
For backwards compatibility. Use C<grok_bin> instead.
- NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
+ NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
=for hackers
Found in file numeric.c
For backwards compatibility. Use C<grok_hex> instead.
- NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
+ NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
=for hackers
Found in file numeric.c
For backwards compatibility. Use C<grok_oct> instead.
- NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
+ NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
=for hackers
Found in file numeric.c
Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
eligible for inlining at compile-time.
- CV* newCONSTSUB(HV* stash, char* name, SV* sv)
+ CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
=for hackers
Found in file op.c
=back
+=head1 Pad Data Structures
+
+=over 8
+
+=item pad_sv
+
+Get the value at offset po in the current pad.
+Use macro PAD_SV instead of calling this function directly.
+
+ SV* pad_sv(PADOFFSET po)
+
+=for hackers
+Found in file pad.c
+
+
+=back
+
+=head1 Simple Exception Handling Macros
+
+=over 8
+
+=item dXCPT
+
+Set up neccessary local variables for exception handling.
+See L<perlguts/"Exception Handling">.
+
+ dXCPT;
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_CATCH
+
+Introduces a catch block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_RETHROW
+
+Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
+
+ XCPT_RETHROW;
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_TRY_END
+
+Ends a try block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_TRY_START
+
+Starts a try block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+
+=back
+
=head1 Stack Manipulation Macros
=over 8
Declares a local copy of perl's stack pointer for the XSUB, available via
the C<SP> macro. See C<SP>.
- dSP;
+ dSP;
+
+=for hackers
+Found in file pp.h
+
+=item EXTEND
+
+Used to extend the argument stack for an XSUB's return values. Once
+used, guarantees that there is room for at least C<nitems> to be pushed
+onto the stack.
+
+ void EXTEND(SP, int nitems)
+
+=for hackers
+Found in file pp.h
+
+=item MARK
+
+Stack marker variable for the XSUB. See C<dMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mXPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void mXPUSHn(NV nv)
=for hackers
Found in file pp.h
-=item EXTEND
+=item mXPUSHp
-Used to extend the argument stack for an XSUB's return values. Once
-used, guarantees that there is room for at least C<nitems> to be pushed
-onto the stack.
+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>.
- void EXTEND(SP, int nitems)
+ void mXPUSHp(char* str, STRLEN len)
=for hackers
Found in file pp.h
-=item MARK
+=item mXPUSHu
-Stack marker variable for the XSUB. See C<dMARK>.
+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>.
+
+ void mXPUSHu(UV uv)
=for hackers
Found in file pp.h
=item PUSHi
Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHi>.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
+C<mXPUSHi>.
void PUSHi(IV iv)
Opening bracket for arguments on a callback. See C<PUTBACK> and
L<perlcall>.
- PUSHMARK;
+ void PUSHMARK(SP)
+
+=for hackers
+Found in file pp.h
+
+=item 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>.
+
+ void PUSHmortal()
=for hackers
Found in file pp.h
=item PUSHn
Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHn>.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
+C<mXPUSHn>.
void PUSHn(NV nv)
=item PUSHp
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. See
-C<XPUSHp>.
+The C<len> indicates the length of the string. Handles 'set' magic. Uses
+C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
+call multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
void PUSHp(char* str, STRLEN len)
=item PUSHs
Push an SV onto the stack. The stack must have room for this element.
-Does not handle 'set' magic. See C<XPUSHs>.
+Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
+C<XPUSHs> and C<XPUSHmortal>.
void PUSHs(SV* sv)
=item PUSHu
Push an unsigned integer onto the stack. The stack must have room for this
-element. See C<XPUSHu>.
+element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
+should be called to declare it. Do not call multiple C<TARG>-oriented
+macros to return lists from XSUB's - see C<mPUSHu> instead. See also
+C<XPUSHu> and C<mXPUSHu>.
void PUSHu(UV uv)
=item XPUSHi
Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHi>.
+'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it. Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
void XPUSHi(IV iv)
=for hackers
Found in file pp.h
+=item 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>.
+
+ void XPUSHmortal()
+
+=for hackers
+Found in file pp.h
+
=item XPUSHn
Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHn>.
+'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it. Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
void XPUSHn(NV nv)
=item XPUSHp
Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. See
-C<PUSHp>.
+indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
+C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
+multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
void XPUSHp(char* str, STRLEN len)
=item XPUSHs
Push an SV onto the stack, extending the stack if necessary. Does not
-handle 'set' magic. See C<PUSHs>.
+handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
+C<PUSHs> and C<PUSHmortal>.
void XPUSHs(SV* sv)
=item XPUSHu
Push an unsigned integer onto the stack, extending the stack if necessary.
-See C<PUSHu>.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
+C<mPUSHu>.
void XPUSHu(UV uv)
=for hackers
Found in file XSUB.h
+=item XSRETURN_EMPTY
+
+Return an empty list from an XSUB immediately.
+
+ XSRETURN_EMPTY;
+
+=for hackers
+Found in file XSUB.h
+
=item XSRETURN_IV
Return an integer from an XSUB immediately. Uses C<XST_mIV>.
=for hackers
Found in file XSUB.h
+=item XSRETURN_UV
+
+Return an integer from an XSUB immediately. Uses C<XST_mUV>.
+
+ void XSRETURN_UV(IV uv)
+
+=for hackers
+Found in file XSUB.h
+
=item XSRETURN_YES
Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
=for hackers
Found in file sv.c
+=item NEWSV
+
+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).
+
+ SV* NEWSV(int id, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
=item newSV
Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
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.
+C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
SV* newSVpvn(const char* s, STRLEN len)
=for hackers
Found in file sv.c
-=item new_vstring
-
-Returns a pointer to the next character after the parsed
-vstring, as well as updating the passed in sv.
-
-Function must be called like
-
- sv = NEWSV(92,5);
- s = new_vstring(s,sv);
-
-The sv must already be large enough to store the vstring
-passed in.
-
- char* new_vstring(char *vstr, SV *sv)
-
-=for hackers
-Found in file util.c
-
=item SvCUR
Returns the length of the string which is in the SV. See C<SvLEN>.
Returns a boolean indicating whether the SV contains a signed integer.
- void SvIOK_notUV(SV* sv)
+ bool SvIOK_notUV(SV* sv)
=for hackers
Found in file sv.h
Returns a boolean indicating whether the SV contains an unsigned integer.
- void SvIOK_UV(SV* sv)
+ bool SvIOK_UV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIsCOW
+
+Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
+hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
+COW)
+
+ bool SvIsCOW(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIsCOW_shared_hash
+
+Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
+scalar.
+
+ bool SvIsCOW_shared_hash(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
+=item SvIVX
+
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvIV()>.
+
+ IV SvIVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
=item SvIVx
Coerces the given SV to an integer and returns it. Guarantees to evaluate
=for hackers
Found in file sv.h
-=item SvIVX
+=item SvIV_nomg
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
+Like C<SvIV> but doesn't process magic.
- IV SvIVX(SV* sv)
+ IV SvIV_nomg(SV* sv)
=for hackers
Found in file sv.h
=item SvOK
-Returns a boolean indicating whether the value is an SV.
+Returns a boolean indicating whether the value is an SV. It also tells
+whether the value is defined or not.
bool SvOK(SV* sv)
=item SvPOK_only
Tells an SV that it is a string and disables all other OK bits.
-Will also turn off the UTF8 status.
+Will also turn off the UTF-8 status.
void SvPOK_only(SV* sv)
=item SvPOK_only_UTF8
Tells an SV that it is a string and disables all other OK bits,
-and leaves the UTF8 status as it was.
+and leaves the UTF-8 status as it was.
void SvPOK_only_UTF8(SV* sv)
Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
otherwise.
-
char* SvPVbytex(SV* sv, STRLEN len)
=for hackers
=for hackers
Found in file sv.h
-=item SvPVx
+=item SvPVX
-A version of C<SvPV> which guarantees to evaluate sv only once.
+Returns a pointer to the physical string in the SV. The SV must contain a
+string.
- char* SvPVx(SV* sv, STRLEN len)
+ char* SvPVX(SV* sv)
=for hackers
Found in file sv.h
-=item SvPVX
+=item SvPVx
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
+A version of C<SvPV> which guarantees to evaluate sv only once.
- char* SvPVX(SV* sv)
+ char* SvPVx(SV* sv, STRLEN len)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
+=item SvPV_nomg
+
+Like C<SvPV> but doesn't process magic.
+
+ char* SvPV_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
=item SvREFCNT
Returns the value of the object's reference count.
=item SvTAINT
-Taints an SV if tainting is enabled
+Taints an SV if tainting is enabled.
void SvTAINT(SV* sv)
=item SvTAINTED_on
-Marks an SV as tainted.
+Marks an SV as tainted if tainting is enabled.
void SvTAINTED_on(SV* sv)
=for hackers
Found in file sv.h
-=item SvUNLOCK
-
-Releases a mutual exclusion lock on sv if a suitable module
-has been loaded.
-
-
- void SvUNLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
=item SvUOK
Returns a boolean indicating whether the SV contains an unsigned integer.
Returns a boolean indicating whether the SV contains UTF-8 encoded data.
- void SvUTF8(SV* sv)
+ bool SvUTF8(SV* sv)
=for hackers
Found in file sv.h
=item SvUTF8_off
-Unsets the UTF8 status of an SV.
+Unsets the UTF-8 status of an SV.
void SvUTF8_off(SV *sv)
=item SvUTF8_on
-Turn on the UTF8 status of an SV (the data is not changed, just the flag).
+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_nomg
+
+Like C<SvUV> but doesn't process magic.
+
+ UV SvUV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item 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_2bool
This function is only called on magical items, and is only used by
=for hackers
Found in file sv.c
-=item sv_2iv
+=item sv_2iv_flags
-Return the integer value of an SV, doing any necessary string conversion,
-magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
+Return the integer value of an SV, doing any necessary string
+conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
- IV sv_2iv(SV* sv)
+ IV sv_2iv_flags(SV* sv, I32 flags)
=for hackers
Found in file sv.c
Marks an existing SV as mortal. The SV will be destroyed "soon", either
by an explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
+statement boundaries. SvTEMP() is turned on which means that the SV's
+string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
+and C<sv_mortalcopy>.
SV* sv_2mortal(SV* sv)
=item sv_2pvbyte
Return a pointer to the byte-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be downgraded from UTF8 as a
+to its length. May cause the SV to be downgraded from UTF-8 as a
side-effect.
Usually accessed via the C<SvPVbyte> macro.
=item sv_2pvbyte_nolen
Return a pointer to the byte-encoded representation of the SV.
-May cause the SV to be downgraded from UTF8 as a side-effect.
+May cause the SV to be downgraded from UTF-8 as a side-effect.
Usually accessed via the C<SvPVbyte_nolen> macro.
=item sv_2pvutf8
-Return a pointer to the UTF8-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
+Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
+to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
Usually accessed via the C<SvPVutf8> macro.
=item sv_2pvutf8_nolen
-Return a pointer to the UTF8-encoded representation of the SV.
-May cause the SV to be upgraded to UTF8 as a side-effect.
+Return a pointer to the UTF-8-encoded representation of the SV.
+May cause the SV to be upgraded to UTF-8 as a side-effect.
Usually accessed via the C<SvPVutf8_nolen> macro.
=for hackers
Found in file sv.c
-=item sv_2uv
+=item sv_2uv_flags
Return the unsigned integer value of an SV, doing any necessary string
-conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
-macros.
+conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
- UV sv_2uv(SV* sv)
+ UV sv_2uv_flags(SV* sv, I32 flags)
=for hackers
Found in file sv.c
=item sv_catpv
Concatenates the string onto the end of the string which is in the SV.
-If the SV has the UTF8 status set, then the bytes appended should be
-valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
+If the SV has the UTF-8 status set, then the bytes appended should be
+valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
void sv_catpv(SV* sv, const char* ptr)
output to an SV. If the appended data contains "wide" characters
(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
-C<SvSETMAGIC()> must typically be called after calling this function
-to handle 'set' magic.
+upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
+C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
+valid UTF-8; if the original SV was bytes, the pattern should be too.
void sv_catpvf(SV* sv, const char* pat, ...)
=item sv_catpvn
Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF8
-status set, then the bytes appended should be valid UTF8.
+C<len> indicates number of bytes to copy. If the SV has the UTF-8
+status set, then the bytes appended should be valid UTF-8.
Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
=item sv_catpvn_flags
Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF8
-status set, then the bytes appended should be valid UTF8.
+C<len> indicates number of bytes to copy. If the SV has the UTF-8
+status set, then the bytes appended should be valid UTF-8.
If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
in terms of this function.
=for hackers
Found in file sv.c
+=item 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_catpv_mg
Like C<sv_catpv>, but also handles 'set' magic.
=for hackers
Found in file sv.c
+=item 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
Efficient removal of characters from the beginning of the string buffer.
SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
the string buffer. The C<ptr> becomes the first character of the adjusted
string. Uses the "OOK hack".
+Beware: after this function returns, C<ptr> and SvPVX(sv) may no longer
+refer to the same chunk of data.
void sv_chop(SV* sv, char* ptr)
Undo various types of fakery on an SV: if the PV is a shared string, make
a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
-an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
-when unrefing. C<sv_force_normal> calls this function with flags set to 0.
+an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
+we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
+then a copy-on-write scalar drops its PV buffer (if any) and becomes
+SvPOK_off rather than making a copy. (Used where this scalar is about to be
+set to some other value.) In addition, the C<flags> parameter gets passed to
+C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
+with flags set to 0.
void sv_force_normal_flags(SV *sv, U32 flags)
Inserts a string at the specified offset/length within the SV. Similar to
the Perl substr() function.
- void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
+ void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
=for hackers
Found in file sv.c
=item sv_len_utf8
Returns the number of characters in the string in an SV, counting wide
-UTF8 bytes as a single character. Handles magic and type coercion.
+UTF-8 bytes as a single character. Handles magic and type coercion.
STRLEN sv_len_utf8(SV* sv)
Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
then adds a new magic item of type C<how> to the head of the magic list.
+See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
+handling of the C<name> and C<namlen> arguments.
+
+You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
+to add more than one instance of the same 'how'.
+
void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
=for hackers
=item sv_magicext
Adds magic to an SV, upgrading it if necessary. Applies the
-supplied vtable and returns pointer to the magic added.
+supplied vtable and returns a pointer to the magic added.
-Note that sv_magicext will allow things that sv_magic will not.
-In particular you can add magic to SvREADONLY SVs and and more than
-one instance of the same 'how'
+Note that C<sv_magicext> will allow things that C<sv_magic> will not.
+In particular, you can add magic to SvREADONLY SVs, and add more than
+one instance of the same 'how'.
-I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
-if C<namelen> is zero then C<name> is stored as-is and - as another special
-case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
-an C<SV*> and has its REFCNT incremented
+If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
+stored, if C<namlen> is zero then C<name> is stored as-is and - as another
+special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
+to contain an C<SV*> and is stored as-is with its REFCNT incremented.
-(This is now used as a subroutine by sv_magic.)
+(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
=for hackers
Found in file sv.c
-=item sv_nolocking
-
-Dummy routine which "locks" an SV when there is no locking module present.
-Exists to avoid test for a NULL function pointer and because it could potentially warn under
-some level of strict-ness.
-
- void sv_nolocking(SV *)
-
-=for hackers
-Found in file util.c
-
-=item sv_nosharing
-
-Dummy routine which "shares" an SV when there is no sharing module present.
-Exists to avoid test for a NULL function pointer and because it could potentially warn under
-some level of strict-ness.
-
- void sv_nosharing(SV *)
-
-=for hackers
-Found in file util.c
-
-=item sv_nounlocking
-
-Dummy routine which "unlocks" an SV when there is no locking module present.
-Exists to avoid test for a NULL function pointer and because it could potentially warn under
-some level of strict-ness.
-
- void sv_nounlocking(SV *)
-
-=for hackers
-Found in file util.c
-
=item sv_nv
A private implementation of the C<SvNVx> macro for compilers which can't
=item sv_pos_b2u
Converts the value pointed to by offsetp from a count of bytes from the
-start of the string, to a count of the equivalent number of UTF8 chars.
+start of the string, to a count of the equivalent number of UTF-8 chars.
Handles magic and type coercion.
void sv_pos_b2u(SV* sv, I32* offsetp)
=item sv_pos_u2b
-Converts the value pointed to by offsetp from a count of UTF8 chars from
+Converts the value pointed to by offsetp from a count of UTF-8 chars from
the start of the string, to a count of the equivalent number of bytes; if
lenp is non-zero, it does the same to lenp, but this time starting from
the offset, rather than from the start of the string. Handles magic and
Returns a string describing what the SV is a reference to.
- char* sv_reftype(SV* sv, int ob)
+ char* sv_reftype(const SV* sv, int ob)
=for hackers
Found in file sv.c
Underlying implementation for the C<reset> Perl function.
Note that the perl-level function is vaguely deprecated.
- void sv_reset(char* s, HV* stash)
+ void sv_reset(const char* s, HV* stash)
=for hackers
Found in file sv.c
=item sv_setpvf
-Processes its arguments like C<sprintf> and sets an SV to the formatted
-output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
+Works like C<sv_catpvf> but copies the text into the SV instead of
+appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
void sv_setpvf(SV* sv, const char* pat, ...)
=item sv_setpvn
Copies a string into an SV. The C<len> parameter indicates the number of
-bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
+bytes to be copied. If the C<ptr> argument is NULL the SV will become
+undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
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 be returned and will have a reference count of 1.
+will have a reference count of 1, and the RV will be returned.
SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
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 be returned and will have a reference count of 1.
+will have a reference count of 1, and the RV will be returned.
SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
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
-will be returned and will have a reference count of 1.
+will have a reference count of 1, and the RV will be returned.
Do not use with other Perl types such as HV, AV, SV, CV, because those
objects will become corrupted by the pointer copy process.
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 be returned and will have
-a reference count of 1.
+C<Nullch> 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.
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 be returned and will have a reference count of 1.
+will have a reference count of 1, and the RV will be returned.
SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
C<SvSetMagicSV_nosteal>.
-
void sv_setsv(SV* dsv, SV* ssv)
=for hackers
Loosely speaking, it performs a copy-by-value, obliterating any previous
content of the destination.
If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
-C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
-implemented in terms of this function.
+C<ssv> if appropriate, else not. If the C<flags> parameter has the
+C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
+and C<sv_setsv_nomg> are implemented in terms of this function.
You probably want to use one of the assortment of wrappers, such as
C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
=for hackers
Found in file sv.c
+=item 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
Copies an unsigned integer into the given SV, upgrading first if necessary.
=item sv_utf8_decode
-Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
-turn off SvUTF8 if needed so that we see characters. Used as a building block
-for decode_utf8 in Encode.xs
+If the PV of the SV is an octet sequence in UTF-8
+and contains a multiple-byte character, the C<SvUTF8> flag is turned on
+so that it looks like a character. If the PV contains only single-byte
+characters, the C<SvUTF8> flag stays being off.
+Scans PV for validity and returns false if the PV is invalid UTF-8.
NOTE: this function is experimental and may change or be
removed without notice.
=item sv_utf8_downgrade
-Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
-This may not be possible if the PV contains non-byte encoding characters;
-if this is the case, either returns false or, if C<fail_ok> is not
+Attempts to convert the PV of an SV from characters to bytes.
+If the PV contains a character beyond byte, this conversion will fail;
+in this case, either returns false or, if C<fail_ok> is not
true, croaks.
This is not as a general purpose Unicode to byte encoding interface:
=item sv_utf8_encode
-Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
-flag so that it looks like octets again. Used as a building block
-for encode_utf8 in Encode.xs
+Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
+flag off so that it looks like octets again.
void sv_utf8_encode(SV *sv)
=item sv_utf8_upgrade
-Convert the PV of an SV to its UTF8-encoded form.
+Converts the PV of an SV to its UTF-8-encoded form.
Forces the SV to string form if it is not already.
Always sets the SvUTF8 flag to avoid future validity checks even
if all the bytes have hibit clear.
=item sv_utf8_upgrade_flags
-Convert the PV of an SV to its UTF8-encoded form.
+Converts the PV of an SV to its UTF-8-encoded form.
Forces the SV to string form if it is not already.
Always sets the SvUTF8 flag to avoid future validity checks even
if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
=for hackers
Found in file sv.c
+=item sv_vcatpvf
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
+
+Usually used via its frontend C<sv_catpvf>.
+
+ void sv_vcatpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
=item sv_vcatpvfn
Processes its arguments like C<vsprintf> and appends the formatted output
C<maybe_tainted> if results are untrustworthy (often due to the use of
locales).
-Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
+Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
=for hackers
Found in file sv.c
+=item sv_vcatpvf_mg
+
+Like C<sv_vcatpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_catpvf_mg>.
+
+ void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvf
+
+Works like C<sv_vcatpvf> but copies the text into the SV instead of
+appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
+
+Usually used via its frontend C<sv_setpvf>.
+
+ void sv_vsetpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
=item sv_vsetpvfn
-Works like C<vcatpvfn> but copies the text into the SV instead of
+Works like C<sv_vcatpvfn> but copies the text into the SV instead of
appending it.
-Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
=for hackers
Found in file sv.c
+=item sv_vsetpvf_mg
+
+Like C<sv_vsetpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_setpvf_mg>.
+
+ void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
=back
=item bytes_from_utf8
-Converts a string C<s> of length C<len> from UTF8 into byte encoding.
-Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
+Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
+Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
the newly-created string, and updates C<len> to contain the new
length. Returns the original string if no conversion occurs, C<len>
is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
NOTE: this function is experimental and may change or be
removed without notice.
- U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
+ U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
=for hackers
Found in file utf8.c
=item bytes_to_utf8
-Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
+Converts a string C<s> of length C<len> from ASCII into UTF-8 encoding.
Returns a pointer to the newly-created string, and sets C<len> to
reflect the new length.
+If you want to convert to UTF-8 from other encodings than ASCII,
+see sv_recode_to_utf8().
+
NOTE: this function is experimental and may change or be
removed without notice.
- U8* bytes_to_utf8(U8 *s, STRLEN *len)
+ U8* bytes_to_utf8(const U8 *s, STRLEN *len)
=for hackers
Found in file utf8.c
in there (they will point at the beginning of the I<next> character).
If the pointers behind pe1 or pe2 are non-NULL, they are the end
pointers beyond which scanning will not continue under any
-circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
+circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
s2+l2 will be used as goal end pointers that will also stop the scan,
and which qualify towards defining a successful match: all the scans
that define an explicit length must reach their goal pointers for
=item is_utf8_char
Tests if some arbitrary number of bytes begins in a valid UTF-8
-character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
-The actual number of bytes in the UTF-8 character will be returned if
-it is valid, otherwise 0.
+character. Note that an INVARIANT (i.e. ASCII) character is a valid
+UTF-8 character. The actual number of bytes in the UTF-8 character
+will be returned if it is valid, otherwise 0.
- STRLEN is_utf8_char(U8 *p)
+ STRLEN is_utf8_char(const U8 *p)
=for hackers
Found in file utf8.c
=item is_utf8_string
-Returns true if first C<len> bytes of the given string form a valid UTF8
-string, false otherwise. Note that 'a valid UTF8 string' does not mean
-'a string that contains UTF8' because a valid ASCII string is a valid
-UTF8 string.
+Returns true if first C<len> bytes of the given string form a valid
+UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
+not mean 'a string that contains code points above 0x7F encoded in UTF-8'
+because a valid ASCII string is a valid UTF-8 string.
+
+ bool is_utf8_string(const U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string_loc
- bool is_utf8_string(U8 *s, STRLEN len)
+Like is_ut8_string but store the location of the failure in
+the last argument.
+
+ bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
=for hackers
Found in file utf8.c
The pointer to the PV of the dsv is returned.
- char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
+ char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
=for hackers
Found in file utf8.c
+=item sv_cat_decode
+
+The encoding is assumed to be an Encode object, the PV of the ssv is
+assumed to be octets in that encoding and decoding the input starts
+from the position which (PV + *offset) pointed to. The dsv will be
+concatenated the decoded UTF-8 string from ssv. Decoding will terminate
+when the string tstr appears in decoding output or the input ends on
+the PV of the ssv. The value which the offset points will be modified
+to the last input position on the ssv.
+
+Returns TRUE if the terminator was found, else returns FALSE.
+
+ bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
+
+=for hackers
+Found in file sv.c
+
=item sv_recode_to_utf8
The encoding is assumed to be an Encode object, on entry the PV
The "normal" is a string like "ToLower" which means the swash
%utf8::ToLower.
- UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
+ UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, const char *normal, const char *special)
=for hackers
Found in file utf8.c
Convert the UTF-8 encoded character at p to its foldcase version and
store that in UTF-8 in ustrp and its length in bytes in lenp. Note
-that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
foldcase version may be longer than the original character (up to
three characters).
The first character of the foldcased version is returned
(but note, as explained above, that there may be more.)
- UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
+ UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
Convert the UTF-8 encoded character at p to its lowercase version and
store that in UTF-8 in ustrp and its length in bytes in lenp. Note
-that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
-lowercase version may be longer than the original character (up to two
-characters).
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
+lowercase version may be longer than the original character.
The first character of the lowercased version is returned
(but note, as explained above, that there may be more.)
- UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
+ UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
Convert the UTF-8 encoded character at p to its titlecase version and
store that in UTF-8 in ustrp and its length in bytes in lenp. Note
-that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
-titlecase version may be longer than the original character (up to two
-characters).
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
+titlecase version may be longer than the original character.
The first character of the titlecased version is returned
(but note, as explained above, that there may be more.)
- UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
+ UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
Convert the UTF-8 encoded character at p to its uppercase version and
store that in UTF-8 in ustrp and its length in bytes in lenp. Note
-that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
-uppercase version may be longer than the original character (up to two
-characters).
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
+the uppercase version may be longer than the original character.
The first character of the uppercased version is returned
(but note, as explained above, that there may be more.)
- UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
+ UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
=item utf8n_to_uvchr
Returns the native character value of the first character in the string C<s>
-which is assumed to be in UTF8 encoding; C<retlen> will be set to the
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
length, in bytes, of that character.
Allows length and flags to be passed to low level routine.
- UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
+ UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
=for hackers
Found in file utf8.c
Bottom level UTF-8 decode routine.
Returns the unicode code point value of the first character in the string C<s>
-which is assumed to be in UTF8 encoding and no longer than C<curlen>;
+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.
-If C<s> does not point to a well-formed UTF8 character, the behaviour
+If C<s> does not point to a well-formed UTF-8 character, the behaviour
is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
it is assumed that the caller will raise a warning, and this function
will silently just set C<retlen> to C<-1> and return zero. If the
Most code should use utf8_to_uvchr() rather than call this directly.
- UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
+ UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
=for hackers
Found in file utf8.c
=item utf8_distance
-Returns the number of UTF8 characters between the UTF-8 pointers C<a>
+Returns the number of UTF
-8 characters between the UTF-8 pointers C<a>
and C<b>.
WARNING: use only if you *know* that the pointers point inside the
same UTF-8 buffer.
- IV utf8_distance(U8 *a, U8 *b)
+ IV utf8_distance(const U8 *a, const U8 *b)
=for hackers
Found in file utf8.c
Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
up past C<e>, croaks.
- STRLEN utf8_length(U8* s, U8 *e)
+ STRLEN utf8_length(const U8* s, const U8 *e)
=for hackers
Found in file utf8.c
=item utf8_to_bytes
-Converts a string C<s> of length C<len> from UTF8 into byte encoding.
+Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
Unlike C<bytes_to_utf8>, this over-writes the original string, and
updates len to contain the new length.
Returns zero on failure, setting C<len> to -1.
=item utf8_to_uvchr
Returns the native character value of the first character in the string C<s>
-which is assumed to be in UTF8 encoding; C<retlen> will be set to the
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
length, in bytes, of that character.
-If C<s> does not point to a well-formed UTF8 character, zero is
+If C<s> does not point to a well-formed UTF-8 character, zero is
returned and retlen is set, if possible, to -1.
- UV utf8_to_uvchr(U8 *s, STRLEN* retlen)
+ UV utf8_to_uvchr(const U8 *s, STRLEN* retlen)
=for hackers
Found in file utf8.c
=item utf8_to_uvuni
Returns the Unicode code point of the first character in the string C<s>
-which is assumed to be in UTF8 encoding; C<retlen> will be set to the
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
length, in bytes, of that character.
This function should only be used when returned UV is considered
an index into the Unicode semantic tables (e.g. swashes).
-If C<s> does not point to a well-formed UTF8 character, zero is
+If C<s> does not point to a well-formed UTF-8 character, zero is
returned and retlen is set, if possible, to -1.
- UV utf8_to_uvuni(U8 *s, STRLEN* retlen)
+ UV utf8_to_uvuni(const U8 *s, STRLEN* retlen)
=for hackers
Found in file utf8.c
=item uvchr_to_utf8
-Adds the UTF8 representation of the Native codepoint C<uv> to the end
-of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
+Adds the UTF-8 representation of the Native codepoint C<uv> to the end
+of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
bytes available. The return value is the pointer to the byte after the
end of the new character. In other words,
=item uvuni_to_utf8_flags
-Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
-of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
+Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
+of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
bytes available. The return value is the pointer to the byte after the
end of the new character. In other words,
=for hackers
Found in file XSUB.h
+=item dAXMARK
+
+Sets up the C<ax> variable and stack marker variable C<mark>.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+ dAXMARK;
+
+=for hackers
+Found in file XSUB.h
+
=item dITEMS
Sets up the C<items> variable.
=for hackers
Found in file XSUB.h
+=item dUNDERBAR
+
+Sets up the C<padoff_du> variable for an XSUB that wishes to use
+C<UNDERBAR>.
+
+ dUNDERBAR;
+
+=for hackers
+Found in file XSUB.h
+
=item dXSARGS
Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
=for hackers
Found in file XSUB.h
-=item XS
+=item UNDERBAR
-Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>.
+The SV* corresponding to the $_ variable. Works even if there
+is a lexical $_ in scope.
=for hackers
Found in file XSUB.h
-=item XSRETURN_EMPTY
-
-Return an empty list from an XSUB immediately.
-
+=item XS
- XSRETURN_EMPTY;
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
=for hackers
Found in file XSUB.h
=item croak
This is the XSUB-writer's interface to Perl's C<die> function.
-Normally use this function the same way you use the C C<printf>
-function. See C<warn>.
+Normally call this function the same way you call the C C<printf>
+function. Calling C<croak> returns control directly to Perl,
+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():
=item warn
-This is the XSUB-writer's interface to Perl's C<warn> function. Use this
-function the same way you use the C C<printf> function. See
-C<croak>.
+This is the XSUB-writer's interface to Perl's C<warn> function. Call this
+function the same way you call the C C<printf> function. See C<croak>.
void warn(const char* pat, ...)
https://perl5.git.perl.org / perl5.git / blobdiff