diff options
| -rw-r--r-- | XSUB.h | 10 | ||||
| -rw-r--r-- | av.c | 16 | ||||
| -rw-r--r-- | dump.c | 46 | ||||
| -rw-r--r-- | ext/mro/mro.pm | 2 | ||||
| -rw-r--r-- | ext/mro/mro.xs | 2 | ||||
| -rw-r--r-- | gv.c | 38 | ||||
| -rw-r--r-- | handy.h | 4 | ||||
| -rw-r--r-- | hv.c | 47 | ||||
| -rw-r--r-- | hv.h | 2 | ||||
| -rw-r--r-- | inline.h | 4 | ||||
| -rw-r--r-- | intrpvar.h | 2 | ||||
| -rw-r--r-- | mathoms.c | 28 | ||||
| -rw-r--r-- | mg.c | 26 | ||||
| -rw-r--r-- | mro_core.c | 4 | ||||
| -rw-r--r-- | numeric.c | 102 | ||||
| -rw-r--r-- | op.c | 58 | ||||
| -rw-r--r-- | op.h | 20 | ||||
| -rw-r--r-- | pad.c | 91 | ||||
| -rw-r--r-- | pad.h | 18 | ||||
| -rw-r--r-- | perl.c | 6 | ||||
| -rw-r--r-- | pod/perldiag.pod | 2 | ||||
| -rw-r--r-- | pp_ctl.c | 4 | ||||
| -rw-r--r-- | pp_pack.c | 16 | ||||
| -rw-r--r-- | pp_sort.c | 2 | ||||
| -rw-r--r-- | pp_sys.c | 6 | ||||
| -rw-r--r-- | regexp.h | 2 | ||||
| -rw-r--r-- | sv.c | 240 | ||||
| -rw-r--r-- | sv.h | 182 | ||||
| -rw-r--r-- | utf8.c | 78 | ||||
| -rw-r--r-- | util.c | 51 |
30 files changed, 557 insertions, 552 deletions
@@ -49,7 +49,7 @@ Used to access elements on the XSUB's stack. =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. @@ -72,7 +72,7 @@ Sets up the C<items> variable. 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>. @@ -86,8 +86,8 @@ 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 -is a lexical $_ in scope. +The SV* corresponding to the C<$_> variable. Works even if there +is a lexical C<$_> in scope. =cut */ @@ -286,7 +286,7 @@ handled automatically by C<ExtUtils::MakeMaker>. See 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">. @@ -288,7 +288,7 @@ Perl_av_fetch(pTHX_ AV *av, SSize_t key, I32 lval) =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 @@ -296,7 +296,7 @@ there (= C<val>)). 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;>. @@ -383,7 +383,7 @@ Perl_av_store(pTHX_ AV *av, SSize_t key, SV *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...);> @@ -432,9 +432,9 @@ Perl_av_make(pTHX_ SSize_t size, SV **strp) /* =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 = ();>. @@ -497,7 +497,7 @@ Perl_av_clear(pTHX_ AV *av) =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 @@ -783,7 +783,7 @@ Set the highest index in the array to the given number, equivalent to 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)>. @@ -912,7 +912,7 @@ Perl_av_delete(pTHX_ AV *av, SSize_t key, I32 flags) 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])>. @@ -94,43 +94,43 @@ S_append_flags(pTHX_ SV *sv, U32 flags, const struct flag_to_name *start, /* =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 */ @@ -249,23 +249,23 @@ Perl_pv_escape( pTHX_ SV *dsv, char const * const str, =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 */ diff --git a/ext/mro/mro.pm b/ext/mro/mro.pm index 093d080c47..0946fb6722 100644 --- a/ext/mro/mro.pm +++ b/ext/mro/mro.pm @@ -12,7 +12,7 @@ use warnings; # 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]; diff --git a/ext/mro/mro.xs b/ext/mro/mro.xs index 987bafb2cf..6d891ae731 100644 --- a/ext/mro/mro.xs +++ b/ext/mro/mro.xs @@ -13,7 +13,7 @@ static const struct mro_alg c3_alg = /* =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). @@ -142,7 +142,7 @@ Perl_gv_fetchfile_flags(pTHX_ const char *const name, const STRLEN namelen, 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 */ @@ -304,8 +304,8 @@ Perl_cvstash_set(pTHX_ CV *cv, HV *st) 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. @@ -318,25 +318,25 @@ stash element, it is the caller's responsibility to ensure that the name 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 @@ -669,16 +669,16 @@ Perl_gv_fetchmeth_pv(pTHX_ HV *stash, const char *name, I32 level, U32 flags) 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 @@ -909,14 +909,14 @@ Perl_gv_fetchmeth_pv_autoload(pTHX_ HV *stash, const char *name, I32 level, U32 /* =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 */ @@ -958,7 +958,7 @@ Perl_gv_fetchmeth_pvn_autoload(pTHX_ HV *stash, const char *name, STRLEN len, I3 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 @@ -971,7 +971,7 @@ These functions grant C<"SUPER"> token 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 @@ -1364,7 +1364,7 @@ Returns a pointer to the stash for a specified package. The C<namelen> parameter indicates the length of the C<name>, in bytes. C<flags> is passed to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be created if it does not already exist. If the package does not exist and -C<flags> is 0 (or any other setting that does not create packages) then NULL +C<flags> is 0 (or any other setting that does not create packages) then C<NULL> is returned. Flags may be one of: @@ -1376,7 +1376,7 @@ 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. @@ -1844,7 +1844,7 @@ source, C<dest> is the destination, C<nitems> is the number of items, and 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. @@ -1855,7 +1855,7 @@ C<type> is the type. May fail on overlapping copies. See also C<L</Move>>. =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. @@ -222,19 +222,19 @@ C<hash> parameter is the precomputed hash value; if it is zero then 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. @@ -244,22 +244,22 @@ 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. @@ -973,15 +973,15 @@ Deletes a key/value pair in the hash. The value's SV is removed from 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 @@ -1664,11 +1664,12 @@ Perl_hv_clear(pTHX_ HV *hv) 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 */ @@ -1830,7 +1831,7 @@ Perl_hfree_next_entry(pTHX_ HV *hv, STRLEN *indexp) 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 @@ -2480,7 +2481,7 @@ trigger the resource deallocation. 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 @@ -152,7 +152,7 @@ Null HV pointer. =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 @@ -287,11 +287,11 @@ S__is_utf8_char_slow(const U8 *s, const U8 *e) =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 */ diff --git a/intrpvar.h b/intrpvar.h index f6b68d9f1c..9d51290cf4 100644 --- a/intrpvar.h +++ b/intrpvar.h @@ -84,7 +84,7 @@ PERLVAR(I, defgv, GV *) /* the *_ glob */ =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 */ @@ -258,7 +258,7 @@ Perl_sv_2pvutf8_nolen(pTHX_ SV *sv) 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 */ @@ -739,10 +739,10 @@ Perl_is_utf8_string_loc(pTHX_ const U8 *s, STRLEN len, const U8 **ep) =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 */ @@ -759,10 +759,10 @@ Perl_sv_nolocking(pTHX_ SV *sv) =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 */ @@ -862,9 +862,9 @@ Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len) /* =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 */ @@ -885,9 +885,9 @@ Perl_unpack_str(pTHX_ const char *pat, const char *patend, const char *s, /* =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 */ @@ -1145,13 +1145,13 @@ Perl_sv_2bool(pTHX_ SV *const sv) /* =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 @@ -1743,7 +1743,7 @@ is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead. 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. @@ -160,7 +160,7 @@ Perl_mg_magical(SV *sv) =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 */ @@ -285,10 +285,10 @@ Perl_mg_set(pTHX_ SV *sv) =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 */ @@ -403,7 +403,7 @@ S_mg_findext_flags(const SV *sv, int type, const MGVTBL *vtbl, U32 flags) /* =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 */ @@ -486,12 +486,12 @@ Perl_mg_copy(pTHX_ SV *sv, SV *nsv, const char *key, I32 klen) =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 @@ -1782,7 +1782,7 @@ The C<flags> can be: 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 @@ -3451,7 +3451,7 @@ S_unwind_handler_stack(pTHX_ const void *p) /* =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. @@ -3483,7 +3483,7 @@ Perl_magic_sethint(pTHX_ SV *sv, MAGIC *mg) /* =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 @@ -3507,7 +3507,7 @@ Perl_magic_clearhint(pTHX_ SV *sv, MAGIC *mg) /* =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 */ diff --git a/mro_core.c b/mro_core.c index d134b8acdc..c1e2da7cf1 100644 --- a/mro_core.c +++ b/mro_core.c @@ -199,7 +199,7 @@ Perl_mro_meta_dup(pTHX_ struct mro_meta* smeta, CLONE_PARAMS* param) /* =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). @@ -461,7 +461,7 @@ Perl_mro_get_linear_isa(pTHX_ HV *stash) =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 @@ -108,7 +108,7 @@ Perl_cast_uv(NV f) 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. @@ -116,15 +116,15 @@ On return C<*len> is set to the length of the scanned string, 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 @@ -231,23 +231,23 @@ Perl_grok_bin(pTHX_ const char *start, STRLEN *len_p, I32 *flags, NV *result) 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 @@ -352,21 +352,21 @@ Perl_grok_hex(pTHX_ const char *start, STRLEN *len_p, I32 *flags, NV *result) 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 @@ -551,7 +551,7 @@ Perl_grok_numeric_radix(pTHX_ const char **sp, const char *send) /* =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 @@ -560,11 +560,11 @@ or "not a number", and returns one of the following flag combinations: 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 */ @@ -807,20 +807,20 @@ Perl_grok_infnan(pTHX_ const char** sp, const char* send) 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 @@ -829,7 +829,7 @@ C<IS_NUMBER_TRAILING> on the result. =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 */ @@ -1525,9 +1525,9 @@ Perl_my_atof2(pTHX_ const char* orig, NV* value) /* =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(). @@ -1550,9 +1550,9 @@ Perl_isinfnan(NV nv) /* =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 */ @@ -1610,19 +1610,19 @@ Perl_my_frexpl(long double x, int *e) { 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 */ @@ -1211,7 +1211,7 @@ Perl_op_refcnt_unlock(pTHX) =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 @@ -1222,22 +1222,22 @@ Note that op_next is not manipulated, and nodes are not freed; that is 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: @@ -1362,7 +1362,7 @@ Perl_op_sibling_splice(OP *parent, OP *start, int del_count, OP* insert) /* =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 @@ -2365,7 +2365,7 @@ S_check_hash_fields_and_hekify(pTHX_ UNOP *rop, SVOP *key_op) 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 @@ -2585,13 +2585,13 @@ S_finalize_op(pTHX_ OP* o) 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>. @@ -4673,7 +4673,7 @@ consumed by this function and become part of the constructed op tree. 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. @@ -4816,8 +4816,8 @@ Perl_newUNOP(pTHX_ I32 type, I32 flags, OP *first) /* =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 */ @@ -4857,7 +4857,7 @@ and, shifted up eight bits, the eight bits of C<op_private>, except that 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 */ @@ -4912,7 +4912,7 @@ method name. C<type> is the opcode. C<flags> gives the eight bits of 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 */ @@ -6105,15 +6105,15 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg) 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. @@ -7597,7 +7597,7 @@ C<cond> supplies the expression that will be locally assigned to a lexical 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 */ @@ -7733,7 +7733,7 @@ static void const_av_xsub(pTHX_ CV* cv); =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">. @@ -8803,12 +8803,12 @@ Perl_newCONSTSUB(pTHX_ HV *stash, const char *name, SV *sv) 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.) @@ -14342,7 +14342,7 @@ Perl_peep(pTHX_ OP *o) =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. @@ -14479,8 +14479,8 @@ Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr, const XOP *xop) =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 @@ -714,7 +714,7 @@ Return the BHK's flags. =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 @@ -912,13 +912,13 @@ Return a short description of the provided OP. =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 @@ -933,28 +933,28 @@ replaced by an OP of type OP_NULL. 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 */ @@ -38,10 +38,10 @@ not callable at will and are always thrown away after the eval"" is done 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. @@ -55,26 +55,27 @@ array, so don't rely on it. See L</PadlistNAMES>. 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: @@ -88,13 +89,13 @@ 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 @@ -104,20 +105,20 @@ instantiated multiple times?), and for fake ANONs, 'low' contains the index 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 @@ -288,7 +289,7 @@ Perl_pad_new(pTHX_ int flags) 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 @@ -488,10 +489,10 @@ Perl_cv_undef_flags(pTHX_ CV *cv, U32 flags) /* =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 @@ -853,11 +854,11 @@ Perl_pad_add_weakref(pTHX_ CV* func) 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 */ @@ -1103,18 +1104,18 @@ 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_* +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 @@ -1383,7 +1384,7 @@ S_pad_findlex(pTHX_ const char *namepv, STRLEN namelen, U32 flags, const CV* cv, =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 */ @@ -1406,7 +1407,7 @@ Perl_pad_sv(pTHX_ PADOFFSET po) =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 */ @@ -1578,7 +1579,7 @@ Perl_pad_leavemy(pTHX) /* =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 @@ -1667,7 +1668,7 @@ S_pad_reset(pTHX) 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 @@ -2333,7 +2334,7 @@ An SV may be passed as a second argument. If so, the name will be assigned 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). @@ -2373,8 +2374,8 @@ Perl_cv_name(pTHX_ CV *cv, SV *sv, U32 flags) /* =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 @@ -2445,7 +2446,7 @@ Perl_pad_fixup_inner_anons(pTHX_ PADLIST *padlist, CV *old_cv, CV *new_cv) 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 */ @@ -2815,7 +2816,7 @@ Perl_newPADNAMEpvn(const char *s, STRLEN len) 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 */ @@ -179,10 +179,10 @@ Save a pad slot (used to restore after an iteration) 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 @@ -191,7 +191,7 @@ numbers >= 1, as the 0th entry is not guaranteed to remain usable. =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 @@ -225,7 +225,7 @@ The C array of pad entries. 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 @@ -251,7 +251,7 @@ are often referred to as 'fake'. 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 @@ -292,11 +292,11 @@ like PAD_SET_CUR, but without the save 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 */ @@ -412,7 +412,7 @@ Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() 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 @@ -2515,7 +2515,7 @@ Perl_get_av(pTHX_ const char *name, I32 flags) 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 */ @@ -2589,7 +2589,7 @@ Perl_get_cv(pTHX_ const char *name, I32 flags) =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)>. @@ -2820,7 +2820,7 @@ Perl_call_sv(pTHX_ SV *sv, VOL I32 flags) =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 */ diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 918d35c7a9..7ca4cf9145 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -6501,7 +6501,7 @@ discovered. See L<perlre>. =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. @@ -3161,8 +3161,8 @@ S_docatch(pTHX_ OP *o) =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.) @@ -791,20 +791,20 @@ first_symbol(const char *pat, const char *patend) { =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 */ @@ -1948,7 +1948,7 @@ S_div128(pTHX_ SV *pnum, bool *done) /* =for apidoc packlist -The engine implementing pack() Perl function. +The engine implementing C<pack()> Perl function. =cut */ @@ -1432,7 +1432,7 @@ 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 C<L</sortsv_flags>> for a more flexible routine. =cut @@ -1265,10 +1265,10 @@ PP(pp_sselect) =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 */ @@ -242,7 +242,7 @@ equivalent to the following snippet: 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 @@ -1925,7 +1925,7 @@ S_not_incrementable(pTHX_ SV *const 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 @@ -2420,7 +2420,7 @@ S_sv_2iuv_common(pTHX_ SV *const sv) =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 @@ -2516,7 +2516,7 @@ Perl_sv_2iv_flags(pTHX_ SV *const sv, const I32 flags) =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 @@ -2599,7 +2599,7 @@ Perl_sv_2uv_flags(pTHX_ SV *const sv, const I32 flags) =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 @@ -2924,8 +2924,8 @@ S_infnan_2pv(NV nv, char* buffer, size_t maxlen, char plus) { /* =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. @@ -3222,21 +3222,21 @@ Perl_sv_2pv_flags(pTHX_ SV *const sv, STRLEN *const lp, const I32 flags) =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 */ @@ -3260,7 +3260,7 @@ Perl_sv_copypv_flags(pTHX_ SV *const dsv, SV *const ssv, const I32 flags) /* =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. @@ -3288,7 +3288,7 @@ Perl_sv_2pvbyte(pTHX_ SV *sv, STRLEN *const lp) /* =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. @@ -3314,15 +3314,15 @@ Perl_sv_2pvutf8(pTHX_ SV *sv, STRLEN *const lp) /* =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 @@ -3380,7 +3380,7 @@ Perl_sv_2bool_flags(pTHX_ SV *sv, I32 flags) 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 @@ -3389,7 +3389,7 @@ use the Encode extension for that. =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 @@ -3400,7 +3400,7 @@ if all the bytes are invariant in UTF-8. 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 @@ -3413,8 +3413,8 @@ use the Encode extension for that. =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. @@ -3696,7 +3696,7 @@ in this case, either returns false or, if C<fail_ok> is not 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 */ @@ -3856,7 +3856,7 @@ content of the destination. If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on C<ssv> if appropriate, else not. 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 @@ -4972,19 +4972,20 @@ Perl_sv_sethek(pTHX_ SV *const sv, const HEK *const hek) 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>). @@ -5058,11 +5059,11 @@ Perl_sv_usepvn_flags(pTHX_ SV *const sv, char *ptr, const STRLEN len, const U32 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 @@ -5222,10 +5223,10 @@ Perl_sv_force_normal_flags(pTHX_ SV *const sv, const U32 flags) =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. @@ -5325,7 +5326,7 @@ Perl_sv_chop(pTHX_ SV *const sv, const char *const ptr) /* =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>>. @@ -5505,12 +5506,12 @@ Perl_sv_catpv_mg(pTHX_ SV *const sv, const char *const ptr) 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. @@ -5532,16 +5533,16 @@ Perl_newSV(pTHX_ const STRLEN len) =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>.) @@ -5642,8 +5643,8 @@ magic list. 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 */ @@ -5827,16 +5828,16 @@ Perl_sv_rvweaken(pTHX_ SV *const sv) /* =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 */ @@ -6161,7 +6162,7 @@ Perl_sv_kill_backrefs(pTHX_ SV *const sv, AV *const av) =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 @@ -6357,7 +6358,7 @@ Clear an SV: call any destructors, free up any memory used by the body, 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. @@ -6930,7 +6931,7 @@ Perl_sv_free2(pTHX_ SV *const sv, const U32 rc) 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 */ @@ -7196,8 +7197,8 @@ S_sv_pos_u2b_cached(pTHX_ SV *const sv, MAGIC **const mgp, const U8 *const start 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. @@ -7251,9 +7252,9 @@ Perl_sv_pos_u2b_flags(pTHX_ SV *const sv, STRLEN uoffset, STRLEN *const lenp, /* =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. @@ -7474,7 +7475,7 @@ S_sv_pos_b2u_midway(pTHX_ const U8 *const s, const U8 *const target, /* =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. @@ -7578,7 +7579,7 @@ Perl_sv_pos_b2u_flags(pTHX_ SV *const sv, STRLEN const offset, U32 flags) /* =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. @@ -7629,14 +7630,14 @@ S_assert_uft8_cache_coherent(pTHX_ const char *const func, STRLEN from_cache, =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 */ @@ -7721,15 +7722,15 @@ Perl_sv_eq_flags(pTHX_ SV *sv1, SV *sv2, const U32 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, 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 @@ -7965,14 +7966,15 @@ Perl_sv_cmp_flags(pTHX_ SV *const sv1, SV *const sv2, =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 */ @@ -8046,9 +8048,9 @@ C<L</sv_collxfrm_flags>>. =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. @@ -9002,7 +9004,7 @@ Perl_sv_dec_nomg(pTHX_ SV *const sv) 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 @@ -9032,7 +9034,7 @@ Perl_sv_mortalcopy_flags(pTHX_ SV *const oldstr, U32 flags) 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 @@ -9103,8 +9105,8 @@ Perl_newSVpvn_flags(pTHX_ const char *const s, const STRLEN len, const U32 flags =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>>. @@ -9130,7 +9132,7 @@ Perl_sv_2mortal(pTHX_ SV *const sv) 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. @@ -9175,7 +9177,7 @@ Perl_newSVpvn(pTHX_ const char *const buffer, const STRLEN len) 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 */ @@ -9238,15 +9240,15 @@ Perl_newSVhek(pTHX_ const HEK *const hek) /* =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 */ @@ -9645,8 +9647,8 @@ Using various gambits, try to get an IO from an SV: the IO slot if its a 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 */ @@ -9704,7 +9706,7 @@ Perl_sv_2io(pTHX_ SV *const sv) 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 */ @@ -10129,7 +10131,7 @@ Perl_newSVavdefelem(pTHX_ AV *av, SSize_t ix, bool extendible) 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. @@ -10627,8 +10629,8 @@ Processes its arguments like C<sv_catpvfn>, and appends the formatted 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. @@ -10806,7 +10808,7 @@ S_F0convert(NV nv, char *const endbuf, STRLEN *const len) 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. @@ -14355,28 +14357,28 @@ do_mark_cloneable_stash(pTHX_ SV *const sv) 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, @@ -15277,16 +15279,16 @@ Perl_init_constants(pTHX) =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 */ @@ -15354,13 +15356,13 @@ Perl_sv_recode_to_utf8(pTHX_ SV *sv, SV *encoding) /* =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. @@ -15546,19 +15548,19 @@ Perl_varname(pTHX_ const GV *const gv, const char gvtype, PADOFFSET targ, 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 */ @@ -41,8 +41,8 @@ The types are: 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 @@ -51,25 +51,25 @@ types in the Perl language. 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 @@ -274,49 +274,49 @@ Returns the value of the object's reference count. =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 @@ -691,20 +691,20 @@ Tells an SV that it is an integer. 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. @@ -732,7 +732,7 @@ Tells an SV that it is a string. 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 @@ -741,9 +741,9 @@ Returns a boolean indicating whether the SV contains a v-string. =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 @@ -760,21 +760,21 @@ Dereferences an RV to return the 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>. @@ -790,7 +790,7 @@ attributable to C<SvOOK>. See C<L</SvCUR>>. 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. @@ -805,7 +805,7 @@ With future Perls, however, it will be more efficient to use 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 @@ -817,21 +817,21 @@ C<NUL>-terminated string C<val>. See also C<L</SvIV_set>>. 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>> @@ -901,7 +901,7 @@ Set the actual length of the string which is in the SV. See C<L</SvIV_set>>. =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>> @@ -916,7 +916,7 @@ Unsets the UTF-8 status of an SV (the data is not changed, just the flag). 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 @@ -1044,14 +1044,14 @@ the scalar's value cannot change unless written to. /* =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 @@ -1059,8 +1059,8 @@ 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 */ @@ -1500,14 +1500,14 @@ the SV if the SV does not contain a string. The SV may cache the 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>>. @@ -1527,7 +1527,7 @@ Like C<SvPV_nolen> but doesn't process magic. =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. @@ -1540,7 +1540,7 @@ otherwise use the more efficient C<SvIV>. =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. @@ -1553,7 +1553,7 @@ otherwise use the more efficient C<SvNV>. =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. @@ -1566,50 +1566,50 @@ otherwise use the more efficient C<SvUV>. =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 @@ -1635,7 +1635,7 @@ Like C<sv_catsv> but doesn't process magic. =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 */ @@ -1970,7 +1970,7 @@ incremented. #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 @@ -1987,12 +1987,12 @@ or a tied variable (it calls C<STORE>). This macro evaluates its 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. @@ -2001,15 +2001,15 @@ 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 @@ -2019,7 +2019,7 @@ 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 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 @@ -2137,7 +2137,7 @@ struct clone_params { =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 @@ -2158,7 +2158,7 @@ Creates a new SV containing the pad name. /* =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>. @@ -287,23 +287,23 @@ This function will convert to UTF-8 (and not warn) even code points that aren't 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 */ @@ -430,13 +430,13 @@ overlong sequences, the computed code point is returned; for all other allowed 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. @@ -445,18 +445,18 @@ Certain code points are considered problematic. These are Unicode surrogates, 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 @@ -467,11 +467,11 @@ imposed later). (The smaller ones, those that fit into 32 bits, are 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 @@ -831,9 +831,9 @@ C<*retlen> will be set to the length, in bytes, of that character. 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. @@ -1765,7 +1765,7 @@ of the result. 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 @@ -1773,8 +1773,8 @@ any special mappings; C<""> means to use the special mappings. Values other 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 */ @@ -3876,14 +3876,14 @@ Perl_check_utf8_print(pTHX_ const U8* s, const STRLEN len) 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. @@ -3994,7 +3994,7 @@ scan will not be considered to be a match unless the goal is reached, and 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; @@ -4011,7 +4011,7 @@ reached for a successful match. Also, if the fold of a character is multiple 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>. @@ -630,7 +630,7 @@ Perl_rninstr(const char *big, const char *bigend, const char *little, const char =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 @@ -732,7 +732,7 @@ Perl_fbm_compile(pTHX_ SV *sv, U32 flags) 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 @@ -929,7 +929,8 @@ Perl_fbm_instr(pTHX_ unsigned char *big, unsigned char *bigend, SV *littlestr, U /* =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. @@ -982,8 +983,8 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len) /* =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 */ @@ -1110,7 +1111,7 @@ Perl_savesharedpv(pTHX_ const char *pv) =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 @@ -3947,7 +3948,7 @@ return FALSE =for apidoc getcwd_sv -Fill the sv with current working directory +Fill C<sv> with current working directory =cut */ @@ -4378,7 +4379,7 @@ Perl_my_socketpair (int family, int type, int protocol, int fd[2]) { 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 @@ -4397,7 +4398,7 @@ Perl_sv_nosharing(pTHX_ SV *sv) 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 @@ -4946,18 +4947,18 @@ Perl_my_sprintf(char *buffer, const char* pat, ...) /* =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.> @@ -4995,18 +4996,18 @@ Perl_quadmath_format_single(const char* format) /* =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. @@ -6129,10 +6130,10 @@ static void atos_symbolize(atos_context* ctx, =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 */ @@ -6378,8 +6379,8 @@ Deallocates a backtrace received from get_c_bracktrace. /* =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: @@ -6390,10 +6391,10 @@ 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). @@ -6461,7 +6462,7 @@ Perl_get_c_backtrace_dump(pTHX_ int depth, int skip) /* =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. |