Fix a perldelta typo

[perl5.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 9e70c69..afff655 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -293,7 +293,7 @@ or less equivalent:
           ST(0) = newSVpv("Hello World",0);
           sv_2mortal(ST(0));
           XSRETURN(1);
-  
+
   SV *
   beta()
       CODE:
@@ -319,7 +319,7 @@ CPAN modules) in the typemap file, the reference count of the C<AV *>
 is not properly decremented. Thus, the above XSUB would leak memory
 whenever it is being called. The same problem exists for C<HV *>.
 
-When you're returning an C<AV *> or a C<HV *>, you have make sure
+When you're returning an C<AV *> or a C<HV *>, you have to make sure
 their reference count is decremented by making the AV or HV mortal:
 
   AV *
@@ -950,10 +950,9 @@ The XS code, with ellipsis, follows.
           time_t timep = NO_INIT
        PREINIT:
           char *host = "localhost";
-         STRLEN n_a;
         CODE:
          if( items > 1 )
-              host = (char *)SvPV(ST(1), n_a);
+              host = (char *)SvPV_nolen(ST(1));
          RETVAL = rpcb_gettime( host, &timep );
         OUTPUT:
           timep
@@ -1212,6 +1211,12 @@ To disable version checking:
 
     VERSIONCHECK: DISABLE
 
+Note that if the version of the PM module is an NV (a floating point
+number), it will be stringified with a possible loss of precision
+(currently chopping to nine decimal places) so that it may not match
+the version of the XS module anymore. Quoting the $VERSION declaration
+to make it a string is recommended if long version numbers are used.
+
 =head2 The PROTOTYPES: Keyword
 
 The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
@@ -1242,10 +1247,9 @@ prototypes.
        PROTOTYPE: $;$
        PREINIT:
           char *host = "localhost";
-         STRLEN n_a;
         CODE:
                  if( items > 1 )
-                      host = (char *)SvPV(ST(1), n_a);
+                      host = (char *)SvPV_nolen(ST(1));
                  RETVAL = rpcb_gettime( host, &timep );
         OUTPUT:
           timep
@@ -1430,10 +1434,26 @@ The XS module can use INCLUDE: to pull that file into it.
     INCLUDE: Rpcb1.xsh
 
 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
-the compiler will interpret the parameters as a command.
+the compiler will interpret the parameters as a command. This feature is
+mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
+below.
 
     INCLUDE: cat Rpcb1.xsh |
 
+Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
+happens to be the first in your path and not necessarily the same perl that is
+used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
+
+=head2 The INCLUDE_COMMAND: Keyword
+
+Runs the supplied command and includes its output into the current XS
+document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
+in that it runs the same perl interpreter that is running C<xsubpp>:
+
+    INCLUDE_COMMAND: cat Rpcb1.xsh
+
+    INCLUDE_COMMAND: $^X -e ...
+
 =head2 The CASE: Keyword
 
 The CASE: keyword allows an XSUB to have multiple distinct parts with each
@@ -1941,7 +1961,7 @@ and the module version number.
 
 =item typedef my_cxt_t
 
-This struct typedef I<must> always be called C<my_cxt_t> -- the other
+This struct typedef I<must> always be called C<my_cxt_t>. The other
 C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
 
 Declare a typedef named C<my_cxt_t> that is a structure that contains
@@ -1960,7 +1980,7 @@ of C<my_cxt_t>.
 
 The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
 
-It I<must> be called exactly once -- typically in a BOOT: section. If you
+It I<must> be called exactly once, typically in a BOOT: section. If you
 are maintaining multiple interpreters, it should be called once in each
 interpreter instance, except for interpreters cloned from existing ones.
 (But see C<MY_CXT_CLONE> below.)