X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlguts.pod;h=99c79d0a437e473e2efeaac4ce8dc1b723d74988;hb=4e9dada01dea61250de18f52c49ec01866133705;hp=3d1e5d82d0ea194ba04deb3da13e573d766a59da;hpb=1e54db1a8aea187ba2e790aca2ab81fab24ff92d;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 3d1e5d8..99c79d0 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -201,9 +201,22 @@ you can call:
     SvOK(SV*)
 
 The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.
-Its address can be used whenever an C<SV*> is needed.
-However, you have to be careful when using C<&PL_sv_undef> as a value in AVs
-or HVs (see L<AVs, HVs and undefined values>).
+
+Its address can be used whenever an C<SV*> is needed. Make sure that
+you don't try to compare a random sv with C<&PL_sv_undef>. For example
+when interfacing Perl code, it'll work correctly for:
+
+  foo(undef);
+
+But won't work when called as:
+
+  $x = undef;
+  foo($x);
+
+So to repeat always use SvOK() to check whether an sv is defined.
+
+Also you have to be careful when using C<&PL_sv_undef> as a value in
+AVs or HVs (see L<AVs, HVs and undefined values>).
 
 There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
 boolean TRUE and FALSE values, respectively.  Like C<PL_sv_undef>, their
@@ -1328,7 +1341,8 @@ Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
 
 Duplicates the current value of C<SV>, on the exit from the current
 C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
-using the stored value.
+using the stored value. It doesn't handle magic. Use C<save_scalar> if
+magic is affected.
 
 =item C<void save_list(SV **sarg, I32 maxsarg)>
 
@@ -1380,11 +1394,12 @@ and C<num> is the number of elements the stack should be extended by.
 
 Now that there is room on the stack, values can be pushed on it using C<PUSHs>
 macro. The pushed values will often need to be "mortal" (See
-L</Reference Counts and Mortality>).
+L</Reference Counts and Mortality>):
 
     PUSHs(sv_2mortal(newSViv(an_integer)))
+    PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
+    PUSHs(sv_2mortal(newSVnv(a_double)))
     PUSHs(sv_2mortal(newSVpv("Some String",0)))
-    PUSHs(sv_2mortal(newSVnv(3.141592)))
 
 And now the Perl program calling C<tzname>, the two values will be assigned
 as in:
@@ -1400,8 +1415,9 @@ This macro automatically adjust the stack for you, if needed.  Thus, you
 do not need to call C<EXTEND> to extend the stack.
 
 Despite their suggestions in earlier versions of this document the macros
-C<PUSHi>, C<PUSHn> and C<PUSHp> are I<not> suited to XSUBs which return
-multiple results, see L</Putting a C value on Perl stack>.
+C<(X)PUSH[iunp]> are I<not> suited to XSUBs which return multiple results.
+For that, either stick to the C<(X)PUSHs> macros shown above, or use the new
+C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.
 
 For more information, consult L<perlxs> and L<perlxstut>.
 
@@ -1535,7 +1551,7 @@ corresponding parts of its I<target> and puts the I<target> on stack.
 
 The macro to put this target on stack is C<PUSHTARG>, and it is
 directly used in some opcodes, as well as indirectly in zillions of
-others, which use it via C<(X)PUSH[pni]>.
+others, which use it via C<(X)PUSH[iunp]>.
 
 Because the target is reused, you must be careful when pushing multiple
 values on the stack. The following code will not do what you think:
@@ -1547,12 +1563,30 @@ This translates as "set C<TARG> to 10, push a pointer to C<TARG> onto
 the stack; set C<TARG> to 20, push a pointer to C<TARG> onto the stack".
 At the end of the operation, the stack does not contain the values 10
 and 20, but actually contains two pointers to C<TARG>, which we have set
-to 20. If you need to push multiple different values, use C<XPUSHs>,
-which bypasses C<TARG>.
+to 20.
+
+If you need to push multiple different values then you should either use
+the C<(X)PUSHs> macros, or else use the new C<m(X)PUSH[iunp]> macros,
+none of which make use of C<TARG>.  The C<(X)PUSHs> macros simply push an
+SV* on the stack, which, as noted under L</XSUBs and the Argument Stack>,
+will often need to be "mortal".  The new C<m(X)PUSH[iunp]> macros make
+this a little easier to achieve by creating a new mortal for you (via
+C<(X)PUSHmortal>), pushing that onto the stack (extending it if necessary
+in the case of the C<mXPUSH[iunp]> macros), and then setting its value.
+Thus, instead of writing this to "fix" the example above:
+
+    XPUSHs(sv_2mortal(newSViv(10)))
+    XPUSHs(sv_2mortal(newSViv(20)))
+
+you can simply write:
+
+    mXPUSHi(10)
+    mXPUSHi(20)
 
-On a related note, if you do use C<(X)PUSH[npi]>, then you're going to
+On a related note, if you do use C<(X)PUSH[iunp]>, then you're going to
 need a C<dTARG> in your variable declarations so that the C<*PUSH*>
-macros can make use of the local variable C<TARG>.
+macros can make use of the local variable C<TARG>.  See also C<dTARGET>
+and C<dXSTARG>.
 
 =head2 Scratchpads
 
@@ -1762,10 +1796,10 @@ are subject to the same restrictions as in the pass 2.
 =head2 Pluggable runops
 
 The compile tree is executed in a runops function.  There are two runops
-functions in F<run.c>.  C<Perl_runops_debug> is used with DEBUGGING and
-C<Perl_runops_standard> is used otherwise.  For fine control over the
-execution of the compile tree it is possible to provide your own runops
-function.
+functions, in F<run.c> and in F<dump.c>.  C<Perl_runops_debug> is used
+with DEBUGGING and C<Perl_runops_standard> is used otherwise.  For fine
+control over the execution of the compile tree it is possible to provide
+your own runops function.
 
 It's probably best to copy one of the existing runops functions and
 change it to suit your needs.  Then, in the BOOT section of your XS
@@ -2085,11 +2119,12 @@ static functions start with C<S_>.)
 Inside the Perl core, you can get at the functions either with or
 without the C<Perl_> prefix, thanks to a bunch of defines that live in
 F<embed.h>. This header file is generated automatically from
-F<embed.pl>. F<embed.pl> also creates the prototyping header files for
-the internal functions, generates the documentation and a lot of other
-bits and pieces. It's important that when you add a new function to the
-core or change an existing one, you change the data in the table at the
-end of F<embed.pl> as well. Here's a sample entry from that table:
+F<embed.pl> and F<embed.fnc>. F<embed.pl> also creates the prototyping
+header files for the internal functions, generates the documentation
+and a lot of other bits and pieces. It's important that when you add
+a new function to the core or change an existing one, you change the
+data in the table in F<embed.fnc> as well. Here's a sample entry from
+that table:
 
     Apd |SV**   |av_fetch   |AV* ar|I32 key|I32 lval
 
@@ -2148,19 +2183,32 @@ or disappear without notice.
 This function should not have a compatibility macro to define, say,
 C<Perl_parse> to C<parse>. It must be called as C<Perl_parse>.
 
-=item j
-
-This function is not a member of C<CPerlObj>. If you don't know
-what this means, don't use it.
-
 =item x
 
 This function isn't exported out of the Perl core.
 
+=item m
+
+This is implemented as a macro.
+
+=item X
+
+This function is explicitly exported.
+
+=item E
+
+This function is visible to extensions included in the Perl core.
+
+=item b
+
+Binary backward compatibility; this function is a macro but also has
+a C<Perl_> implementation (which is exported).
+
 =back
 
-If you edit F<embed.pl>, you will need to run C<make regen_headers> to
-force a rebuild of F<embed.h> and other auto-generated files.
+If you edit F<embed.pl> or F<embed.fnc>, you will need to run
+C<make regen_headers> to force a rebuild of F<embed.h> and other
+auto-generated files.
 
 =head2 Formatted Printing of IVs, UVs, and NVs