plus some typo fixes. I probably changed some things in perlintern, too.
=for apidoc Amn|(whatever)|RETVAL
Variable which is setup by C<xsubpp> to hold the return value for an
-XSUB. This is always the proper type for the XSUB. See
+XSUB. This is always the proper type for the XSUB. See
L<perlxs/"The RETVAL Variable">.
=for apidoc Amn|(whatever)|THIS
=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 XS_EXTERNAL macro.
=for apidoc AmU||XS_INTERNAL
Macro to declare an XSUB and its C parameter list without exporting the symbols.
handled automatically by C<xsubpp>.
=for apidoc Ams||dUNDERBAR
-Sets up any variable needed by the C<UNDERBAR> macro. It used to define
-C<padoff_du>, but it is currently a noop. However, it is strongly advised
+Sets up any variable needed by the C<UNDERBAR> macro. It used to define
+C<padoff_du>, but it is currently a noop. However, it is strongly advised
to still use it for ensuring past and future compatibility.
=for apidoc AmU||UNDERBAR
-The SV* corresponding to the $_ variable. Works even if there
+The SV* corresponding to the $_ variable. Works even if there
is a lexical $_ in scope.
=cut
print $fh "\n=head1 Undocumented functions\n\n";
print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
The following functions have been flagged as part of the public API,
-but are currently undocumented. Use them at your own risk, as the
+but are currently undocumented. Use them at your own risk, as the
interfaces are subject to change. Functions that are not listed in this
document are not intended for public use, and should NOT be used under any
circumstances.
If you use one of the undocumented functions below, you may wish to consider
-creating and submitting documentation for it. If your patch is accepted, this
+creating and submitting documentation
+for it. If your patch is accepted, this
will indicate that the interface is stable (unless it is explicitly marked
otherwise).
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
need to be actually stored within the array (as in the case of tied
-arrays). Otherwise, it can be dereferenced
+arrays). Otherwise, it can be dereferenced
to get the C<SV*> that was stored
there (= C<val>)).
=head1 Multicall Functions
=for apidoc Ams||dMULTICALL
-Declare local variables for a multicall. See L<perlcall/LIGHTWEIGHT CALLBACKS>.
+Declare local variables for a multicall.
See L<perlcall/LIGHTWEIGHT CALLBACKS>.
=for apidoc Ams||PUSH_MULTICALL
Opening bracket for a lightweight callback.
See L<perlcall/LIGHTWEIGHT CALLBACKS>.
=for apidoc Ams||MULTICALL
-Make a lightweight callback. See L<perlcall/LIGHTWEIGHT CALLBACKS>.
+Make a lightweight callback.
See L<perlcall/LIGHTWEIGHT CALLBACKS>.
=for apidoc Ams||POP_MULTICALL
Closing bracket for a lightweight callback.
or subroutines. For more information, see L<perlguts>.
=for apidoc Am|HV*|CvSTASH|CV* cv
-Returns the stash of the CV. A stash is the symbol table hash, containing
+Returns the stash of the CV. A stash is the symbol table hash, containing
the package-scoped variables in the package where the subroutine was defined.
For more information, see L<perlguts>.
using C<\x01F1> style escapes, otherwise if 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
+common escaped patterns like C<\n>.
+Otherwise, if PERL_PV_ESCAPE_NOBACKSLASH
then all chars below 255 will be treated as printable and
will be output as literals.
If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
-string will be escaped, regardless of max. If the output is to be in hex,
+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,
+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
+not a '\\'. This is because regexes very often contain backslashed
sequences, whereas '%' is not a particularly common character in patterns.
Returns a pointer to the escaped text as held by dsv.
pv_escape() and supporting quoting and ellipses.
If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
-double quoted with any double quotes in the string escaped. Otherwise
+double quoted with any double quotes in the string escaped. Otherwise
if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
angle brackets.
If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
string were output then an ellipsis C<...> will be appended to the
-string. Note that this happens AFTER it has been quoted.
+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
+quote (if there is one) but before the escaped text. If end_color
is non-null then it will be inserted after the escaped text but before
any quotes or ellipses.
=for apidoc dump_all
Dumps the entire optree of the current program starting at C<PL_main_root> to
-C<STDERR>. Also dumps the optrees for all visible subroutines in C<PL_defstash>.
+C<STDERR>. Also dumps the optrees for all visible subroutines in
+C<PL_defstash>.
=cut
*/
=head1 Handy Values
=for apidoc AmU||Nullch
-Null character pointer. (No longer available when C<PERL_CORE> is defined.)
+Null character pointer. (No longer available when C<PERL_CORE> is
+defined.)
=for apidoc AmU||Nullsv
-Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
+Null SV pointer.
(No longer available when C<PERL_CORE> is defined.)
=cut
*/
=for apidoc Am|bool|strnNE|char* s1|char* s2|STRLEN len
Test two strings to see if they are different. The C<len> parameter
-indicates the number of bytes to compare. Returns true or false. (A
+indicates the number of bytes to compare. Returns true or false. (A
wrapper for C<strncmp>).
=for apidoc Am|bool|strnEQ|char* s1|char* s2|STRLEN len
Test two strings to see if they are equal. The C<len> parameter indicates
-the number of bytes to compare. Returns true or false. (A wrapper for
+the number of bytes to compare. Returns true or false. (A wrapper for
C<strncmp>).
=cut
C<type> is the type. Can do overlapping moves. See also C<Copy>.
=for apidoc Am|void *|MoveD|void* src|void* dest|int nitems|type
-Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
+Like C<Move> but returns dest. Useful
+for encouraging compilers to tail-call
optimise.
=for apidoc Am|void|Copy|void* src|void* dest|int nitems|type
=for apidoc Am|void *|CopyD|void* src|void* dest|int nitems|type
-Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
+Like C<Copy> but returns dest. Useful
+for encouraging compilers to tail-call
optimise.
=for apidoc Am|void|Zero|void* dest|int nitems|type
=for apidoc Am|void *|ZeroD|void* dest|int nitems|type
-Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
+Like C<Zero> but returns dest. Useful
+for encouraging compilers to tail-call
optimise.
=for apidoc Am|void|StructCopy|type *src|type *dest|type
/*
=for apidoc hv_scalar
-Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
+Evaluates the hash in scalar context and returns the result. Handles magic
+when the hash is tied.
=cut
*/
/*
=for apidoc hv_fill
-Returns the number of hash buckets that happen to be in use. This function is
+Returns the number of hash buckets that
+happen to be in use. This function is
wrapped by the macro C<HvFILL>.
Previously this value was always stored in the HV structure, which created an
overhead on every hash (and pretty much every object) for something that was
-rarely used. Now we calculate it on demand the first time that it is needed,
-and cache it if that calculation is going to be costly to repeat. The cached
+rarely used. Now we calculate it on demand the first
+time that it is needed, and cache it if that calculation
+is going to be costly to repeat. The cached
value is updated by insertions and deletions, but (currently) discarded if
the hash is split.
Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
set the placeholders keys (for restricted hashes) will be returned in addition
-to normal keys. By default placeholders are automatically skipped over.
+to normal keys. By default placeholders are automatically skipped over.
Currently a placeholder is implemented with a value that is
C<&PL_sv_placeholder>. Note that the implementation of placeholders and
restricted hashes may change, and the implementation currently is
/*
=for apidoc cop_store_label
-Save a label into a C<cop_hints_hash>. You need to set flags to C<SVf_UTF8>
+Save a label into a C<cop_hints_hash>.
+You need to set flags to C<SVf_UTF8>
for a utf-8 label.
=cut
=for apidoc AmU||HEf_SVKEY
This flag, used in the length slot of hash entries and magic structures,
specifies the structure contains an C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+is to be expected. (For information only--not to be used).
=head1 Handy Values
Returns true if the name is in UTF8 encoding.
=for apidoc Am|char*|HvENAME|HV* stash
-Returns the effective name of a stash, or NULL if there is none. The
+Returns the effective name of a stash, or NULL if there is none. The
effective name represents a location in the symbol table where this stash
-resides. It is updated automatically when packages are aliased or deleted.
-A stash that is no longer in the symbol table has no effective name. This
+resides. It is updated automatically when packages are aliased or deleted.
+A stash that is no longer in the symbol table has no effective name. This
name is preferable to C<HvNAME> for use in MRO linearisations and isa
caches.
Returns true if the effective name is in UTF8 encoding.
=for apidoc Am|void*|HeKEY|HE* he
-Returns the actual pointer stored in the key slot of the hash entry. The
+Returns the actual pointer stored in the key slot of the hash entry. The
pointer may be either C<char*> or C<SV*>, depending on the value of
C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
usually preferable for finding the value of a key.
=for apidoc Am|STRLEN|HeKLEN|HE* he
If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
-be assigned to. The C<HePV()> macro is usually preferable for finding key
+be assigned to. The C<HePV()> macro is usually preferable for finding key
lengths.
=for apidoc Am|SV*|HeVAL|HE* he
-Returns the value slot (type C<SV*>) stored in the hash entry. Can be assigned
+Returns the value slot (type C<SV*>)
+stored in the hash entry. Can be assigned
to.
SV *foo= HeVAL(hv);
variable C<PL_na>, though this is rather less efficient than using a local
variable. Remember though, that hash keys in perl are free to contain
embedded nulls, so using C<strlen()> or similar is not a good way to find
-the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document. See also C<HeUTF8>.
+the length of hash keys. This is very similar to the C<SvPV()> macro
+described elsewhere in this document. See also C<HeUTF8>.
If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
/*
=for apidoc sv_taint
-Taint an SV. Use C<SvTAINTED_on> instead.
+Taint an SV. Use C<SvTAINTED_on> instead.
=cut
*/
/*
=for apidoc sv_2pv_nolen
-Like C<sv_2pv()>, but doesn't return the length too. You should usually
+Like C<sv_2pv()>, but doesn't return the length too. You should usually
use the macro wrapper C<SvPV_nolen(sv)> instead.
=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<sv_force_normal_flags>.
+an xpvmg. See also C<sv_force_normal_flags>.
=cut
*/
=for apidoc sv_iv
A private implementation of the C<SvIVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+cope with complex macro expressions. Always use the macro instead.
=cut
*/
=for apidoc sv_uv
A private implementation of the C<SvUVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+cope with complex macro expressions. Always use the macro instead.
=cut
*/
=for apidoc sv_nv
A private implementation of the C<SvNVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+cope with complex macro expressions. Always use the macro instead.
=cut
*/
=for apidoc sv_pvn
A private implementation of the C<SvPV> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+cope with complex macro expressions. Always use the macro instead.
=cut
*/
=for apidoc sv_pvbyten
A private implementation of the C<SvPVbyte> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
+which can't cope with complex macro expressions. Always use the macro
instead.
=cut
=for apidoc sv_pvutf8n
A private implementation of the C<SvPVutf8> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
+which can't cope with complex macro expressions. Always use the macro
instead.
=cut
/*
=for apidoc sv_usepvn
-Tells an SV to use C<ptr> to find its string value. Implemented by
+Tells an SV to use C<ptr> to find its string value. Implemented by
calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
-magic. See C<sv_usepvn_flags>.
+magic. See C<sv_usepvn_flags>.
=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 unpack() Perl function. Note: parameters strbeg,
+new_s and ocnt are not used. This call should not be used, use
+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 pack() Perl function. Note: parameters
+next_in_list and flags are not used. This call should not be used; use
+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 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
+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
compatibility, and should not be used.
=for apidoc mg_get
Do magic before a value is retrieved from the SV. The type of SV must
-be >= SVt_PVMG. See C<sv_magic>.
+be >= SVt_PVMG. See C<sv_magic>.
=cut
*/
and I<*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 I<*result>. If the value is > UV_MAX C<grok_bin>
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
The binary number may optionally be prefixed with "0b" or "b" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
number may use '_' characters to separate digits.
and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
+and nothing is written to I<*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,
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
The hex number may optionally be prefixed with "0x" or "x" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
number may use '_' characters to separate digits.
and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
/*
=for apidoc scan_bin
-For backwards compatibility. Use C<grok_bin> instead.
+For backwards compatibility. Use C<grok_bin> instead.
=for apidoc scan_hex
-For backwards compatibility. Use C<grok_hex> instead.
+For backwards compatibility. Use C<grok_hex> instead.
=for apidoc scan_oct
-For backwards compatibility. Use C<grok_oct> instead.
+For backwards compatibility. Use C<grok_oct> instead.
=cut
*/
=head1 Optree Manipulation Functions
=for apidoc Am|OP*|op_linklist|OP *o
-This function is the implementation of the L</LINKLIST> macro. It should
+This function is the implementation of the L</LINKLIST> macro. It should
not be called directly.
=cut
/*
=for apidoc finalize_optree
-This function finalizes the optree. Should be called directly after
-the complete optree is built. It does some additional
+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
the tree thread-safe.
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
+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.
It also flags things that need to behave specially in an lvalue context,
=for apidoc Aox||blockhook_register
Register a set of hooks to be called when the Perl lexical scope changes
-at compile time. See L<perlguts/"Compile-time scope hooks">.
+at compile time.
See L<perlguts/"Compile-time scope hooks">.
=cut
*/
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
-(or 0 for no flags). ver, if specified and not NULL, provides version semantics
+(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()
method, similar to C<use Foo::Bar VERSION LIST>. They must be
=for apidoc cv_const_sv
-If C<cv> is a constant sub eligible for inlining. returns the constant
+If C<cv> is a constant sub eligible for inlining, returns the constant
value returned by the sub. Otherwise, returns NULL.
Constant subs can be created with C<newCONSTSUB> or as described in
=head1 Custom Operators
=for apidoc Ao||custom_op_xop
-Return the XOP structure for a given custom op. This macro should be
+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.
-This macro does call a function. Prior to 5.19.8, this was implemented as a
+This macro does call a function. Prior
+to 5.19.8, this was implemented as a
function.
=cut
/*
=for apidoc Ao||custom_op_register
-Register a custom op. See L<perlguts/"Custom Operators">.
+Register a custom op.
See L<perlguts/"Custom Operators">.
=cut
*/
=for apidoc Amn|U32|GIMME_V
The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
-respectively. See L<perlcall> for a usage example.
+respectively.
See L<perlcall> for a usage example.
=for apidoc Amn|U32|GIMME
A backward-compatible version of C<GIMME_V> which can only return
=for apidoc Am|OP*|LINKLIST|OP *o
Given the root of an optree, link the tree in execution order using the
-C<op_next> pointers and return the first op executed. If this has
+C<op_next> pointers and return the first op executed. If this has
already been done, it will not be redone, and C<< o->op_next >> will be
-returned. If C<< o->op_next >> is not already set, I<o> should be at
+returned. If C<< o->op_next >> is not already set, I<o> should be at
least an C<UNOP>.
=cut
Return the BHK's flags.
=for apidoc mx|void *|BhkENTRY|BHK *hk|which
-Return an entry from the BHK structure. I<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
+Return an entry from the BHK structure. I<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
entry you ask for.
=for apidoc Amx|void|BhkENTRY_set|BHK *hk|which|void *ptr
Set an entry in the BHK structure, and set the flags to indicate it is
-valid. I<which> is a preprocessing token indicating which entry to set.
+valid. I<which> is a preprocessing token indicating which entry to set.
The type of I<ptr> depends on the entry.
=for apidoc Amx|void|BhkDISABLE|BHK *hk|which
Temporarily disable an entry in this BHK structure, by clearing the
-appropriate flag. I<which> is a preprocessor token indicating which
+appropriate flag. I<which> is a preprocessor token indicating which
entry to disable.
=for apidoc Amx|void|BhkENABLE|BHK *hk|which
Re-enable an entry in this BHK structure, by setting the appropriate
-flag. I<which> is a preprocessor token indicating which entry to enable.
+flag. I<which> is a preprocessor token indicating which entry to enable.
This will assert (under -DDEBUGGING) if the entry doesn't contain a valid
pointer.
=for apidoc mx|void|CALL_BLOCK_HOOKS|which|arg
-Call all the registered block hooks for type I<which>. I<which> is a
+Call all the registered block hooks for type I<which>. I<which> is a
preprocessing token; the type of I<arg> depends on I<which>.
=cut
Return the XOP's flags.
=for apidoc Am||XopENTRY|XOP *xop|which
-Return a member of the XOP structure. I<which> is a cpp token indicating
-which entry to return. If the member is not set this will return a
-default value. The return type depends on I<which>. This macro evaluates its
-arguments more than once. If you are using C<Perl_custom_op_xop> to retreive a
+Return a member of the XOP structure. I<which> is a cpp token
+indicating which entry to return. If the member is not set
+this will return a default value. The return type depends
+on I<which>. This macro evaluates its arguments more than
+once. If you are using C<Perl_custom_op_xop> to retreive a
C<XOP *> from a C<OP *>, use the more efficient L</XopENTRYCUSTOM> instead.
=for apidoc Am||XopENTRYCUSTOM|const OP *o|which
Exactly like C<XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)> but more
-efficient. The I<which> parameter is identical to L</XopENTRY>.
+efficient. The I<which> parameter is identical to L</XopENTRY>.
=for apidoc Am|void|XopENTRY_set|XOP *xop|which|value
-Set a member of the XOP structure. I<which> is a cpp token indicating
-which entry to set. See L<perlguts/"Custom Operators"> for details about
-the available members and how they are used. This macro evaluates its argument
+Set a member of the XOP structure. I<which> is a cpp token
+indicating which entry to set. See L<perlguts/"Custom Operators">
+for details about the available members and how
+they are used. This macro evaluates its argument
more than once.
=for apidoc Am|void|XopDISABLE|XOP *xop|which
=head1 Optree Manipulation Functions
=for apidoc Am|const char *|OP_NAME|OP *o
-Return the name of the provided OP. For core ops this looks up the name
+Return the name of the provided OP. For core ops this looks up the name
from the op_type; for custom ops from the op_ppaddr.
=for apidoc Am|const char *|OP_DESC|OP *o
=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
+structures it uses. For core ops this currently gets the information out
of 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
+to the registree to ensure it is accurate. The value returned will be
one of the OA_* constants from op.h.
=for apidoc Am|bool|OP_TYPE_IS|OP *o, Optype type
If PADNAME_OUTER (SvFAKE) is set on the
name SV, then that slot in the frame AV is
-a REFCNT'ed reference to a lexical from "outside". In this case,
+a REFCNT'ed reference to a lexical from "outside". In this case,
the name SV does not use xlow and xhigh to store a cop_seq range, since it is
-in scope throughout. Instead xhigh stores some flags containing info about
+in scope throughout. Instead xhigh stores some flags containing info about
the real lexical (is it declared in an anon, and is it capable of being
instantiated multiple times?), and for fake ANONs, xlow contains the index
within the parent's pad where the lexical's value is stored, to make
=for apidoc cv_undef
-Clear out all the active components of a CV. This can happen either
+Clear out all the active components of a CV. This can happen either
by an explicit C<undef &foo>, or by the reference count going to zero.
In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
children can still follow the full lexical scope chain.
/*
=for apidoc m|PADOFFSET|pad_findlex|const char *namepv|STRLEN namelen|U32 flags|const CV* cv|U32 seq|int warn|SV** out_capture|SV** out_name_sv|int *out_flags
-Find a named lexical anywhere in a chain of nested pads. Add fake entries
+Find a named lexical anywhere in a chain of nested pads. Add fake entries
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_*
+to match against. If warn is true, print appropriate warnings. The 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
+should be stored. out_capture, if non-null, requests that the innermost
instance of the lexical is captured; out_name_sv is set to the innermost
matched namesv or fake namesv; out_flags returns the flags normally
associated with the IVX field of a fake namesv.
Note that 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
+then comes back down, adding fake entries
+as it goes. It has to be this way
because fake namesvs in anon protoypes have to store in xlow the index into
the parent pad.
=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
+old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
moved to a pre-existing CV struct.
=cut
=for apidoc p||get_sv
Returns the SV of the specified Perl scalar. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
+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.
Returns the AV of the specified Perl global or package array with the given
name (so it won't work on lexical variables). C<flags> are passed
-to C<gv_fetchpv>. If C<GV_ADD> is set and the
+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.
=for apidoc p||get_hv
Returns the HV of the specified Perl hash. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
+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.
=for apidoc p||get_cvn_flags
Returns the CV of the specified Perl subroutine. C<flags> are passed to
-C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
+C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
exist then it will be declared (which has the same effect as saying
C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
then NULL is returned.
=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 L<perlcall>.
+with C<argv> (a 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>.
+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>.
=cut
*/
/*
=for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv
Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
+run Perl interpreters. This should be called only once, before creating
any Perl interpreters.
=for apidoc Am|void|PERL_SYS_INIT3|int *argc|char*** argv|char*** env
Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
+run Perl interpreters. This should be called only once, before creating
any Perl interpreters.
=for apidoc Am|void|PERL_SYS_TERM|
Provides system-specific clean up of the C runtime environment after
-running Perl interpreters. This should be called only once, after
+running Perl interpreters. This should be called only once, after
freeing any remaining Perl interpreters.
=cut
/*
=for apidoc Am|void|EXTEND|SP|SSize_t nitems
-Used to extend the argument stack for an XSUB's return values. Once
+Used to extend the argument stack for an XSUB's return values. Once
used, guarantees that there is room for at least C<nitems> to be pushed
onto the stack.
/*
=for apidoc caller_cx
-The XSUB-writer's equivalent of L<caller()|perlfunc/caller>. The
+The XSUB-writer's equivalent of L<caller()|perlfunc/caller>. The
returned C<PERL_CONTEXT> structure can be interrogated to find all the
-information returned to Perl by C<caller>. Note that XSUBs don't get a
+information returned to Perl by C<caller>. Note that XSUBs don't get a
stack frame, so C<caller_cx(0, NULL)> will return information for the
immediately-surrounding Perl code.
This function skips over the automatic calls to C<&DB::sub> made on the
-behalf of the debugger. If the stack frame requested was a sub called by
+behalf of the debugger. If the stack frame requested was a sub called by
C<DB::sub>, the return value will be the frame for the call to
C<DB::sub>, since that has the correct line number/etc. for the call
-site. If I<dbcxp> is non-C<NULL>, it will be set to a pointer to the
+site. If I<dbcxp> is non-C<NULL>, it will be set to a pointer to the
frame for the sub call itself.
=cut
Locate the CV corresponding to the currently executing sub or eval.
If db_seqp is non_null, skip CVs that are in the DB package and populate
*db_seqp with the cop sequence number at the point that the DB:: code was
-entered. (allows debuggers to eval in the scope of the breakpoint rather
-than in the scope of the debugger itself).
+entered. (This allows debuggers to eval in the scope of the breakpoint
+rather than in the scope of the debugger itself.)
=cut
*/
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
-C<SPAGAIN> after the call to this function). It returns the number of
+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
=for apidoc sortsv
-Sort an array. Here is an example:
+Sort an array. Here is an example:
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 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
+typeglob. As 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.
=for apidoc Am|REGEXP *|SvRX|SV *sv
-Convenience macro to get the REGEXP from a SV. This is approximately
+Convenience macro to get the REGEXP from a SV. This is approximately
equivalent to the following snippet:
if (SvMAGICAL(sv))
a typeglob. 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. SVt_REGEXP is for regular
+expressions. SVt_INVLIST is for Perl
core internal use only.
SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression,
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV. I<sv> may be NULL.
+Decrements the reference count of the given SV. I<sv> may be NULL.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
Same as SvREFCNT_dec, but can only be used if you know I<sv>
Unsets the NV/IV status of an SV.
=for apidoc Am|U32|SvOK|SV* sv
-Returns a U32 value indicating whether the value is defined. This is
+Returns a U32 value indicating whether the value is defined. This is
only meaningful for scalars.
=for apidoc Am|U32|SvIOKp|SV* sv
=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
+string. Prior to 5.9.3 it is not safe
+to execute this macro unless the SV's
type >= SVt_PV.
This is also used to store the name of an autoloaded subroutine in an XS
Untaints an SV. Be I<very> careful with this routine, as it short-circuits
some of Perl's fundamental security features. XS module authors should not
use this function unless they fully understand all the implications of
-unconditionally untainting the value. Untainting should be done in the
+unconditionally untainting the value. Untainting should be done in the
standard perl fashion, via a carefully crafted regexp, rather than directly
untainting variables.
going to update the C<SvPVX> directly. Processes get magic.
Note that coercing an arbitrary scalar into a plain PV will potentially
-strip useful data from it. For example if the SV was C<SvROK>, then the
+strip useful data from it. For example if the SV was C<SvROK>, then the
referent will have its reference count decremented, and the SV itself may
be converted to an C<SvPOK> scalar with a string buffer containing a value
such as C<"ARRAY(0x1234)">.
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
+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
be valid (for example, if you intend to write to it), then see
Expands the character buffer in the SV so that it has room for the
indicated number of bytes (remember to reserve space for an extra trailing
NUL character). Calls C<sv_grow> to perform the expansion if necessary.
-Returns a pointer to the character buffer. SV must be of type >= SVt_PV. One
+Returns a pointer to the character
+buffer. SV must be of type >= SVt_PV. One
alternative is to call C<sv_grow> if you are not sure of the type of SV.
=cut
croak_xs_usage(cv, "eee_yow");
works out the package name and subroutine name from C<cv>, and then calls
-C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
+C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
Perl_croak(aTHX_ "Usage: %"SVf"::%"SVf"(%s)", "ouch" "awk", "eee_yow");
=head1 Unicode Support
This file contains various utility functions for manipulating UTF8-encoded
-strings. For the uninitiated, this is a method of representing arbitrary
+strings. For the uninitiated, this is a method of representing arbitrary
Unicode characters as a variable number of bytes, in such a way that
characters in the ASCII range are unmodified, and a zero byte never appears
within non-zero characters.
Adds the UTF-8 representation of the native code point C<uv> to the end
of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free
-bytes available. The return value is the pointer to the byte after the
-end of the new character. In other words,
+bytes available. The return value is the pointer to the byte after the
+end of the new character. In other words,
d = uvchr_to_utf8(d, uv);
Adds the UTF-8 representation of the native code point C<uv> to the end
of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free
-bytes available. The return value is the pointer to the byte after the
-end of the new character. In other words,
+bytes available. The return value is the pointer to the byte after the
+end of the new character. In other words,
d = uvchr_to_utf8_flags(d, uv, flags);
byte containing 0xFE or 0xFF. The 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,
-including these, as malformations.) Similarly, UTF8_WARN_FE_FF acts just like
+including these, as malformations.)
+Similarly, 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
=for apidoc bytes_cmp_utf8
Compares the sequence of characters (stored as octets) in C<b>, C<blen> with the
-sequence of characters (stored as UTF-8) in C<u>, C<ulen>. Returns 0 if they are
+sequence of characters (stored as UTF-8)
+in C<u>, C<ulen>. Returns 0 if they are
equal, -1 or -2 if the first string is less than the second string, +1 or +2
if the first string is greater than the second string.
-1 or +1 is returned if the shorter string was identical to the start of the
-longer string. -2 or +2 is returned if the was a difference between characters
+longer string. -2 or +2 is returned if
+there was a difference between characters
within the strings.
=cut
Unlike L</utf8_to_bytes> but like L</bytes_to_utf8>, returns a pointer to
the newly-created string, and updates C<len> to contain the new
length. Returns the original string if no conversion occurs, C<len>
-is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
+is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
0 if C<s> is converted or consisted entirely of characters that are invariant
in utf8 (i.e., US-ASCII on non-EBCDIC machines).
=for apidoc savepv
-Perl's version of C<strdup()>. Returns a pointer to a newly allocated
-string which is a duplicate of C<pv>. The size of the string is
-determined by C<strlen()>. The memory allocated for the new string can
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
be freed with the C<Safefree()> function.
On some platforms, Windows for example, all allocated memory owned by a thread
/*
=for apidoc savepvn
-Perl's version of what C<strndup()> would be if it existed. Returns a
+Perl's version of what C<strndup()> would be if it existed. Returns a
pointer to a newly allocated string which is a duplicate of the first
-C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
+C<len> bytes from C<pv>, plus a trailing
+NUL byte. The memory allocated for
the new string can be freed with the C<Safefree()> function.
On some platforms, Windows for example, all allocated memory owned by a thread
=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 NULL
pointer is not acceptable)
=cut
=for apidoc Am|void|croak_no_modify
Exactly equivalent to C<Perl_croak(aTHX_ "%s", PL_no_modify)>, but generates
-terser object code than using C<Perl_croak>. Less code used on exception code
+terser object code than using C<Perl_croak>. Less code used on exception code
paths reduces CPU cache pressure.
=cut
=for apidoc sv_nosharing
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.
+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
potentially warn under some level of strict-ness.
=for apidoc my_sprintf
The C library C<sprintf>, wrapped if necessary, to ensure that it will return
-the length of the string written to the buffer. Only rare pre-ANSI systems
+the length of the string written to the buffer. Only rare pre-ANSI systems
need the wrapper function - usually this is a direct call to C<sprintf>.
=cut
https://perl5.git.perl.org / perl5.git / commitdiff