Removes 'the' in front of parameter names in some instances.
=for apidoc AmU||XS
Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>. It is the same as using the more explicit XS_EXTERNAL macro.
+C<xsubpp>. It is the same as using the more explicit C<XS_EXTERNAL> macro.
=for apidoc AmU||XS_INTERNAL
Macro to declare an XSUB and its C parameter list without exporting the symbols.
This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
=for apidoc Ams||dXSARGS
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up stack and mark pointers for an XSUB, calling C<dSP> and C<dMARK>.
Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
This is usually handled automatically by C<xsubpp>.
to still use it for ensuring past and future compatibility.
=for apidoc AmU||UNDERBAR
-The SV* corresponding to the $_ variable. Works even if there
-is a lexical $_ in scope.
+The SV* corresponding to the C<$_> variable. Works even if there
+is a lexical C<$_> in scope.
=cut
*/
C<L</XS_VERSION_BOOTCHECK>>.
=for apidoc Ams||XS_VERSION_BOOTCHECK
-Macro to verify that a PM module's $VERSION variable matches the XS
+Macro to verify that a PM module's C<$VERSION> variable matches the XS
module's C<XS_VERSION> variable. This is usually handled automatically by
C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
=for apidoc av_store
Stores an SV in an array. The array index is specified as C<key>. The
-return value will be NULL if the operation failed or if the value did not
+return value will be C<NULL> if the operation failed or if the value did not
need to be actually stored within the array (as in the case of tied
arrays). Otherwise, it can be dereferenced
to get the C<SV*> that was stored
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.
+returned C<NULL>.
Approximate Perl equivalent: C<$myarray[$key] = $val;>.
=for apidoc av_make
Creates a new AV and populates it with a list of SVs. The SVs are copied
-into the array, so they may be freed after the call to av_make. The new AV
+into the array, so they may be freed after the call to C<av_make>. The new AV
will have a reference count of 1.
Perl equivalent: C<my @new_array = ($scalar1, $scalar2, $scalar3...);>
/*
=for apidoc av_clear
-Clears an array, making it empty. Does not free the memory the av uses to
+Clears an array, making it empty. Does not free the memory C<av> uses to
store its list of scalars. If any destructors are triggered as a result,
-the av itself may be freed when this function returns.
+C<av> itself may be freed when this function returns.
Perl equivalent: C<@myarray = ();>.
=for apidoc av_undef
Undefines the array. Frees the memory used by the av to store its list of
-scalars. If any destructors are triggered as a result, the av itself may
+scalars. If any destructors are triggered as a result, C<av> itself may
be freed.
=cut
Perl's C<$#array = $fill;>.
The number of elements in the array will be C<fill + 1> after
-av_fill() returns. If the array was previously shorter, then the
+C<av_fill()> returns. If the array was previously shorter, then the
additional elements appended are set to NULL. If the array
was longer, then the excess elements are freed. C<av_fill(av, -1)> is
the same as C<av_clear(av)>.
Returns true if the element indexed by C<key> has been initialized.
This relies on the fact that uninitialized array elements are set to
-NULL.
+C<NULL>.
Perl equivalent: C<exists($myarray[$key])>.
/*
=for apidoc pv_escape
-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
+Escapes at most the first C<count> chars of C<pv> and puts the results into
+C<dsv> such that the size of the escaped string will not exceed C<max> chars
and will not contain any incomplete escape sequences. The number of bytes
-escaped will be returned in the STRLEN *escaped parameter if it is not null.
-When the dsv parameter is null no escaping actually occurs, but the number
+escaped will be returned in the C<STRLEN *escaped> parameter if it is not null.
+When the C<dsv> parameter is null no escaping actually occurs, but the number
of bytes that would be escaped were it not null will be calculated.
-If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
+If flags contains C<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.
+but when C<PERL_PV_ESCAPE_NOCLEAR> is set this will not occur.
-If PERL_PV_ESCAPE_UNI is set then the input string is treated as UTF-8
-if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
+If C<PERL_PV_ESCAPE_UNI> is set then the input string is treated as UTF-8
+if C<PERL_PV_ESCAPE_UNI_DETECT> is set then the input string is scanned
using C<is_utf8_string()> to determine if it is UTF-8.
-If PERL_PV_ESCAPE_ALL is set then all input chars will be output
-using C<\x01F1> style escapes, otherwise if PERL_PV_ESCAPE_NONASCII is set, only
+If C<PERL_PV_ESCAPE_ALL> is set then all input chars will be output
+using C<\x01F1> style escapes, otherwise if C<PERL_PV_ESCAPE_NONASCII> is set, only
non-ASCII chars will be escaped using this style; otherwise, only chars above
255 will be so escaped; other non printable chars will use octal or
common escaped patterns like C<\n>.
-Otherwise, if PERL_PV_ESCAPE_NOBACKSLASH
+Otherwise, if C<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
+If C<PERL_PV_ESCAPE_FIRSTCHAR> is set then only the first char of the
string will be escaped, regardless of max. If the output is to be in hex,
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 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.
+If C<PERL_PV_ESCAPE_RE> is set then the escape char used will be a C<"%"> and
+not a C<"\\">. This is because regexes very often contain backslashed
+sequences, whereas C<"%"> is not a particularly common character in patterns.
-Returns a pointer to the escaped text as held by dsv.
+Returns a pointer to the escaped text as held by C<dsv>.
=cut
*/
=for apidoc pv_pretty
Converts a string into something presentable, handling escaping via
-pv_escape() and supporting quoting and ellipses.
+C<pv_escape()> and supporting quoting and ellipses.
-If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
+If the C<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
+if the C<PERL_PV_PRETTY_LTGT> flag is set then the result be wrapped in
angle brackets.
-If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
+If the C<PERL_PV_PRETTY_ELLIPSES> flag is set and not all characters in
string were output then an ellipsis C<...> will be appended to the
string. Note that this happens AFTER it has been quoted.
-If start_color is non-null then it will be inserted after the opening
-quote (if there is one) but before the escaped text. If end_color
+If C<start_color> is non-null then it will be inserted after the opening
+quote (if there is one) but before the escaped text. If C<end_color>
is non-null then it will be inserted after the escaped text but before
any quotes or ellipses.
-Returns a pointer to the prettified text as held by dsv.
+Returns a pointer to the prettified text as held by C<dsv>.
=cut
*/
# mro.pm versions < 1.00 reserved for MRO::Compat
# for partial back-compat to 5.[68].x
-our $VERSION = '1.17';
+our $VERSION = '1.18';
sub import {
mro::set_mro(scalar(caller), $_[1]) if $_[1];
/*
=for apidoc mro_get_linear_isa_c3
-Returns the C3 linearization of @ISA
+Returns the C3 linearization of C<@ISA>
the given stash. The return value is a read-only AV*.
C<level> should be 0 (it is used internally in this
function's recursion).
If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
inlining, or C<gv> is a placeholder reference that would be promoted to such
a typeglob, then returns the value returned by the sub. Otherwise, returns
-NULL.
+C<NULL>.
=cut
*/
Converts a scalar into a typeglob. This is an incoercible typeglob;
assigning a reference to it will assign to one of its slots, instead of
-overwriting it as happens with typeglobs created by SvSetSV. Converting
-any scalar that is SvOK() may produce unpredictable results and is reserved
+overwriting it as happens with typeglobs created by C<SvSetSV>. Converting
+any scalar that is C<SvOK()> may produce unpredictable results and is reserved
for perl's internal use.
C<gv> is the scalar to be converted.
passed to this function matches the name of the element. If it does not
match, perl's internal bookkeeping will get out of sync.
-C<flags> can be set to SVf_UTF8 if C<name> is a UTF8 string, or
+C<flags> can be set to C<SVf_UTF8> if C<name> is a UTF8 string, or
the return value of SvUTF8(sv). It can also take the
-GV_ADDMULTI flag, which means to pretend that the GV has been
+C<GV_ADDMULTI> flag, which means to pretend that the GV has been
seen before (i.e., suppress "Used once" warnings).
=for apidoc gv_init
-The old form of gv_init_pvn(). It does not work with UTF8 strings, as it
+The old form of C<gv_init_pvn()>. It does not work with UTF8 strings, as it
has no flags parameter. If the C<multi> parameter is set, the
-GV_ADDMULTI flag will be passed to gv_init_pvn().
+C<GV_ADDMULTI> flag will be passed to C<gv_init_pvn()>.
=for apidoc gv_init_pv
-Same as gv_init_pvn(), but takes a nul-terminated string for the name
+Same as C<gv_init_pvn()>, but takes a nul-terminated string for the name
instead of separate char * and length parameters.
=for apidoc gv_init_sv
-Same as gv_init_pvn(), but takes an SV * for the name instead of separate
+Same as C<gv_init_pvn()>, but takes an SV * for the name instead of separate
char * and length parameters. C<flags> is currently unused.
=cut
Returns the glob with the given C<name> and a defined subroutine or
C<NULL>. The glob lives in the given C<stash>, or in the stashes
-accessible via @ISA and UNIVERSAL::.
+accessible via C<@ISA> and C<UNIVERSAL::>.
The argument C<level> should be either 0 or -1. If C<level==0>, as a
side-effect creates a glob with the given C<name> in the given C<stash>
which in the case of success contains an alias for the subroutine, and sets
up caching info for this glob.
-The only significant values for C<flags> are GV_SUPER and SVf_UTF8.
+The only significant values for C<flags> are C<GV_SUPER> and C<SVf_UTF8>.
-GV_SUPER indicates that we want to look up the method in the superclasses
+C<GV_SUPER> indicates that we want to look up the method in the superclasses
of the C<stash>.
The
/*
=for apidoc gv_fetchmeth_pvn_autoload
-Same as gv_fetchmeth_pvn(), but looks for autoloaded subroutines too.
+Same as C<gv_fetchmeth_pvn()>, but looks for autoloaded subroutines too.
Returns a glob for the subroutine.
For an autoloaded subroutine without a GV, will create a GV even
-if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
+if C<level < 0>. For an autoloaded subroutine without a stub, C<GvCV()>
of the result may be zero.
-Currently, the only significant value for C<flags> is SVf_UTF8.
+Currently, the only significant value for C<flags> is C<SVf_UTF8>.
=cut
*/
Returns the glob which contains the subroutine to call to invoke the method
on the C<stash>. In fact in the presence of autoloading this may be the
-glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
+glob for "AUTOLOAD". In this case the corresponding variable C<$AUTOLOAD> is
already setup.
The third parameter of C<gv_fetchmethod_autoload> determines whether
as a prefix of the method name. Note
that if you want to keep the returned glob for a long time, you need to
check for it being "AUTOLOAD", since at the later time the call may load a
-different subroutine due to $AUTOLOAD changing its value. Use the glob
+different subroutine due to C<$AUTOLOAD> changing its value. Use the glob
created as a side effect to do this.
These functions have the same side-effects as C<gv_fetchmeth> with
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
+C<flags> is 0 (or any other setting that does not create packages) then C<NULL>
is returned.
Flags may be one of:
GV_NOEXPAND
GV_ADDMG
-The most important of which are probably GV_ADD and SVf_UTF8.
+The most important of which are probably C<GV_ADD> and C<SVf_UTF8>.
Note, use of C<gv_stashsv> instead of C<gv_stashpvn> where possible is strongly
recommended for performance reasons.
C<type> is the type. Can do overlapping moves. See also C<L</Copy>>.
=for apidoc Am|void *|MoveD|void* src|void* dest|int nitems|type
-Like C<Move> but returns dest. Useful
+Like C<Move> but returns C<dest>. Useful
for encouraging compilers to tail-call
optimise.
=for apidoc Am|void *|CopyD|void* src|void* dest|int nitems|type
-Like C<Copy> but returns dest. Useful
+Like C<Copy> but returns C<dest>. Useful
for encouraging compilers to tail-call
optimise.
Perl will compute it.
The return value will be
-NULL if the operation failed or if the value did not need to be actually
+C<NULL> if the operation failed or if the value did not need to be actually
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. Effectively
-a successful hv_store takes ownership of one reference to C<val>. This is
+the call, and decrementing it if the function returned C<NULL>. Effectively
+a successful C<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
+if all your code does is create SVs then store them in a hash, C<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.
+anything further to tidy up. C<hv_store> is not implemented as a call to
+C<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 C<hv_store> in preference to
+C<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.
Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
parameter is the precomputed hash value; if it is zero then Perl will
compute it. The return value is the new hash entry so created. It will be
-NULL if the operation failed or if the value did not need to be actually
+C<NULL> if the operation failed or if the value did not need to be actually
stored within the hash (as in the case of tied hashes). Otherwise the
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. Effectively a successful
-hv_store_ent takes ownership of one reference to C<val>. This is
+C<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
+if all your code does is create SVs then store them in a hash, C<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>;
+anything further to tidy up. Note that C<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
+reference count on C<key> is entirely the caller's responsibility. C<hv_store>
+is not implemented as a call to C<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.
+C<hv_store> in preference to C<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.
the hash, made mortal, and returned to the caller. The absolute
value of C<klen> is the length of the key. If C<klen> is negative the
key is assumed to be in UTF-8-encoded Unicode. The C<flags> value
-will normally be zero; if set to G_DISCARD then NULL will be returned.
-NULL will also be returned if the key is not found.
+will normally be zero; if set to C<G_DISCARD> then C<NULL> will be returned.
+C<NULL> will also be returned if the key is not found.
=for apidoc hv_delete_ent
Deletes a key/value pair in the hash. The value SV is removed from the hash,
made mortal, and returned to the caller. The C<flags> value will normally be
-zero; if set to G_DISCARD then NULL will be returned. NULL will also be
-returned if the key is not found. C<hash> can be a valid precomputed hash
+zero; if set to C<G_DISCARD> then C<NULL> will be returned. C<NULL> will also
+be returned if the key is not found. C<hash> can be a valid precomputed hash
value, or 0 to ask for it to be computed.
=cut
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
+deleted but is marked by assigning it a value of C<&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.
+See C<L<Hash::Util::lock_keys()|Hash::Util/lock_keys>> for an example of its
+use.
=cut
*/
Undefines the hash. The XS equivalent of C<undef(%hash)>.
-As well as freeing all the elements of the hash (like hv_clear()), this
+As well as freeing all the elements of the hash (like C<hv_clear()>), this
also frees any auxiliary data and storage associated with the hash.
If any destructors are triggered as a result, the hv itself may
Returns entries from a hash iterator. See C<L</hv_iterinit>> and
C<L</hv_iternext>>.
-The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+The C<flags> value will normally be zero; if C<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
=head1 Hash Manipulation Functions
=for apidoc Am|char*|HvNAME|HV* stash
-Returns the package name of a stash, or NULL if C<stash> isn't a stash.
+Returns the package name of a stash, or C<NULL> if C<stash> isn't a stash.
See C<L</SvSTASH>>, C<L</CvSTASH>>.
=for apidoc Am|STRLEN|HvNAMELEN|HV *stash
=for apidoc AiR|bool|is_safe_syscall|const char *pv|STRLEN len|const char *what|const char *op_name
Test that the given C<pv> doesn't contain any internal C<NUL> characters.
-If it does, set C<errno> to ENOENT, optionally warn, and return FALSE.
+If it does, set C<errno> to C<ENOENT>, optionally warn, and return FALSE.
Return TRUE if the name is safe.
-Used by the IS_SAFE_SYSCALL() macro.
+Used by the C<IS_SAFE_SYSCALL()> macro.
=cut
*/
=for apidoc mn|bool|PL_dowarn
-The C variable which corresponds to Perl's $^W warning variable.
+The C variable which corresponds to Perl's C<$^W> warning variable.
=cut
*/
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. See also C<L</sv_force_normal_flags>>.
+an C<xpvmg>. See also C<L</sv_force_normal_flags>>.
=cut
*/
=for apidoc 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
+Exists to avoid test for a C<NULL> function pointer and because it could
potentially warn under some level of strict-ness.
-"Superseded" by sv_nosharing().
+"Superseded" by C<sv_nosharing()>.
=cut
*/
=for apidoc 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
+Exists to avoid test for a C<NULL> function pointer and because it could
potentially warn under some level of strict-ness.
-"Superseded" by sv_nosharing().
+"Superseded" by C<sv_nosharing()>.
=cut
*/
/*
=for apidoc 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.
+The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>,
+C<new_s> and C<ocnt> are not used. This call should not be used, use
+C<unpackstring> instead.
=cut */
/*
=for apidoc 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.
+The engine implementing C<pack()> Perl function. Note: parameters
+C<next_in_list> and C<flags> are not used. This call should not be used; use
+C<packlist> instead.
=cut
*/
/*
=for apidoc custom_op_name
-Return the name for a given custom op. This was once used by the OP_NAME
+Return the name for a given custom op. This was once used by the C<OP_NAME>
macro, but is no longer: it has only been kept for compatibility, and
should not be used.
=for apidoc custom_op_desc
Return the description of a given custom op. This was once used by the
-OP_DESC macro, but is no longer: it has only been kept for
+C<OP_DESC> macro, but is no longer: it has only been kept for
compatibility, and should not be used.
=cut
If C<s> points to one of the detected malformations, and UTF8 warnings are
enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
-NULL) to -1. If those warnings are off, the computed value if well-defined (or
+C<NULL>) to -1. If those warnings are off, the computed value if well-defined (or
the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
next possible position in C<s> that could begin a non-malformed character.
=for apidoc mg_get
Do magic before a value is retrieved from the SV. The type of SV must
-be >= SVt_PVMG. See C<L</sv_magic>>.
+be >= C<SVt_PVMG>. See C<L</sv_magic>>.
=cut
*/
=for apidoc mg_length
Reports on the SV's length in bytes, calling length magic if available,
-but does not set the UTF8 flag on the sv. It will fall back to 'get'
+but does not set the UTF8 flag on C<sv>. It will fall back to 'get'
magic if there is no 'length' magic, but with no indication as to
-whether it called 'get' magic. It assumes the sv is a PVMG or
-higher. Use sv_len() instead.
+whether it called 'get' magic. It assumes C<sv> is a C<PVMG> or
+higher. Use C<sv_len()> instead.
=cut
*/
/*
=for apidoc mg_find
-Finds the magic pointer for type matching the SV. See C<L</sv_magic>>.
+Finds the magic pointer for C<type> matching the SV. See C<L</sv_magic>>.
=cut
*/
=for apidoc mg_localize
Copy some of the magic from an existing SV to new localized version of that
-SV. Container magic (eg %ENV, $1, tie)
+SV. Container magic (eg C<%ENV>, C<$1>, C<tie>)
gets copied, value magic doesn't (eg
-taint, pos).
+C<taint>, C<pos>).
-If setmagic is false then no set magic will be called on the new (empty) SV.
-This typically means that assignment will soon follow (e.g. 'local $x = $y'),
+If C<setmagic> is false then no set magic will be called on the new (empty) SV.
+This typically means that assignment will soon follow (e.g. C<'local $x = $y'>),
and that will handle the magic.
=cut
The arguments themselves are any values following the C<flags> argument.
-Returns the SV (if any) returned by the method, or NULL on failure.
+Returns the SV (if any) returned by the method, or C<NULL> on failure.
=cut
/*
=for apidoc magic_sethint
-Triggered by a store to %^H, records the key/value pair to
+Triggered by a store to C<%^H>, records the key/value pair to
C<PL_compiling.cop_hints_hash>. It is assumed that hints aren't storing
anything that would need a deep copy. Maybe we should warn if we find a
reference.
/*
=for apidoc magic_clearhint
-Triggered by a delete from %^H, records the key to
+Triggered by a delete from C<%^H>, records the key to
C<PL_compiling.cop_hints_hash>.
=cut
/*
=for apidoc magic_clearhints
-Triggered by clearing
%^H, resets C<PL_compiling.cop_hints_hash>.
+Triggered by clearing
C<%^H>, resets C<PL_compiling.cop_hints_hash>.
=cut
*/
/*
=for apidoc mro_get_linear_isa_dfs
-Returns the Depth-First Search linearization of @ISA
+Returns the Depth-First Search linearization of C<@ISA>
the given stash. The return value is a read-only AV*.
C<level> should be 0 (it is used internally in this
function's recursion).
=for apidoc mro_isa_changed_in
Takes the necessary steps (cache invalidations, mostly)
-when the @ISA of the given package has changed. Invoked
+when the C<@ISA> of the given package has changed. Invoked
by the C<setisa> magic, should not need to invoke directly.
=cut
converts a string representing a binary number to numeric form.
On entry C<start> and C<*len> give the string to scan, C<*flags> gives
-conversion flags, and C<result> should be NULL or a pointer to an NV.
+conversion flags, and C<result> should be C<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 C<*flags>, encountering an
invalid character will also trigger a warning.
and C<*flags> gives output flags.
If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
-and nothing is written to C<*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 nothing is written to C<*result>. If the value is > C<UV_MAX>, C<grok_bin>
+returns
C<UV_MAX>, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to C<*result> (or the value is discarded if C<result>
is NULL).
-The binary number may optionally be prefixed with "0b" or "b" unless
+The binary number may optionally be prefixed with C<"0b"> or C<"b"> unless
C<PERL_SCAN_DISALLOW_PREFIX> is set in C<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the binary
-number may use '_' characters to separate digits.
+number may use C<"_"> characters to separate digits.
=cut
converts a string representing a hex number to numeric form.
On entry C<start> and C<*len_p> give the string to scan, C<*flags> gives
-conversion flags, and C<result> should be NULL or a pointer to an NV.
+conversion flags, and C<result> should be C<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 C<*flags>, encountering an
invalid character will also trigger a warning.
On return C<*len> is set to the length of the scanned string,
and C<*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 C<*result>. If the value is > UV_MAX C<grok_hex>
-returns
UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
+and nothing is written to C<*result>. If the value is > C<UV_MAX>, C<grok_hex>
+returns
C<UV_MAX>, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to C<*result> (or the value is discarded if C<result>
-is NULL).
+is C<NULL>).
-The hex number may optionally be prefixed with "0x" or "x" unless
+The hex number may optionally be prefixed with C<"0x"> or C<"x"> unless
C<PERL_SCAN_DISALLOW_PREFIX> is set in C<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the hex
-number may use '_' characters to separate digits.
+number may use C<"_"> characters to separate digits.
=cut
converts a string representing an octal number to numeric form.
On entry C<start> and C<*len> give the string to scan, C<*flags> gives
-conversion flags, and C<result> should be NULL or a pointer to an NV.
+conversion flags, and C<result> should be C<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 C<*flags>, encountering an
8 or 9 will also trigger a warning.
On return C<*len> is set to the length of the scanned string,
and C<*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 C<*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,
+If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
+and nothing is written to C<*result>. If the value is > C<UV_MAX>, C<grok_oct>
+returns
C<UV_MAX>, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to C<*result> (or the value is discarded if C<result>
-is NULL).
+is C<NULL>).
If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in C<*flags> then the octal
-number may use '_' characters to separate digits.
+number may use C<"_"> characters to separate digits.
=cut
/*
=for apidoc grok_infnan
-Helper for grok_number(), accepts various ways of spelling "infinity"
+Helper for C<grok_number()>, accepts various ways of spelling "infinity"
or "not a number", and returns one of the following flag combinations:
IS_NUMBER_INFINITE
IS_NUMBER_NAN | IS_NUMBER_NEG
0
-possibly |-ed with IS_NUMBER_TRAILING.
+possibly |-ed with C<IS_NUMBER_TRAILING>.
-If an infinity or a not-a-number is recognized, the *sp will point to
+If an infinity or a not-a-number is recognized, C<*sp> will point to
one byte past the end of the recognized string. If the recognition fails,
-zero is returned, and the *sp will not move.
+zero is returned, and C<*sp> will not move.
=cut
*/
Recognise (or not) a number. The type of the number is returned
(0 if unrecognised), otherwise it is a bit-ORed combination of
-IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
-IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in F<perl.h>).
-
-If the value of the number can fit in a UV, it is returned in the *valuep
-IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
-will never be set unless *valuep is valid, but *valuep may have been assigned
-to during processing even though IS_NUMBER_IN_UV is not set on return.
-If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
-valuep is non-NULL, but no actual assignment (or SEGV) will occur.
-
-IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
-seen (in which case *valuep gives the true value truncated to an integer), and
-IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
-absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
+C<IS_NUMBER_IN_UV>, C<IS_NUMBER_GREATER_THAN_UV_MAX>, C<IS_NUMBER_NOT_INT>,
+C<IS_NUMBER_NEG>, C<IS_NUMBER_INFINITY>, C<IS_NUMBER_NAN> (defined in perl.h).
+
+If the value of the number can fit in a UV, it is returned in C<*valuep>.
+C<IS_NUMBER_IN_UV> will be set to indicate that C<*valuep> is valid, C<IS_NUMBER_IN_UV>
+will never be set unless C<*valuep> is valid, but C<*valuep> may have been assigned
+to during processing even though C<IS_NUMBER_IN_UV> is not set on return.
+If C<valuep> is C<NULL>, C<IS_NUMBER_IN_UV> will be set for the same cases as when
+C<valuep> is non-C<NULL>, but no actual assignment (or SEGV) will occur.
+
+C<IS_NUMBER_NOT_INT> will be set with C<IS_NUMBER_IN_UV> if trailing decimals were
+seen (in which case C<*valuep> gives the true value truncated to an integer), and
+C<IS_NUMBER_NEG> if the number is negative (in which case C<*valuep> holds the
+absolute value). C<IS_NUMBER_IN_UV> is not set if e notation was used or the
number is larger than a UV.
C<flags> allows only C<PERL_SCAN_TRAILING>, which allows for trailing
=for apidoc grok_number
-Identical to grok_number_flags() with flags set to zero.
+Identical to C<grok_number_flags()> with C<flags> set to zero.
=cut
*/
/*
=for apidoc isinfnan
-Perl_isinfnan() is utility function that returns true if the NV
-argument is either an infinity or a NaN, false otherwise. To test
-in more detail, use Perl_isinf() and Perl_isnan().
+C<Perl_isinfnan()> is utility function that returns true if the NV
+argument is either an infinity or a C<NaN>, false otherwise. To test
+in more detail, use C<Perl_isinf()> and C<Perl_isnan()>.
This is also the logical inverse of Perl_isfinite().
/*
=for apidoc
-Checks whether the argument would be either an infinity or NaN when used
+Checks whether the argument would be either an infinity or C<NaN> when used
as a number, but is careful not to trigger non-numeric or uninitialized
-warnings. it assumes the caller has done SvGETMAGIC(sv) already.
+warnings. it assumes the caller has done C<SvGETMAGIC(sv)> already.
=cut
*/
Return a non-zero integer if the sign bit on an NV is set, and 0 if
it is not.
-If F<Configure> detects this system has a signbit() that will work with
-our NVs, then we just use it via the #define in perl.h. Otherwise,
+If F<Configure> detects this system has a C<signbit()> that will work with
+our NVs, then we just use it via the C<#define> in F<perl.h>. Otherwise,
fall back on this implementation. The main use of this function
-is catching -0.0.
+is catching C<-0.0>.
-Configure notes: This function is called 'Perl_signbit' instead of a
-plain 'signbit' because it is easy to imagine a system having a signbit()
+C<Configure> notes: This function is called C<'Perl_signbit'> instead of a
+plain C<'signbit'> because it is easy to imagine a system having a C<signbit()>
function or macro that doesn't happen to work with our particular choice
-of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
+of NVs. We shouldn't just re-C<#define> C<signbit> as C<Perl_signbit> and expect
the standard system headers to be happy. Also, this is a no-context
-function (no pTHX_) because Perl_signbit() is usually re-#defined in
-F<perl.h> as a simple macro call to the system's signbit().
-Users should just always call Perl_signbit().
+function (no C<pTHX_>) because C<Perl_signbit()> is usually re-C<#defined> in
+F<perl.h> as a simple macro call to the system's C<signbit()>.
+Users should just always call C<Perl_signbit()>.
=cut
*/
=for apidoc op_sibling_splice
A general function for editing the structure of an existing chain of
-op_sibling nodes. By analogy with the perl-level splice() function, allows
+op_sibling nodes. By analogy with the perl-level C<splice()> function, allows
you to delete zero or more sequential nodes, replacing them with zero or
more different nodes. Performs the necessary op_first/op_last
housekeeping on the parent node and op_sibling manipulation on the
responsibility of the caller. It also won't create a new list op for an
empty list etc; use higher-level functions like op_append_elem() for that.
-parent is the parent node of the sibling chain. It may passed as NULL if
+C<parent> is the parent node of the sibling chain. It may passed as C<NULL> if
the splicing doesn't affect the first or last op in the chain.
-start is the node preceding the first node to be spliced. Node(s)
+C<start> is the node preceding the first node to be spliced. Node(s)
following it will be deleted, and ops will be inserted after it. If it is
-NULL, the first node onwards is deleted, and nodes are inserted at the
+C<NULL>, the first node onwards is deleted, and nodes are inserted at the
beginning.
-del_count is the number of nodes to delete. If zero, no nodes are deleted.
+C<del_count> is the number of nodes to delete. If zero, no nodes are deleted.
If -1 or greater than or equal to the number of remaining kids, all
remaining kids are deleted.
-insert is the first of a chain of nodes to be inserted in place of the nodes.
-If NULL, no nodes are inserted.
+C<insert> is the first of a chain of nodes to be inserted in place of the nodes.
+If C<NULL>, no nodes are inserted.
-The head of the chain of deleted ops is returned, or NULL if no ops were
+The head of the chain of deleted ops is returned, or C<NULL> if no ops were
deleted.
For example:
/*
=for apidoc op_parent
-Returns the parent OP of o, if it has a parent. Returns NULL otherwise.
+Returns the parent OP of C<o>, if it has a parent. Returns C<NULL> otherwise.
This function is only available on perls built with C<-DPERL_OP_PARENT>.
=cut
This function finalizes the optree. Should be called directly after
the complete optree is built. It does some additional
-checking which can't be done in the normal ck_xxx functions and makes
+checking which can't be done in the normal C<ck_>xxx functions and makes
the tree thread-safe.
=cut
Propagate lvalue ("modifiable") context to an op and its children.
C<type> represents the context type, roughly based on the type of op that
-would do the modifying, although C<local()> is represented by OP_NULL,
+would do the modifying, although C<local()> is represented by C<OP_NULL>,
because it has no op type of its own (it is signalled by a flag on
the lvalue op).
This function detects things that can't be modified, such as C<$x+1>, and
generates errors for them. For example, C<$x+1 = 2> would cause it to be
-called with an op of type OP_ADD and a C<type> argument of OP_SASSIGN.
+called with an op of type C<OP_ADD> and a C<type> argument of C<OP_SASSIGN>.
It also flags things that need to behave specially in an lvalue context,
such as C<$$x = 5> which might have to vivify a reference in C<$x>.
For most list operators, the check function expects all the kid ops to be
present already, so calling C<newLISTOP(OP_JOIN, ...)> (e.g.) is not
appropriate. What you want to do in that case is create an op of type
-OP_LIST, append more children to it, and then call L</op_convert_list>.
+C<OP_LIST>, append more children to it, and then call L</op_convert_list>.
See L</op_convert_list> for more information.
/*
=for apidoc newUNOP_AUX
-Similar to C<newUNOP>, but creates an UNOP_AUX struct instead, with op_aux
-initialised to aux
+Similar to C<newUNOP>, but creates an C<UNOP_AUX> struct instead, with C<op_aux>
+initialised to C<aux>
=cut
*/
the bit with value 1 is automatically set. C<dynamic_meth> supplies an
op which evaluates method name; it is consumed by this function and
become part of the constructed op tree.
-Supported optypes: OP_METHOD.
+Supported optypes: C<OP_METHOD>.
=cut
*/
C<op_flags>, and, shifted up eight bits, the eight bits of
C<op_private>. C<const_meth> supplies a constant method name;
it must be a shared COW string.
-Supported optypes: OP_METHOD_NAMED.
+Supported optypes: C<OP_METHOD_NAMED>.
=cut
*/
Loads the module whose name is pointed to by the string part of name.
Note that the actual module name, not its filename, should be given.
Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
-PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
+C<PERL_LOADMOD_DENY>, C<PERL_LOADMOD_NOIMPORT>, or C<PERL_LOADMOD_IMPORT_OPS>
(or 0 for no flags). ver, if specified
and not NULL, provides version semantics
similar to C<use Foo::Bar VERSION>. The optional trailing SV*
-arguments can be used to specify arguments to the module's import()
+arguments can be used to specify arguments to the module's C<import()>
method, similar to C<use Foo::Bar VERSION LIST>. They must be
-terminated with a final NULL pointer. Note that this list can only
-be omitted when the PERL_LOADMOD_NOIMPORT flag has been used.
-Otherwise at least a single NULL pointer to designate the default
+terminated with a final C<NULL> pointer. Note that this list can only
+be omitted when the C<PERL_LOADMOD_NOIMPORT> flag has been used.
+Otherwise at least a single C<NULL> pointer to designate the default
import list is required.
The reference count for each specified C<SV*> parameter is decremented.
variable, and C<block> supplies the body of the C<given> construct; they
are consumed by this function and become part of the constructed op tree.
C<defsv_off> is the pad offset of the scalar lexical variable that will
-be affected. If it is 0, the global $_ will be used.
+be affected. If it is 0, the global C<$_> will be used.
=cut
*/
=for apidoc cv_const_sv
If C<cv> is a constant sub eligible for inlining, returns the constant
-value returned by the sub. Otherwise, returns NULL.
+value returned by the sub. Otherwise, returns C<NULL>.
Constant subs can be created with C<newCONSTSUB> or as described in
L<perlsub/"Constant Functions">.
Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
eligible for inlining at compile-time.
-Currently, the only useful value for C<flags> is SVf_UTF8.
+Currently, the only useful value for C<flags> is C<SVf_UTF8>.
The newly created subroutine takes ownership of a reference to the passed in
SV.
-Passing NULL for SV creates a constant sub equivalent to C<sub BAR () {}>,
+Passing C<NULL> for SV creates a constant sub equivalent to C<sub BAR () {}>,
which won't be called if used as a destructor, but will suppress the overhead
of a call to C<AUTOLOAD>. (This form, however, isn't eligible for inlining at
compile time.)
=for apidoc Ao||custom_op_xop
Return the XOP structure for a given custom op. This macro should be
-considered internal to OP_NAME and the other access macros: use them instead.
+considered internal to C<OP_NAME> and the other access macros: use them instead.
This macro does call a function. Prior
to 5.19.6, this was implemented as a
function.
=for apidoc core_prototype
This function assigns the prototype of the named core function to C<sv>, or
-to a new mortal SV if C<sv> is NULL. It returns the modified C<sv>, or
-NULL if the core function has no prototype. C<code> is a code as returned
+to a new mortal SV if C<sv> is C<NULL>. It returns the modified C<sv>, or
+C<NULL> if the core function has no prototype. C<code> is a code as returned
by C<keyword()>. It must not be equal to 0.
=cut
=for apidoc mx|void *|BhkENTRY|BHK *hk|which
Return an entry from the BHK structure. C<which> is a preprocessor token
indicating which entry to return. If the appropriate flag is not set
-this will return NULL. The type of the return value depends on which
+this will return C<NULL>. The type of the return value depends on which
entry you ask for.
=for apidoc Amx|void|BhkENTRY_set|BHK *hk|which|void *ptr
=for apidoc Am|U32|OP_CLASS|OP *o
Return the class of the provided OP: that is, which of the *OP
structures it uses. For core ops this currently gets the information out
-of PL_opargs, which does not always accurately reflect the type used.
+of C<PL_opargs>, which does not always accurately reflect the type used.
For custom ops the type is returned from the registration, and it is up
to the registree to ensure it is accurate. The value returned will be
-one of the OA_* constants from F<op.h>.
+one of the C<OA_>* constants from F<op.h>.
=for apidoc Am|bool|OP_TYPE_IS|OP *o|Optype type
-Returns true if the given OP is not a NULL pointer
+Returns true if the given OP is not a C<NULL> pointer
and if it is of the given type.
The negation of this macro, C<OP_TYPE_ISNT> is also available
The negation of this macro, C<OP_TYPE_ISNT_AND_WASNT>
is also available as well as C<OP_TYPE_IS_OR_WAS_NN>
and C<OP_TYPE_ISNT_AND_WASNT_NN> which elide
-the NULL pointer check.
+the C<NULL> pointer check.
=for apidoc Am|bool|OpHAS_SIBLING|OP *o
-Returns true if o has a sibling
+Returns true if C<o> has a sibling
=for apidoc Am|OP*|OpSIBLING|OP *o
-Returns the sibling of o, or NULL if there is no sibling
+Returns the sibling of C<o>, or C<NULL> if there is no sibling
=for apidoc Am|void|OpMORESIB_set|OP *o|OP *sib
-Sets the sibling of o to the non-zero value sib. See also C<L</OpLASTSIB_set>>
+Sets the sibling of C<o> to the non-zero value C<sib>. See also C<L</OpLASTSIB_set>>
and C<L</OpMAYBESIB_set>>. For a higher-level interface, see
C<L</op_sibling_splice>>.
=for apidoc Am|void|OpLASTSIB_set|OP *o|OP *parent
-Marks
o as having no further siblings. On C<PERL_OP_PARENT> builds, marks
+Marks
C<o> as having no further siblings. On C<PERL_OP_PARENT> builds, marks
o as having the specified parent. See also C<L</OpMORESIB_set>> and
C<OpMAYBESIB_set>. For a higher-level interface, see
C<L</op_sibling_splice>>.
=for apidoc Am|void|OpMAYBESIB_set|OP *o|OP *sib|OP *parent
Conditionally does C<OpMORESIB_set> or C<OpLASTSIB_set> depending on whether
-sib is non-null. For a higher-level interface, see C<L</op_sibling_splice>>.
+C<sib> is non-null. For a higher-level interface, see C<L</op_sibling_splice>>.
=cut
*/
executing). Require'd files are simply evals without any outer lexical
scope.
-XSUBs do not have a CvPADLIST. dXSTARG fetches values from PL_curpad,
+XSUBs do not have a C<CvPADLIST>. C<dXSTARG> fetches values from C<PL_curpad>,
but that is really the callers pad (a slot of which is allocated by
-every entersub). Do not get or set CvPADLIST if a CV is an XSUB (as
-determined by C<CvISXSUB()>), CvPADLIST slot is reused for a different
+every entersub). Do not get or set C<CvPADLIST> if a CV is an XSUB (as
+determined by C<CvISXSUB()>), C<CvPADLIST> slot is reused for a different
internal purpose in XSUBs.
The PADLIST has a C array where pads are stored.
The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the stack frame
at that depth of recursion into the CV. The 0th slot of a frame AV is an
-AV which is @_. Other entries are storage for variables and op targets.
+AV which is C<@_>. Other entries are storage for variables and op targets.
Iterating over the PADNAMELIST iterates over all possible pad
-items. Pad slots for targets (SVs_PADTMP)
+items. Pad slots for targets (C<SVs_PADTMP>)
and GVs end up having &PL_padname_undef "names", while slots for constants
-have &PL_padname_const "names" (see pad_alloc()). That &PL_padname_undef
-and &PL_padname_const are used is an implementation detail subject to
-change. To test for them, use C<!PadnamePV(name)> and C<PadnamePV(name)
-&& !PadnameLEN(name)>, respectively.
+have C<&PL_padname_const> "names" (see C<L</pad_alloc>>). That
+C<&PL_padname_undef>
+and C<&PL_padname_const> are used is an implementation detail subject to
+change. To test for them, use C<!PadnamePV(name)> and
+C<PadnamePV(name) && !PadnameLEN(name)>, respectively.
-Only my/our variable slots get valid names.
+Only C<my>/C<our> variable slots get valid names.
The rest are op targets/GVs/constants which are statically allocated
or resolved at compile time. These don't have names by which they
can be looked up from Perl code at run time through eval"" the way
-my/our variables can be. Since they can't be looked up by "name"
+C<my>/C<our> variables can be. Since they can't be looked up by "name"
but only by their index allocated at compile time (which is usually
-in PL_op->op_targ), wasting a name SV for them doesn't make sense.
+in C<PL_op->op_targ>), wasting a name SV for them doesn't make sense.
The pad names in the PADNAMELIST have their PV holding the name of
-the variable. The COP_SEQ_RANGE_LOW and _HIGH fields form a range
+the variable. The C<COP_SEQ_RANGE_LOW> and C<_HIGH> fields form a range
(low+1..high inclusive) of cop_seq numbers for which the name is
valid. During compilation, these fields may hold the special value
PERL_PADSEQ_INTRO to indicate various stages:
valid-seq# valid-seq# compilation of scope complete:
{ my ($x) }
-For typed lexicals PadnameTYPE points at the type stash. For C<our>
-lexicals, PadnameOURSTASH points at the stash of the associated global (so
+For typed lexicals C<PadnameTYPE> points at the type stash. For C<our>
+lexicals, C<PadnameOURSTASH> points at the stash of the associated global (so
that duplicate C<our> declarations in the same package can be detected).
-PadnameGEN is sometimes used to store the generation number during
+C<PadnameGEN> is sometimes used to store the generation number during
compilation.
-If PadnameOUTER is set on the pad name, then that slot in the frame AV
+If C<PadnameOUTER> is set on the pad name, then that slot in the frame AV
is a REFCNT'ed reference to a lexical from "outside". Such entries
are sometimes referred to as 'fake'. In this case, the name does not
use 'low' and 'high' to store a cop_seq range, since it is in scope
within the parent's pad where the lexical's value is stored, to make
cloning quicker.
-If the 'name' is '&' the corresponding entry in the PAD
+If the 'name' is C<&> the corresponding entry in the PAD
is a CV representing a possible closure.
Note that formats are treated as anon subs, and are cloned each time
write is called (if necessary).
-The flag SVs_PADSTALE is cleared on lexicals each time the my() is executed,
+The flag C<SVs_PADSTALE> is cleared on lexicals each time the C<my()> is executed,
and set on scope exit. This allows the
-'Variable $x is not available' warning
+C<"Variable $x is not available"> warning
to be generated in evals, such as
{ my $x = 1; sub f { eval '$x'} } f();
-For state vars, SVs_PADSTALE is overloaded to mean 'not yet initialised',
+For state vars, C<SVs_PADSTALE> is overloaded to mean 'not yet initialised',
but this internal state is stored in a separate pad entry.
=for apidoc AmxU|PADNAMELIST *|PL_comppad_name
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
+In the former case, we keep the C<CvOUTSIDE> pointer, so that any anonymous
children can still follow the full lexical scope chain.
=cut
/*
=for apidoc cv_forget_slab
-When a CV has a reference count on its slab (CvSLABBED), it is responsible
+When a CV has a reference count on its slab (C<CvSLABBED>), it is responsible
for making sure it is freed. (Hence, no two CVs should ever have a
reference count on the same slab.) The CV only needs to reference the slab
-during compilation. Once it is compiled and CvROOT attached, it has
+during compilation. Once it is compiled and C<CvROOT> attached, it has
finished its job, so it can forget the slab.
=cut
Check for duplicate declarations: report any of:
- * a my in the current scope with the same name;
- * an our (anywhere in the pad) with the same name and the
- same stash as C<ourstash>
+ * a 'my' in the current scope with the same name;
+ * an 'our' (anywhere in the pad) with the same name and the
+ same stash as 'ourstash'
-C<is_our> indicates that the name to check is an 'our' declaration.
+C<is_our> indicates that the name to check is an C<"our"> declaration.
=cut
*/
in the inner pads if it's found in an outer one.
Returns the offset in the bottom pad of the lex or the fake lex.
-cv is the CV in which to start the search, and seq is the current cop_seq
-to match against. If warn is true, print appropriate warnings. The out_*
+C<cv> is the CV in which to start the search, and seq is the current C<cop_seq>
+to match against. If C<warn> is true, print appropriate warnings. The C<out_>*
vars return values, and so are pointers to where the returned values
-should be stored. out_capture, if non-null, requests that the innermost
-instance of the lexical is captured; out_name is set to the innermost
-matched pad name or fake pad name; out_flags returns the flags normally
-associated with the PARENT_FAKELEX_FLAGS field of a fake pad name.
+should be stored. C<out_capture>, if non-null, requests that the innermost
+instance of the lexical is captured; C<out_name> is set to the innermost
+matched pad name or fake pad name; C<out_flags> returns the flags normally
+associated with the C<PARENT_FAKELEX_FLAGS> field of a fake pad name.
-Note that pad_findlex() is recursive; it recurses up the chain of CVs,
+Note that C<pad_findlex()> is recursive; it recurses up the chain of CVs,
then comes back down, adding fake entries
as it goes. It has to be this way
-because fake names in anon protoypes have to store in xlow the index into
+because fake names in anon protoypes have to store in C<xlow> the index into
the parent pad.
=cut
=for apidoc Am|SV *|pad_sv|PADOFFSET po
Get the value at offset C<po> in the current (compiling or executing) pad.
-Use macro PAD_SV instead of calling this function directly.
+Use macro C<PAD_SV> instead of calling this function directly.
=cut
*/
=for apidoc Am|void|pad_setsv|PADOFFSET po|SV *sv
Set the value at offset C<po> in the current (compiling or executing) pad.
-Use the macro PAD_SETSV() rather than calling this function directly.
+Use the macro C<PAD_SETSV()> rather than calling this function directly.
=cut
*/
/*
=for apidoc m|void|pad_swipe|PADOFFSET po|bool refadjust
-Abandon the tmp in the current pad at offset po and replace with a
+Abandon the tmp in the current pad at offset C<po> and replace with a
new one.
=cut
Tidy up a pad at the end of compilation of the code to which it belongs.
Jobs performed here are: remove most stuff from the pads of anonsub
-prototypes; give it a @_; mark temporaries as such. C<type> indicates
+prototypes; give it a C<@_>; mark temporaries as such. C<type> indicates
the kind of subroutine:
padtidy_SUB ordinary subroutine
to it and it will be returned. Otherwise the returned SV will be a new
mortal.
-If the C<flags> include CV_NAME_NOTQUAL, then the package name will not be
+If C<flags> include C<CV_NAME_NOTQUAL>, then the package name will not be
included. If the first argument is neither a CV nor a GV, this flag is
ignored (subject to change).
/*
=for apidoc m|void|pad_fixup_inner_anons|PADLIST *padlist|CV *old_cv|CV *new_cv
-For any anon CVs in the pad, change CvOUTSIDE of that CV from
-old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
+For any anon CVs in the pad, change C<CvOUTSIDE> of that CV from
+C<old_cv> to C<new_cv> if necessary. Needed when a newly-compiled CV has to be
moved to a pre-existing CV struct.
=cut
Push a new pad frame onto the padlist, unless there's already a pad at
this depth, in which case don't bother creating a new one. Then give
-the new pad an @_ in slot zero.
+the new pad an C<@_> in slot zero.
=cut
*/
Constructs and returns a new pad name. Only use this function for names
that refer to outer lexicals. (See also L</newPADNAMEpvn>.) C<outer> is
the outer pad name that this one mirrors. The returned pad name has the
-PADNAMEt_OUTER flag already set.
+C<PADNAMEt_OUTER> flag already set.
=cut
*/
XXX DAPM it would make more sense to make the arg a PADOFFSET
=for apidoc m|void|SAVECLEARSV |SV **svp
Clear the pointed to pad value on scope exit. (i.e. the runtime action of
-'my')
+C<my>)
=for apidoc m|void|SAVECOMPPAD
-save PL_comppad and PL_curpad
+save C<PL_comppad> and C<PL_curpad>
=for apidoc Amx|PAD **|PadlistARRAY|PADLIST padlist
=for apidoc Amx|SSize_t|PadlistMAX|PADLIST padlist
The index of the last allocated space in the padlist. Note that the last
-pad may be in an earlier slot. Any entries following it will be NULL in
+pad may be in an earlier slot. Any entries following it will be C<NULL> in
that case.
=for apidoc Amx|PADNAMELIST *|PadlistNAMES|PADLIST padlist
The index of the last pad entry.
=for apidoc Amx|char *|PadnamePV|PADNAME pn
-The name stored in the pad name struct. This returns NULL for a target
+The name stored in the pad name struct. This returns C<NULL> for a target
slot.
=for apidoc Amx|STRLEN|PadnameLEN|PADNAME pn
Whether this is a "state" variable.
=for apidoc m|HV *|PadnameTYPE|PADNAME pn
-The stash associated with a typed lexical. This returns the %Foo:: hash
+The stash associated with a typed lexical. This returns the C<%Foo::> hash
for C<my Foo $bar>.
=for apidoc Amx|SSize_t|PadnameREFCNT|PADNAME pn
Save the current pad then set it to null.
=for apidoc m|void|PAD_SAVE_LOCAL|PAD *opad|PAD *npad
-Save the current pad to the local variable opad, then make the
-current pad equal to npad
+Save the current pad to the local variable C<opad>, then make the
+current pad equal to C<npad>
=for apidoc m|void|PAD_RESTORE_LOCAL|PAD *opad
-Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
+Restore the old pad saved into the local variable C<opad> by C<PAD_SAVE_LOCAL()>
=cut
*/
Save the current pad in the given context block structure.
=for apidoc m|SV *|CX_CURPAD_SV|struct context|PADOFFSET po
-Access the SV at offset po in the saved current pad in the given
+Access the SV at offset C<po> in the saved current pad in the given
context block structure (can be used as an lvalue).
=cut
Returns the HV of the specified Perl hash. C<flags> are passed to
C<gv_fetchpv>. If C<GV_ADD> is set and the
Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
+and the variable does not exist then C<NULL> is returned.
=cut
*/
=for apidoc p||call_argv
Performs a callback to the specified named and package-scoped Perl subroutine
-with C<argv> (a NULL-terminated array of strings) as arguments. See
+with C<argv> (a C<NULL>-terminated array of strings) as arguments. See
L<perlcall>.
Approximate Perl equivalent: C<&{"$sub_name"}(@$argv)>.
=for apidoc p||eval_sv
Tells Perl to C<eval> the string in the SV. It supports the same flags
-as C<call_sv>, with the obvious exception of
G_EVAL. See L<perlcall>.
+as C<call_sv>, with the obvious exception of
C<G_EVAL>. See L<perlcall>.
=cut
*/
=item Useless use of attribute "const"
-(W misc) The "const" attribute has no effect except
+(W misc) The C<const> attribute has no effect except
on anonymous closure prototypes. You applied it to
a subroutine via L<attributes.pm|attributes>. This is only useful
inside an attribute handler for an anonymous subroutine.
=for apidoc find_runcv
Locate the CV corresponding to the currently executing sub or eval.
-If db_seqp is non_null, skip CVs that are in the DB package and populate
-*db_seqp with the cop sequence number at the point that the DB:: code was
+If C<db_seqp> is non_null, skip CVs that are in the DB package and populate
+C<*db_seqp> with the cop sequence number at the point that the DB:: code was
entered. (This allows debuggers to eval in the scope of the breakpoint
rather than in the scope of the debugger itself.)
=for apidoc unpackstring
-The engine implementing the unpack() Perl function.
+The engine implementing the C<unpack()> Perl function.
-Using the template pat..patend, this function unpacks the string
-s..strend into a number of mortal SVs, which it pushes onto the perl
-argument (
@_) stack (so you will need to issue a C<PUTBACK> before and
+Using the template C<pat..patend>, this function unpacks the string
+C<s..strend> into a number of mortal SVs, which it pushes onto the perl
+argument (
C<@_>) stack (so you will need to issue a C<PUTBACK> before and
C<SPAGAIN> after the call to this function). It returns the number of
pushed elements.
-The strend and patend pointers should point to the byte following the last
-character of each string.
+The C<strend> and C<patend> pointers should point to the byte following the
+last character of each string.
Although this function returns its values on the perl argument stack, it
doesn't take any parameters from that stack (and thus in particular
-there's no need to do a PUSHMARK before calling it, unlike L</call_pv> for
+there's no need to do a C<PUSHMARK> before calling it, unlike L</call_pv> for
example).
=cut */
/*
=for apidoc packlist
-The engine implementing pack() Perl function.
+The engine implementing C<pack()> Perl function.
=cut
*/
sortsv(AvARRAY(av), av_top_index(av)+1, Perl_sv_cmp_locale);
-Currently this always uses mergesort. See sortsv_flags for a more
+Currently this always uses mergesort. See C<L</sortsv_flags>> for a more
flexible routine.
=cut
=for apidoc setdefout
-Sets PL_defoutgv, the default file handle for output, to the passed in
-typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference
+Sets C<PL_defoutgv>, the default file handle for output, to the passed in
+typeglob. As C<PL_defoutgv> "owns" a reference on its typeglob, the reference
count of the passed in typeglob is increased by one, and the reference count
-of the typeglob that PL_defoutgv points to is decreased by one.
+of the typeglob that C<PL_defoutgv> points to is decreased by one.
=cut
*/
if (SvTYPE(sv) == SVt_REGEXP)
return (REGEXP*) sv;
-NULL will be returned if a REGEXP* is not found.
+C<NULL> will be returned if a REGEXP* is not found.
=for apidoc Am|bool|SvRXOK|SV* sv
Test if the content of an SV looks like a number (or is a number).
C<Inf> and C<Infinity> are treated as numbers (so will not issue a
-non-numeric warning), even if your atof() doesn't grok them. Get-magic is
+non-numeric warning), even if your C<atof()> doesn't grok them. Get-magic is
ignored.
=cut
=for apidoc sv_2iv_flags
Return the integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+conversion. If C<flags> includes C<SV_GMAGIC>, does an C<mg_get()> first.
Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
=cut
=for apidoc sv_2uv_flags
Return the unsigned integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+conversion. If C<flags> includes C<SV_GMAGIC>, does an C<mg_get()> first.
Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
=cut
=for apidoc sv_2nv_flags
Return the num value of an SV, doing any necessary string or integer
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+conversion. If C<flags> includes C<SV_GMAGIC>, does an C<mg_get()> first.
Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> macros.
=cut
/*
=for apidoc sv_2pv_flags
-Returns a pointer to the string value of an SV, and sets *lp to its length.
-If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a
+Returns a pointer to the string value of an SV, and sets C<*lp> to its length.
+If flags includes C<SV_GMAGIC>, does an C<mg_get()> first. Coerces C<sv> to a
string if necessary. Normally invoked via the C<SvPV_flags> macro.
C<sv_2pv()> and C<sv_2pv_nomg> usually end up here too.
=for apidoc sv_copypv
Copies a stringified representation of the source SV into the
-destination SV. Automatically performs any necessary mg_get and
+destination SV. Automatically performs any necessary C<mg_get> and
coercion of numeric values into strings. Guaranteed to preserve
-UTF8 flag even from overloaded objects. Similar in nature to
-sv_2pv[_flags] but operates directly on an SV instead of just the
-string. Mostly uses sv_2pv_flags to do its work, except when that
+C<UTF8> flag even from overloaded objects. Similar in nature to
+C<sv_2pv[_flags]> but operates directly on an SV instead of just the
+string. Mostly uses C<sv_2pv_flags> to do its work, except when that
would lose the UTF-8'ness of the PV.
=for apidoc sv_copypv_nomg
-Like sv_copypv, but doesn't invoke get magic first.
+Like C<sv_copypv>, but doesn't invoke get magic first.
=for apidoc sv_copypv_flags
-Implementation of sv_copypv and sv_copypv_nomg. Calls get magic iff flags
-include SV_GMAGIC.
+Implementation of C<sv_copypv> and C<sv_copypv_nomg>. Calls get magic iff flags
+include C<SV_GMAGIC>.
=cut
*/
/*
=for apidoc sv_2pvbyte
-Return a pointer to the byte-encoded representation of the SV, and set *lp
+Return a pointer to the byte-encoded representation of the SV, and set C<*lp>
to its length. May cause the SV to be downgraded from UTF-8 as a
side-effect.
/*
=for apidoc sv_2pvutf8
-Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
+Return a pointer to the UTF-8-encoded representation of the SV, and set C<*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.
/*
=for apidoc sv_2bool
-This macro is only used by sv_true() or its macro equivalent, and only if
-the latter's argument is neither SvPOK, SvIOK nor SvNOK.
-It calls sv_2bool_flags with the SV_GMAGIC flag.
+This macro is only used by C<sv_true()> or its macro equivalent, and only if
+the latter's argument is neither C<SvPOK>, C<SvIOK> nor C<SvNOK>.
+It calls C<sv_2bool_flags> with the C<SV_GMAGIC> flag.
=for apidoc sv_2bool_flags
-This function is only used by sv_true() and friends, and only if
-the latter's argument is neither SvPOK, SvIOK nor SvNOK. If the flags
-contain SV_GMAGIC, then it does an mg_get() first.
+This function is only used by C<sv_true()> and friends, and only if
+the latter's argument is neither C<SvPOK>, C<SvIOK> nor C<SvNOK>. If the flags
+contain C<SV_GMAGIC>, then it does an C<mg_get()> first.
=cut
Converts the PV of an SV to its UTF-8-encoded form.
Forces the SV to string form if it is not already.
Will C<mg_get> on C<sv> if appropriate.
-Always sets the SvUTF8 flag to avoid future validity checks even
+Always sets the C<SvUTF8> flag to avoid future validity checks even
if the whole string is the same in UTF-8 as not.
Returns the number of bytes in the converted string
=for apidoc sv_utf8_upgrade_nomg
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
+Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
=for apidoc sv_utf8_upgrade_flags
If C<flags> has C<SV_GMAGIC> bit set,
will C<mg_get> on C<sv> if appropriate, else not.
-If C<flags> has SV_FORCE_UTF8_UPGRADE set, this function assumes that the PV
+If C<flags> has C<SV_FORCE_UTF8_UPGRADE> set, this function assumes that the PV
will expand when converted to UTF-8, and skips the extra work of checking for
that. Typically this flag is used by a routine that has already parsed the
string and found such characters, and passes this information on so that the
=for apidoc sv_utf8_upgrade_flags_grow
-Like sv_utf8_upgrade_flags, but has an additional parameter C<extra>, which is
-the number of unused bytes the string of 'sv' is guaranteed to have free after
+Like C<sv_utf8_upgrade_flags>, but has an additional parameter C<extra>, which is
+the number of unused bytes the string of C<sv> is guaranteed to have free after
it upon return. This allows the caller to reserve extra space that it intends
to fill, to avoid extra grows.
true, croaks.
This is not a general purpose Unicode to byte encoding interface:
-use the Encode extension for that.
+use the C<Encode> extension for that.
=cut
*/
If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
C<ssv> if appropriate, else not. If the C<flags>
parameter has the C<SV_NOSTEAL> bit set then the
-buffers of temps will not be stolen. <sv_setsv>
+buffers of temps will not be stolen. C<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
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 L<Newx|perlclib/Memory Management and String Handling>. It must be
-the start of a Newx-ed block of memory, and not a pointer to the
-middle of it (beware of L<OOK|perlguts/Offsets> and copy-on-write),
-and not be from a non-Newx memory allocator like C<malloc>. The
+outside string. C<ptr> should point to memory that was allocated
+by L<C<Newx>|perlclib/Memory Management and String Handling>. It must be
+the start of a C<Newx>-ed block of memory, and not a pointer to the
+middle of it (beware of L<C<OOK>|perlguts/Offsets> and copy-on-write),
+and not be from a non-C<Newx> memory allocator like C<malloc>. The
string length, C<len>, must be supplied. By default this function
will C<Renew> (i.e. realloc, 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"
+giving it to C<sv_usepvn>, and neither should any pointers from "behind"
that pointer (e.g. ptr + 1) be used.
-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 C<NUL>, and the realloc
+If C<flags & SV_SMAGIC> is true, will call C<SvSETMAGIC>. If
+C<flags & SV_HAS_TRAILING_NUL> is true, then C<ptr[len]> must be C<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>).
Undo various types of fakery on an SV, where fakery means
"more than" a string: if the PV is a shared string, make
a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
-an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
+an C<xpvmg>; if we're a copy-on-write scalar, this is the on-write time when
we do the copy, and is also used locally; if this is a
vstring, drop the vstring magic. If 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
+C<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 unreffing. C<sv_force_normal> calls this function
=for apidoc sv_chop
Efficient removal of characters from the beginning of the string buffer.
-
SvPOK(sv), or at least SvPOKp(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". On return, only
-SvPOK(sv) and SvPOKp(sv) among the OK flags will be true.
+
C<SvPOK(sv)>, or at least C<SvPOKp(sv)>, must be true and C<ptr> must be a
+pointer to somewhere inside the string buffer. C<ptr> becomes the first
+character of the adjusted string. Uses the C<OOK> hack. On return, only
+C<SvPOK(sv)> and C<SvPOKp(sv)> among the C<OK> flags will be true.
Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
refer to the same chunk of data.
/*
=for apidoc sv_catpvn
-Concatenates the string onto the end of the string which is in the SV. The
+Concatenates the string onto the end of the string which is in the SV.
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<L</sv_catpvn_mg>>.
Creates a new SV. A non-zero C<len> parameter indicates the number of
bytes of preallocated string space the SV should have. An extra byte for a
-trailing C<NUL> is also reserved. (SvPOK is not set for the SV even if string
+trailing C<NUL> is also reserved. (C<SvPOK> is not set for the SV even if string
space is allocated.) The reference count for the new SV is set to 1.
-In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
+In 5.9.3, C<newSV()> replaces the older C<NEWSV()> API, and drops the first
parameter, I<x>, a debug aid which allowed callers to identify themselves.
-This aid has been superseded by a new build option, PERL_MEM_LOG (see
+This aid has been superseded by a new build option, C<PERL_MEM_LOG> (see
L<perlhacktips/PERL_MEM_LOG>). The older API is still there for use in XS
modules supporting older perls.
=for apidoc sv_magicext
Adds magic to an SV, upgrading it if necessary. Applies the
-supplied vtable and returns a pointer to the magic added.
+supplied C<vtable> and returns a pointer to the magic added.
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'.
+In particular, you can add magic to C<SvREADONLY> SVs, and add more than
+one instance of the same C<how>.
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.
+to contain an SV* and is stored as-is with its C<REFCNT> incremented.
(This is now used as a subroutine by C<sv_magic>.)
See C<L</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'.
+You need to use C<sv_magicext> to add magic to C<SvREADONLY> SVs and also
+to add more than one instance of the same C<how>.
=cut
*/
/*
=for apidoc sv_get_backrefs
-If the sv is the target of a weak reference then it returns the back
-references structure associated with the sv; otherwise return NULL.
+If C<sv> is the target of a weak reference then it returns the back
+references structure associated with the sv; otherwise return C<NULL>.
When returning a non-null result the type of the return is relevant. If it
is an AV then the elements of the AV are the weak reference RVs which
point at this item. If it is any other type then the item itself is the
weak reference.
-See also Perl_sv_add_backref(), Perl_sv_del_backref(),
-Perl_sv_kill_backrefs()
+See also C<Perl_sv_add_backref()>, C<Perl_sv_del_backref()>,
+C<Perl_sv_kill_backrefs()>
=cut
*/
=for apidoc sv_insert
Inserts a string at the specified offset/length within the SV. Similar to
-the Perl substr() function. Handles get magic.
+the Perl C<substr()> function. Handles get magic.
=for apidoc sv_insert_flags
and free the body itself. The SV's head is I<not> freed, although
its type is set to all 1's so that it won't inadvertently be assumed
to be live during global destruction etc.
-This function should only be called when REFCNT is zero. Most of the time
+This function should only be called when C<REFCNT> is zero. Most of the time
you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
instead.
Returns the length of the string in the SV. Handles magic and type
coercion and sets the UTF8 flag appropriately. See also C<L</SvCUR>>, which
-gives raw access to the xpv_cur slot.
+gives raw access to the C<xpv_cur> slot.
=cut
*/
Converts the offset from a count of UTF-8 chars from
the start of the string, to a count of the equivalent number of bytes; if
-lenp is non-zero, it does the same to lenp, but this time starting from
-the offset, rather than from the start
+C<lenp> is non-zero, it does the same to C<lenp>, but this time starting from
+C<offset>, rather than from the start
of the string. Handles type coercion.
C<flags> is passed to C<SvPV_flags>, and usually should be
C<SV_GMAGIC|SV_CONST_RETURN> to handle magic.
/*
=for apidoc sv_pos_u2b
-Converts the value pointed to by offsetp from a count of UTF-8 chars from
+Converts the value pointed to by C<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
+C<lenp> is non-zero, it does the same to C<lenp>, but this time starting from
the offset, rather than from the start of the string. Handles magic and
type coercion.
/*
=for apidoc sv_pos_b2u_flags
-Converts the offset from a count of bytes from the start of the string, to
+Converts C<offset> from a count of bytes from the start of the string, to
a count of the equivalent number of UTF-8 chars. Handles type coercion.
C<flags> is passed to C<SvPV_flags>, and usually should be
C<SV_GMAGIC|SV_CONST_RETURN> to handle magic.
/*
=for apidoc sv_pos_b2u
-Converts the value pointed to by offsetp from a count of bytes from the
+Converts the value pointed to by C<offsetp> from a count of bytes from the
start of the string, to a count of the equivalent number of UTF-8 chars.
Handles magic and type coercion.
=for apidoc sv_eq
Returns a boolean indicating whether the strings in the two SVs are
-identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+identical. Is UTF-8 and C<'use bytes'> aware, handles get magic, and will
coerce its args to strings if necessary.
=for apidoc sv_eq_flags
Returns a boolean indicating whether the strings in the two SVs are
-identical. Is UTF-8 and 'use bytes' aware and coerces its args to strings
-if necessary. If the flags include SV_GMAGIC, it handles get-magic, too.
+identical. Is UTF-8 and S<C<'use bytes'>> aware and coerces its args to strings
+if necessary. If C<flags> includes C<SV_GMAGIC>, it handles get-magic, too.
=cut
*/
Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+C<sv2>. Is UTF-8 and S<C<'use bytes'>> aware, handles get magic, and will
coerce its args to strings if necessary. See also C<L</sv_cmp_locale>>.
=for apidoc sv_cmp_flags
Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>. Is UTF-8 and 'use bytes' aware and will coerce its args to strings
-if necessary. If the flags include SV_GMAGIC, it handles get magic. See
+C<sv2>. Is UTF-8 and S<C<'use bytes'>> aware and will coerce its args to strings
+if necessary. If the flags includes C<SV_GMAGIC>, it handles get magic. See
also C<L</sv_cmp_locale_flags>>.
=cut
=for apidoc sv_cmp_locale
Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
-'use bytes' aware, handles get magic, and will coerce its args to strings
+S<C<'use bytes'>> aware, handles get magic, and will coerce its args to strings
if necessary. See also C<L</sv_cmp>>.
=for apidoc sv_cmp_locale_flags
Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
-'use bytes' aware and will coerce its args to strings if necessary. If the
-flags contain SV_GMAGIC, it handles get magic. See also C<L</sv_cmp_flags>>.
+S<C<'use bytes'>> aware and will coerce its args to strings if necessary. If
+the flags contain C<SV_GMAGIC>, it handles get magic. See also
+C<L</sv_cmp_flags>>.
=cut
*/
=for apidoc sv_collxfrm_flags
Add Collate Transform magic to an SV if it doesn't already have it. If the
-flags contain SV_GMAGIC, it handles get-magic.
+flags contain C<SV_GMAGIC>, it handles get-magic.
-Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
+Any scalar variable may carry C<PERL_MAGIC_collxfrm> magic that contains the
scalar data of the variable, but transformed to such a format that a normal
memory comparison can be used to compare the data according to the locale
settings.
Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
The new SV is marked as mortal. It will be destroyed "soon", either by an
-explicit call to FREETMPS, or by an implicit call at places such as
+explicit call to C<FREETMPS>, or by an implicit call at places such as
statement boundaries. See also C<L</sv_newmortal>> and C<L</sv_2mortal>>.
=cut
Creates a new null SV which is mortal. The reference count of the SV is
set to 1. It will be destroyed "soon", either by an explicit call to
-FREETMPS, or by an implicit call at places such as statement boundaries.
+C<FREETMPS>, or by an implicit call at places such as statement boundaries.
See also C<L</sv_mortalcopy>> and C<L</sv_2mortal>>.
=cut
=for apidoc sv_2mortal
Marks an existing SV as mortal. The SV will be destroyed "soon", either
-by an explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. SvTEMP() is turned on which means that the SV's
+by an explicit call to C<FREETMPS>, or by an implicit call at places such as
+statement boundaries. C<SvTEMP()> is turned on which means that the SV's
string buffer can be "stolen" if this SV is copied. See also
C<L</sv_newmortal>> and C<L</sv_mortalcopy>>.
Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
characters) into it. The reference count for the
SV is set to 1. If C<len> is zero, Perl will compute the length using
-strlen(), (which means if you use this option, that C<s> can't have embedded
+C<strlen()>, (which means if you use this option, that C<s> can't have embedded
C<NUL> characters and has to have a terminating C<NUL> byte).
For efficiency, consider using C<newSVpvn> instead.
Creates a new SV from the hash key structure. It will generate scalars that
point to the shared string table where possible. Returns a new (undefined)
-SV if the hek is NULL.
+SV if C<hek> is NULL.
=cut
*/
/*
=for apidoc newSVpvn_share
-Creates a new SV with its SvPVX_const pointing to a shared string in the string
+Creates a new SV with its C<SvPVX_const> pointing to a shared string in the string
table. If the string does not already exist in the table, it is
-created first. Turns on the SvIsCOW flag (or READONLY
-and FAKE in 5.16 and earlier). If the C<hash> parameter
+created first. Turns on the C<SvIsCOW> flag (or C<READONLY>
+and C<FAKE> in 5.16 and earlier). If the C<hash> parameter
is non-zero, that value is used; otherwise the hash is computed.
The string's hash can later be retrieved from the SV
with the C<SvSHARED_HASH()> macro. The idea here is
that as the string table is used for shared hash keys these strings will have
-SvPVX_const == HeKEY and hash lookup will avoid string compare.
+C<SvPVX_const == HeKEY> and hash lookup will avoid string compare.
=cut
*/
GV; or the recursive result if we're an RV; or the IO slot of the symbol
named after the PV if we're a string.
-'Get' magic is ignored on the sv passed in, but will be called on
-C<SvRV(sv)> if sv is an RV.
+'Get' magic is ignored on the C<sv> passed in, but will be called on
+C<SvRV(sv)> if C<sv> is an RV.
=cut
*/
Using various gambits, try to get a CV from an SV; in addition, try if
possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
-The flags in C<lref> are passed to gv_fetchsv.
+The flags in C<lref> are passed to C<gv_fetchsv>.
=cut
*/
Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. If the C<pv> argument is
NULL then C<PL_sv_undef> will be placed
+the new SV. If the C<pv> argument is
C<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<NULL> to avoid the blessing. The new SV
will have a reference count of 1, and the RV will be returned.
output to an SV. As with C<sv_catpvfn> called with a non-null C-style
variable argument list, argument reordering is not supported.
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
+(including, but not limited to, SVs with a UTF-8 PV formatted with C<%s>,
+and characters >255 formatted with C<%c>), the original SV might get
upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
C<L</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.
Processes its arguments like C<vsprintf> and appends the formatted output
to an SV. Uses an array of SVs if the C-style variable argument list is
-missing (NULL). Argument reordering (using format specifiers like C<%2$d>
+missing (C<NULL>). Argument reordering (using format specifiers like C<%2$d>
or C<%*2$d>) is supported only when using an array of SVs; using a C-style
C<va_list> argument list with a format string that uses argument reordering
will yield an exception.
Create and return a new interpreter by cloning the current one.
-perl_clone takes these flags as parameters:
+C<perl_clone> takes these flags as parameters:
-CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
+C<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
+The pseudo-fork code uses C<COPY_STACKS> while the
threads->create doesn't.
-CLONEf_KEEP_PTR_TABLE -
-perl_clone keeps a ptr_table with the pointer of the old
+C<CLONEf_KEEP_PTR_TABLE> -
+C<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
+refcount. If C<KEEP_PTR_TABLE> is not set then C<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
+variable who are outside the graph perl scans, an example of this
code is in F<threads.xs> create.
-CLONEf_CLONE_HOST -
+C<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,
=for apidoc sv_recode_to_utf8
-The encoding is assumed to be an Encode object, on entry the PV
-of the sv is assumed to be octets in that encoding, and the sv
+C<encoding> is assumed to be an C<Encode> object, on entry the PV
+of C<sv> is assumed to be octets in that encoding, and C<sv>
will be converted into Unicode (and UTF-8).
-If the sv already is UTF-8 (or if it is not POK), or if the encoding
-is not a reference, nothing is done to the sv. If the encoding is not
+If C<sv> already is UTF-8 (or if it is not C<POK>), or if C<encoding>
+is not a reference, nothing is done to C<sv>. If C<encoding> is not
an C<Encode::XS> Encoding object, bad things will happen.
(See F<lib/encoding.pm> and L<Encode>.)
-The PV of the sv is returned.
+The PV of C<sv> is returned.
=cut */
/*
=for apidoc sv_cat_decode
-The encoding is assumed to be an Encode object, the PV of the ssv is
+C<encoding> is assumed to be an C<Encode> object, the PV of C<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.
+from the position which S<C<(PV + *offset)>> pointed to. C<dsv> will be
+concatenated the decoded UTF-8 string from C<ssv>. Decoding will terminate
+when the string C<tstr> appears in decoding output or the input ends on
+the PV of C<ssv>. The value which C<offset> points will be modified
+to the last input position on C<ssv>.
Returns TRUE if the terminator was found, else returns FALSE.
Find the name of the undefined variable (if any) that caused the operator
to issue a "Use of uninitialized value" warning.
-If match is true, only return a name if its value matches uninit_sv.
-So roughly speaking, if a unary operator (such as OP_COS) generates a
+If match is true, only return a name if its value matches C<uninit_sv>.
+So roughly speaking, if a unary operator (such as C<OP_COS>) generates a
warning, then following the direct child of the op may yield an
-OP_PADSV or OP_GV that gives the name of the undefined variable. On the
-other hand, with OP_ADD there are two branches to follow, so we only print
+C<OP_PADSV> or C<OP_GV> that gives the name of the undefined variable. On the
+other hand, with C<OP_ADD> there are two branches to follow, so we only print
the variable name if we get an exact match.
-desc_p points to a string pointer holding the description of the op.
+C<desc_p> points to a string pointer holding the description of the op.
This may be updated if needed.
The name is returned as a mortal SV.
-Assumes that PL_op is the op that originally triggered the error, and that
-PL_comppad/PL_curpad points to the currently executing pad.
+Assumes that C<PL_op> is the OP that originally triggered the error, and that
+C<PL_comppad>/C<PL_curpad> points to the currently executing pad.
=cut
*/
These are most easily explained from the bottom up.
-SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for
-subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays.
+C<SVt_PVIO> is for I/O objects, C<SVt_PVFM> for formats, C<SVt_PVCV> for
+subroutines, C<SVt_PVHV> for hashes and C<SVt_PVAV> for arrays.
All the others are scalar types, that is, things that can be bound to a
C<$> variable. For these, the internal types are mostly orthogonal to
Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether
something is a scalar.
-SVt_PVGV represents a typeglob. If !SvFAKE(sv), then it is a real,
-incoercible typeglob. If SvFAKE(sv), then it is a scalar to which a
+C<SVt_PVGV> represents a typeglob. If C<!SvFAKE(sv)>, then it is a real,
+incoercible typeglob. If C<SvFAKE(sv)>, then it is a scalar to which a
typeglob has been assigned. Assigning to it again will stop it from being
-a typeglob. SVt_PVLV represents a scalar that delegates to another scalar
+a typeglob. C<SVt_PVLV> represents a scalar that delegates to another scalar
behind the scenes. It is used, e.g., for the return value of C<substr> and
for tied hash and array elements. It can hold any scalar value, including
-a typeglob. SVt_REGEXP is for regular
-expressions. SVt_INVLIST is for Perl
+a typeglob. C<SVt_REGEXP> is for regular
+expressions. C<SVt_INVLIST> is for Perl
core internal use only.
-SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression,
+C<SVt_PVMG> represents a "normal" scalar (not a typeglob, regular expression,
or delegate). Since most scalars do not need all the internal fields of a
PVMG, we save memory by allocating smaller structs when possible. All the
-other types are just simpler forms of SVt_PVMG, with fewer internal fields.
- SVt_NULL can only hold undef. SVt_IV can hold undef, an integer, or a
-reference. (SVt_RV is an alias for SVt_IV, which exists for backward
-compatibility.) SVt_NV can hold any of those or a double. SVt_PV can only
-hold undef or a string. SVt_PVIV is a superset of SVt_PV and SVt_IV.
-SVt_PVNV is similar. SVt_PVMG can hold anything SVt_PVNV can hold, but it
+other types are just simpler forms of C<SVt_PVMG>, with fewer internal fields.
+C<SVt_NULL> can only hold undef. C<SVt_IV> can hold undef, an integer, or a
+reference. (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
+compatibility.) C<SVt_NV> can hold any of those or a double. C<SVt_PV> can only
+hold C<undef> or a string. C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
+C<SVt_PVNV> is similar. C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
can, but does not have to, be blessed or magical.
=for apidoc AmU||SVt_NULL
=for apidoc Am|SV*|SvREFCNT_inc|SV* sv
Increments the reference count of the given SV, returning the SV.
-All of the following SvREFCNT_inc* macros are optimized versions of
-SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
+All of the following C<SvREFCNT_inc>* macros are optimized versions of
+C<SvREFCNT_inc>, and can be replaced with C<SvREFCNT_inc>.
=for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_void|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the
+Same as C<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.
=for apidoc Am|void|SvREFCNT_inc_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that C<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple|SV* sv
-Same as SvREFCNT_inc, but can only be used with expressions without side
+Same as C<SvREFCNT_inc>, but can only be used with expressions without side
effects. Since we don't have to store a temporary value, it's faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple_NN|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc_simple>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_simple_void|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+Same as C<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.
=for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that C<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV. C<sv> may be NULL.
+Decrements the reference count of the given SV. C<sv> may be C<NULL>.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
-Same as SvREFCNT_dec, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_dec>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|svtype|SvTYPE|SV* sv
Unsets the IV status of an SV.
=for apidoc Am|void|SvIOK_only|SV* sv
-Tells an SV that it is an integer and disables all other OK bits.
+Tells an SV that it is an integer and disables all other C<OK> bits.
=for apidoc Am|void|SvIOK_only_UV|SV* sv
-Tells an SV that it is an unsigned integer and disables all other OK bits.
+Tells an SV that it is an unsigned integer and disables all other C<OK> bits.
=for apidoc Am|bool|SvIOK_UV|SV* sv
Returns a boolean indicating whether the SV contains an integer that must be
interpreted as unsigned. A non-negative integer whose value is within the
-range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvUOK|SV* sv
Returns a boolean indicating whether the SV contains an integer that must be
interpreted as unsigned. A non-negative integer whose value is within the
-range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvIOK_notUV|SV* sv
Returns a boolean indicating whether the SV contains a signed integer.
Unsets the PV status of an SV.
=for apidoc Am|void|SvPOK_only|SV* sv
-Tells an SV that it is a string and disables all other OK bits.
+Tells an SV that it is a string and disables all other C<OK> bits.
Will also turn off the UTF-8 status.
=for apidoc Am|bool|SvVOK|SV* sv
=for apidoc Am|U32|SvOOK|SV* sv
Returns a U32 indicating whether the pointer to the string buffer is offset.
This hack is used internally to speed up removal of characters from the
-beginning of a SvPV. When SvOOK is true, then the start of the
-allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
-This offset used to be stored in SvIVX, but is now stored within the spare
+beginning of a C<SvPV>. When C<SvOOK> is true, then the start of the
+allocated string buffer is actually C<SvOOK_offset()> bytes before C<SvPVX>.
+This offset used to be stored in C<SvIVX>, but is now stored within the spare
part of the buffer.
=for apidoc Am|U32|SvROK|SV* sv
=for apidoc Am|IV|SvIVX|SV* sv
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<L</SvIV>>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvIV>>.
=for apidoc Am|UV|SvUVX|SV* sv
Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<L</SvUV>>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvUV>>.
=for apidoc Am|NV|SvNVX|SV* sv
Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<L</SvNV>>.
+Only use when you are sure C<SvNOK> is true. See also C<L</SvNV>>.
=for apidoc Am|char*|SvPVX|SV* sv
Returns a pointer to the physical string in the SV. The SV must contain a
string. Prior to 5.9.3 it is not safe
to execute this macro unless the SV's
-type >= SVt_PV.
+type >= C<SVt_PV>.
This is also used to store the name of an autoloaded subroutine in an XS
AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>.
Returns a pointer to the spot just after the last character in
the string which is in the SV, where there is usually a trailing
C<NUL> character (even though Perl scalars do not strictly require it).
-See C<L</SvCUR>>. Access the character as *(SvEND(sv)).
+See C<L</SvCUR>>. Access the character as C<*(SvEND(sv))>.
Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to
unallocated memory.
C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
=for apidoc Am|void|SvNV_set|SV* sv|NV val
-Set the value of the NV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the NV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvPV_set|SV* sv|char* val
This is probably not what you want to use, you probably wanted
Remember to free the previous PV buffer. There are many things to check.
Beware that the existing pointer may be involved in copy-on-write or other
mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
-C<SvPV_force> (or check the SvIsCOW flag) first to make sure this
+C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
modification is safe. Then finally, if it is not a COW, call C<SvPV_free> to
free the previous PV buffer.
=for apidoc Am|void|SvUV_set|SV* sv|UV val
-Set the value of the UV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the UV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvRV_set|SV* sv|SV* val
-Set the value of the RV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the RV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvMAGIC_set|SV* sv|MAGIC* val
-Set the value of the MAGIC pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the MAGIC pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvSTASH_set|SV* sv|HV* val
-Set the value of the STASH pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the STASH pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len
Set the current length of the string which is in the SV. See C<L</SvCUR>>
=for apidoc Am|U32|SvUTF8|SV* sv
Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up
properly, this indicates whether or not the SV contains UTF-8 encoded data.
-You should use this I<after> a call to SvPV() or one of its variants, in
+You should use this I<after> a call to C<SvPV()> or one of its variants, in
case any call to string overloading updates the internal flag.
If you want to take into account the L<bytes> pragma, use C<L</DO_UTF8>>
Do not use frivolously.
=for apidoc Am|void|SvPOK_only_UTF8|SV* sv
-Tells an SV that it is a string and disables all other OK bits,
+Tells an SV that it is a string and disables all other C<OK> bits,
and leaves the UTF-8 status as it was.
=cut
/*
=for apidoc m|U32|SvTHINKFIRST|SV *sv
-A quick flag check to see whether an sv should be passed to sv_force_normal
-to be "downgraded" before SvIVX or SvPVX can be modified directly.
+A quick flag check to see whether an C<sv> should be passed to C<sv_force_normal>
+to be "downgraded" before C<SvIVX> or C<SvPVX> can be modified directly.
-For example, if your scalar is a reference and you want to modify the SvIVX
-slot, you can't just do SvROK_off, as that will leak the referent.
+For example, if your scalar is a reference and you want to modify the C<SvIVX>
+slot, you can't just do C<SvROK_off>, as that will leak the referent.
This is used internally by various sv-modifying functions, such as
-sv_setsv, sv_setiv and sv_pvn_force.
+C<sv_setsv>, C<sv_setiv> and C<sv_pvn_force..
One case that this does not handle is a gv without SvFAKE set. After
it will still be a gv.
-SvTHINKFIRST sometimes produces false positives. In those cases
-sv_force_normal does nothing.
+C<SvTHINKFIRST> sometimes produces false positives. In those cases
+C<sv_force_normal> does nothing.
=cut
*/
stringified version becoming C<SvPOK>. Handles 'get' magic. The
C<len> variable will be set to the length of the string (this is a macro, so
don't use C<&len>). See also C<L</SvPVx>> for a version which guarantees to
-evaluate sv only once.
+evaluate C<sv> only once.
Note that there is no guarantee that the return value of C<SvPV()> is
equal to C<SvPVX(sv)>, or that C<SvPVX(sv)> contains valid data, or that
successive calls to C<SvPV(sv)> will return the same pointer value each
time. This is due to the way that things like overloading and
Copy-On-Write are handled. In these cases, the return value may point to
-a temporary buffer or similar. If you absolutely need the SvPVX field to
+a temporary buffer or similar. If you absolutely need the C<SvPVX> field to
be valid (for example, if you intend to write to it), then see
C<L</SvPV_force>>.
=for apidoc Am|IV|SvIV|SV* sv
Coerces the given SV to an integer and returns it. See C<L</SvIVx>> for a
-version which guarantees to evaluate sv only once.
+version which guarantees to evaluate C<sv> only once.
=for apidoc Am|IV|SvIV_nomg|SV* sv
Like C<SvIV> but doesn't process magic.
=for apidoc Am|NV|SvNV|SV* sv
Coerce the given SV to a double and return it. See C<L</SvNVx>> for a version
-which guarantees to evaluate sv only once.
+which guarantees to evaluate C<sv> only once.
=for apidoc Am|NV|SvNV_nomg|SV* sv
Like C<SvNV> but doesn't process magic.
=for apidoc Am|UV|SvUV|SV* sv
Coerces the given SV to an unsigned integer and returns it. See C<L</SvUVx>>
-for a version which guarantees to evaluate sv only once.
+for a version which guarantees to evaluate C<sv> only once.
=for apidoc Am|UV|SvUV_nomg|SV* sv
Like C<SvUV> but doesn't process magic.
=for apidoc Am|bool|SvTRUE|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Handles 'get' magic
-unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the
+false. See C<L</SvOK>> for a defined/undefined test. Handles 'get' magic
+unless the scalar is already C<SvPOK>, C<SvIOK> or C<SvNOK> (the public, not the
private flags).
=for apidoc Am|bool|SvTRUE_nomg|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Does not handle 'get' magic.
+false. See C<L</SvOK>> for a defined/undefined test. Does not handle 'get' magic.
=for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+Like C<SvPV_force>, but converts C<sv> to utf8 first if necessary.
=for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
+Like C<SvPV>, but converts C<sv> to utf8 first if necessary.
=for apidoc Am|char*|SvPVutf8_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to utf8 first if necessary.
=for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
+Like C<SvPV_force>, but converts C<sv> to utf8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8_force>
otherwise.
=for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
+Like C<SvPV>, but converts C<sv> to utf8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8>
otherwise.
=for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte_force>
otherwise.
=for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte>
otherwise.
=for apidoc Am|U32|SvIsCOW|SV* sv
=for apidoc Amdb|STRLEN|sv_utf8_upgrade_nomg|NN SV *sv
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
+Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
=cut
*/
#define newRV_inc(sv) newRV(sv)
-/* the following macros update any magic values this sv is associated with */
+/* the following macros update any magic values this C<sv> is associated with */
/*
=head1 Magical Functions
argument more than once.
=for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+Calls C<sv_setsv> if C<dsv> is not the same as C<ssv>. May evaluate arguments
more than once. Does not handle 'set' magic on the destination SV.
=for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
+Calls a non-destructive version of C<sv_setsv> if C<dsv> is not the same as
+C<ssv>. May evaluate arguments more than once.
=for apidoc Am|void|SvSetMagicSV|SV* dsv|SV* ssv
Like C<SvSetSV>, but does any set magic required afterwards.
Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
=for apidoc Am|void|SvSHARE|SV* sv
-Arranges for sv to be shared between threads if a suitable module
+Arranges for C<sv> to be shared between threads if a suitable module
has been loaded.
=for apidoc Am|void|SvLOCK|SV* sv
-Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+Arranges for a mutual exclusion lock to be obtained on C<sv> if a suitable module
has been loaded.
=for apidoc Am|void|SvUNLOCK|SV* sv
-Releases a mutual exclusion lock on sv if a suitable module
+Releases a mutual exclusion lock on C<sv> if a suitable module
has been loaded.
=head1 SV Manipulation Functions
indicated number of bytes (remember to reserve space for an extra trailing
C<NUL> character). Calls C<sv_grow> to perform the expansion if necessary.
Returns a pointer to the character
-buffer. SV must be of type >= SVt_PV. One
+buffer. SV must be of type >= C<SVt_PV>. One
alternative is to call C<sv_grow> if you are not sure of the type of SV.
=cut
=for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8
Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
-characters) into it. If utf8 is true, calls
+characters) into it. If C<utf8> is true, calls
C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
=cut
/*
=for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
-Reads into C<len> the offset from SvPVX back to the true start of the
+Reads into C<len> the offset from C<SvPVX> back to the true start of the
allocated buffer, which will be non-zero if C<sv_chop> has been used to
efficiently remove characters from start of the buffer. Implemented as a
macro, which takes the address of C<len>, which must be of type C<STRLEN>.
legal Unicode or are problematic, unless C<flags> contains one or more of the
following flags:
-If C<uv> is a Unicode surrogate code point and UNICODE_WARN_SURROGATE is set,
+If C<uv> is a Unicode surrogate code point and C<UNICODE_WARN_SURROGATE> is set,
the function will raise a warning, provided UTF8 warnings are enabled. If instead
-UNICODE_DISALLOW_SURROGATE is set, the function will fail and return NULL.
+C<UNICODE_DISALLOW_SURROGATE> is set, the function will fail and return NULL.
If both flags are set, the function will both warn and return NULL.
-The UNICODE_WARN_NONCHAR and UNICODE_DISALLOW_NONCHAR flags
+The C<UNICODE_WARN_NONCHAR> and C<UNICODE_DISALLOW_NONCHAR> flags
affect how the function handles a Unicode non-character. And likewise, the
-UNICODE_WARN_SUPER and UNICODE_DISALLOW_SUPER flags affect the handling of
+C<UNICODE_WARN_SUPER> and C<UNICODE_DISALLOW_SUPER> flags affect the handling of
code points that are
above the Unicode maximum of 0x10FFFF. Code points above 0x7FFF_FFFF (which are
even less portable) can be warned and/or disallowed even if other above-Unicode
-code points are accepted, by the UNICODE_WARN_FE_FF and UNICODE_DISALLOW_FE_FF
-flags.
+code points are accepted, by the C<UNICODE_WARN_FE_FF> and
+C<UNICODE_DISALLOW_FE_FF> flags.
-And finally, the flag UNICODE_WARN_ILLEGAL_INTERCHANGE selects all four of the
-above WARN flags; and UNICODE_DISALLOW_ILLEGAL_INTERCHANGE selects all four
-DISALLOW flags.
+And finally, the flag C<UNICODE_WARN_ILLEGAL_INTERCHANGE> selects all four of
+the above WARN flags; and C<UNICODE_DISALLOW_ILLEGAL_INTERCHANGE> selects all
+four DISALLOW flags.
=cut
*/
malformations, the Unicode REPLACEMENT CHARACTER is returned, as these have no
determinable reasonable value.
-The UTF8_CHECK_ONLY flag overrides the behavior when a non-allowed (by other
+The C<UTF8_CHECK_ONLY> flag overrides the behavior when a non-allowed (by other
flags) malformation is found. If this flag is set, the routine assumes that
the caller will raise a warning, and this function will silently just set
C<retlen> to C<-1> (cast to C<STRLEN>) and return zero.
Note that this API requires disambiguation between successful decoding a C<NUL>
-character, and an error return (unless the UTF8_CHECK_ONLY flag is set), as
+character, and an error return (unless the C<UTF8_CHECK_ONLY> flag is set), as
in both cases, 0 is returned. To disambiguate, upon a zero return, see if the
first byte of C<s> is 0 as well. If so, the input was a C<NUL>; if not, the
input had an error.
Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF.
By default these are considered regular code points, but certain situations
warrant special handling for them. If C<flags> contains
-UTF8_DISALLOW_ILLEGAL_INTERCHANGE, all three classes are treated as
-malformations and handled as such. The flags UTF8_DISALLOW_SURROGATE,
-UTF8_DISALLOW_NONCHAR, and UTF8_DISALLOW_SUPER (meaning above the legal Unicode
-maximum) can be set to disallow these categories individually.
-
-The flags UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_SURROGATE,
-UTF8_WARN_NONCHAR, and UTF8_WARN_SUPER will cause warning messages to be raised
-for their respective categories, but otherwise the code points are considered
-valid (not malformations). To get a category to both be treated as a
-malformation and raise a warning, specify both the WARN and DISALLOW flags.
+C<UTF8_DISALLOW_ILLEGAL_INTERCHANGE>, all three classes are treated as
+malformations and handled as such. The flags C<UTF8_DISALLOW_SURROGATE>,
+C<UTF8_DISALLOW_NONCHAR>, and C<UTF8_DISALLOW_SUPER> (meaning above the legal
+Unicode maximum) can be set to disallow these categories individually.
+
+The flags C<UTF8_WARN_ILLEGAL_INTERCHANGE>, C<UTF8_WARN_SURROGATE>,
+C<UTF8_WARN_NONCHAR>, and C<UTF8_WARN_SUPER> will cause warning messages to be
+raised for their respective categories, but otherwise the code points are
+considered valid (not malformations). To get a category to both be treated as
+a malformation and raise a warning, specify both the WARN and DISALLOW flags.
(But note that warnings are not raised if lexically disabled nor if
-UTF8_CHECK_ONLY is also specified.)
+C<UTF8_CHECK_ONLY> is also specified.)
Very large code points (above 0x7FFF_FFFF) are considered more problematic than
the others that are above the Unicode legal maximum. There are several
representable by a UV on ASCII platforms, but not by an IV, which means that
the number of operations that can be performed on them is quite restricted.)
The UTF-8 encoding on ASCII platforms for these large code points begins with a
-byte containing 0xFE or 0xFF. The UTF8_DISALLOW_FE_FF flag will cause them to
+byte containing 0xFE or 0xFF. The C<UTF8_DISALLOW_FE_FF> flag will cause them to
be treated as malformations, while allowing smaller above-Unicode code points.
-(Of course UTF8_DISALLOW_SUPER will treat all above-Unicode code points,
+(Of course C<UTF8_DISALLOW_SUPER> will treat all above-Unicode code points,
including these, as malformations.)
-Similarly, UTF8_WARN_FE_FF acts just like
+Similarly, C<UTF8_WARN_FE_FF> acts just like
the other WARN flags, but applies just to these code points.
All other code points corresponding to Unicode characters, including private
If C<s> does not point to a well-formed UTF-8 character and UTF8 warnings are
enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
-NULL) to -1. If those warnings are off, the computed value, if well-defined
+C<NULL>) to -1. If those warnings are off, the computed value, if well-defined
(or the Unicode REPLACEMENT CHARACTER if not), is silently returned, and
-C<*retlen> is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is
+C<*retlen> is set (if C<retlen> isn't C<NULL>) so that (S<C<s> + C<*retlen>>) is
the next possible position in C<s> that could begin a non-malformed character.
See L</utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is
returned.
C<swashp> is a pointer to the swash to use.
Both the special and normal mappings are stored in F<lib/unicore/To/Foo.pl>,
-and loaded by SWASHNEW, using F<lib/utf8_heavy.pl>. C<special> (usually,
+and loaded by C<SWASHNEW>, using F<lib/utf8_heavy.pl>. C<special> (usually,
but not always, a multicharacter mapping), is tried first.
C<special> is a string, normally C<NULL> or C<"">. C<NULL> means to not use
than these two are treated as the name of the hash containing the special
mappings, like C<"utf8::ToSpecLower">.
-C<normal> is a string like "ToLower" which means the swash
-%utf8::ToLower.
+C<normal> is a string like C<"ToLower"> which means the swash
+C<%utf8::ToLower>.
=cut */
Build to the scalar C<dsv> a displayable version of the string C<spv>,
length C<len>, the displayable version being at most C<pvlim> bytes long
-(if longer, the rest is truncated and "..." will be appended).
+(if longer, the rest is truncated and C<"..."> will be appended).
-The C<flags> argument can have UNI_DISPLAY_ISPRINT set to display
-isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
-to display the \\[nrfta\\] as the backslashed versions (like '\n')
-(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
-UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
-UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
+The C<flags> argument can have C<UNI_DISPLAY_ISPRINT> set to display
+C<isPRINT()>able characters as themselves, C<UNI_DISPLAY_BACKSLASH>
+to display the C<\\[nrfta\\]> as the backslashed versions (like C<"\n">)
+(C<UNI_DISPLAY_BACKSLASH> is preferred over C<UNI_DISPLAY_ISPRINT> for C<"\\">).
+C<UNI_DISPLAY_QQ> (and its alias C<UNI_DISPLAY_REGEX>) have both
+C<UNI_DISPLAY_BACKSLASH> and C<UNI_DISPLAY_ISPRINT> turned on.
The pointer to the PV of the C<dsv> is returned.
scanning won't continue past that goal. Correspondingly for C<l2> with respect to
C<s2>.
-If C<pe1> is non-NULL and the pointer it points to is not NULL, that pointer is
+If C<pe1> is non-C<NULL> and the pointer it points to is not C<NULL>, that pointer is
considered an end pointer to the position 1 byte past the maximum point
in C<s1> beyond which scanning will not continue under any circumstances.
(This routine assumes that UTF-8 encoded input strings are not malformed;
characters, all of them must be matched (see tr21 reference below for
'folding').
-Upon a successful match, if C<pe1> is non-NULL,
+Upon a successful match, if C<pe1> is non-C<NULL>,
it will be set to point to the beginning of the I<next> character of C<s1>
beyond what was matched. Correspondingly for C<pe2> and C<s2>.
=for apidoc fbm_compile
-Analyses the string in order to make fast searches on it using fbm_instr()
+Analyses the string in order to make fast searches on it using C<fbm_instr()>
-- the Boyer-Moore algorithm.
=cut
Returns the location of the SV in the string delimited by C<big> and
C<bigend>. It returns C<NULL> if the string can't be found. The C<sv>
-does not have to be fbm_compiled, but the search will not be as fast
+does not have to be C<fbm_compiled>, but the search will not be as fast
then.
=cut
/*
=for apidoc foldEQ
-Returns true if the leading len bytes of the strings s1 and s2 are the same
+Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the
+same
case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes
match themselves and their opposite case counterparts. Non-cased and non-ASCII
range bytes match only themselves.
/*
=for apidoc foldEQ_locale
-Returns true if the leading len bytes of the strings s1 and s2 are the same
-case-insensitively in the current locale; false otherwise.
+Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the
+same case-insensitively in the current locale; false otherwise.
=cut
*/
=for apidoc 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
+which is shared between threads. (With the specific difference that a C<NULL>
pointer is not acceptable)
=cut
=for apidoc getcwd_sv
-Fill the sv with current working directory
+Fill C<sv> with current working directory
=cut
*/
Dummy routine which "shares" an SV when there is no sharing module present.
Or "locks" it. Or "unlocks" it. In other
words, ignores its single SV argument.
-Exists to avoid test for a NULL function pointer and because it could
+Exists to avoid test for a C<NULL> function pointer and because it could
potentially warn under some level of strict-ness.
=cut
Dummy routine which reports that object can be destroyed when there is no
sharing module present. It ignores its single SV argument, and returns
-'true'. Exists to avoid test for a NULL function pointer and because it
+'true'. Exists to avoid test for a C<NULL> function pointer and because it
could potentially warn under some level of strict-ness.
=cut
/*
=for apidoc quadmath_format_single
-quadmath_snprintf() is very strict about its format string and will
+C<quadmath_snprintf()> is very strict about its C<format> string and will
fail, returning -1, if the format is invalid. It acccepts exactly
one format spec.
-quadmath_format_single() checks that the intended single spec looks
+C<quadmath_format_single()> checks that the intended single spec looks
sane: begins with C<%>, has only one C<%>, ends with C<[efgaEFGA]>,
and has C<Q> before it. This is not a full "printf syntax check",
just the basics.
Returns the format if it is valid, NULL if not.
-quadmath_format_single() can and will actually patch in the missing
+C<quadmath_format_single()> can and will actually patch in the missing
C<Q>, if necessary. In this case it will return the modified copy of
the format, B<which the caller will need to free.>
/*
=for apidoc quadmath_format_needed
-quadmath_format_needed() returns true if the format string seems to
-contain at least one non-Q-prefixed %[efgaEFGA] format specifier,
+C<quadmath_format_needed()> returns true if the C<format> string seems to
+contain at least one non-Q-prefixed C<%[efgaEFGA]> format specifier,
or returns false otherwise.
The format specifier detection is not complete printf-syntax detection,
but it should catch most common cases.
If true is returned, those arguments B<should> in theory be processed
-with quadmath_snprintf(), but in case there is more than one such
+with C<quadmath_snprintf()>, but in case there is more than one such
format specifier (see L</quadmath_format_single>), and if there is
anything else beyond that one (even just a single byte), they
-B<cannot> be processed because quadmath_snprintf() is very strict,
+B<cannot> be processed because C<quadmath_snprintf()> is very strict,
accepting only one format spec, and nothing else.
In this case, the code should probably fail.
=for apidoc get_c_backtrace
Collects the backtrace (aka "stacktrace") into a single linear
-malloced buffer, which the caller B<must> Perl_free_c_backtrace().
+malloced buffer, which the caller B<must> C<Perl_free_c_backtrace()>.
-Scans the frames back by depth + skip, then drops the skip innermost,
-returning at most depth frames.
+Scans the frames back by S<C<depth + skip>>, then drops the C<skip> innermost,
+returning at most C<depth> frames.
=cut
*/
/*
=for apidoc get_c_backtrace_dump
-Returns a SV a dump of |depth| frames of the call stack, skipping
-the |skip| innermost ones. depth of 20 is usually enough.
+Returns a SV containing a dump of C<depth> frames of the call stack, skipping
+the C<skip> innermost ones. C<depth> of 20 is usually enough.
The appended output looks like:
The fields are tab-separated. The first column is the depth (zero
being the innermost non-skipped frame). In the hex:offset, the hex is
-where the program counter was in S_parse_body, and the :offset (might
-be missing) tells how much inside the S_parse_body the program counter was.
+where the program counter was in C<S_parse_body>, and the :offset (might
+be missing) tells how much inside the C<S_parse_body> the program counter was.
-The util.c:1716 is the source code file and line number.
+The C<util.c:1716> is the source code file and line number.
The F</usr/bin/perl> is obvious (hopefully).
/*
=for apidoc dump_c_backtrace
-Dumps the C backtrace to the given fp.
+Dumps the C backtrace to the given C<fp>.
Returns true if a backtrace could be retrieved, false if not.
https://perl5.git.perl.org / perl5.git / commitdiff