[win32] the EXTCONST in sdbm.h breaks SDBM on Borland, since

[p5sagit/p5-mst-13.2.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 7338bb0..d065b94 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -172,7 +172,7 @@ explicitly.
 
 If PPCODE: directive is not used, C<void> return value should be used
 only for subroutines which do not return a value, I<even if> CODE:
-directive is used which sets ST(0) explicitly. 
+directive is used which sets ST(0) explicitly.
 
 Older versions of this document recommended to use C<void> return
 value in such cases. It was discovered that this could lead to
@@ -277,6 +277,17 @@ typemap.
           OUTPUT:
           timep sv_setnv(ST(1), (double)timep);
 
+B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
+OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
+behavior, as it takes care of properly invoking 'set' magic on output
+parameters (needed for hash or array element parameters that must be
+created if they didn't exist).  If for some reason, this behavior is
+not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
+to disable it for the remainder of the parameters in the OUTPUT section.
+Likewise,  C<SETMAGIC: ENABLE> can be used to reenable it for the
+remainder of the OUTPUT section.  See L<perlguts> for more details
+about 'set' magic.
+
 =head2 The CODE: Keyword
 
 This keyword is used in more complicated XSUBs which require
@@ -289,7 +300,7 @@ its parameters.  The Perl usage is given first.
 
      $status = rpcb_gettime( "localhost", $timep );
 
-The XSUB follows. 
+The XSUB follows.
 
      bool_t
      rpcb_gettime(host,timep)
@@ -547,7 +558,7 @@ Perl as a single list.
           bool_t  status;
           PPCODE:
           status = rpcb_gettime( host, &timep );
-          EXTEND(sp, 2);
+          EXTEND(SP, 2);
           PUSHs(sv_2mortal(newSViv(status)));
           PUSHs(sv_2mortal(newSViv(timep)));
 
@@ -562,7 +573,7 @@ directive.
 
 The EXTEND() macro is used to make room on the argument
 stack for 2 return values.  The PPCODE: directive causes the
-B<xsubpp> compiler to create a stack pointer called C<sp>, and it
+B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
 is this pointer which is being used in the EXTEND() macro.
 The values are then pushed onto the stack with the PUSHs()
 macro.
@@ -572,6 +583,9 @@ the following statement.
 
      ($status, $timep) = rpcb_gettime("localhost");
 
+When handling output parameters with a PPCODE section, be sure to handle
+'set' magic properly.  See L<perlguts> for details about 'set' magic.
+
 =head2 Returning Undef And Empty Lists
 
 Occasionally the programmer will want to return simply
@@ -694,7 +708,7 @@ To disable version checking:
 =head2 The PROTOTYPES: Keyword
 
 The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
-C<-noprototypes> options.  This keyword overrides the command-line options.
+C<-noprototypes> options.  This keyword overrides the command line options.
 Prototypes are enabled by default.  When prototypes are enabled XSUBs will
 be given Perl prototypes.  This keyword may be used multiple times in an XS
 module to enable and disable prototypes for different parts of the module.
@@ -1102,6 +1116,37 @@ that the C unary operator C<*> is considered to be a part of the C type name.
      TYPEMAP
      Netconfig *<tab>T_PTROBJ
 
+Here's a more complicated example: suppose that you wanted C<struct
+netconfig> to be blessed into the class C<Net::Config>.  One way to do
+this is to use underscores (_) to separate package names, as follows:
+
+        typedef struct netconfig * Net_Config;
+
+And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
+double-colons (::), and declare C<Net_Config> to be of that type:
+
+
+        TYPEMAP
+        Net_Config      T_PTROBJ_SPECIAL
+
+        INPUT
+        T_PTROBJ_SPECIAL
+                if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
+                        IV tmp = SvIV((SV*)SvRV($arg));
+                $var = ($type) tmp;
+                }
+                else
+                        croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
+
+        OUTPUT
+        T_PTROBJ_SPECIAL
+                sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
+                (void*)$var);
+
+The INPUT and OUTPUT sections substitute underscores for double-colons
+on the fly, giving the desired effect.  This example demonstrates some
+of the power and versatility of the typemap facility.
+
 =head1 EXAMPLES
 
 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.