[win32] enhancements to previous patch for XSUB OUTPUT args

	Message-Id: <199802090731.CAA04438@aatma.engin.umich.edu>
	Subject: Re: [PATCH] XSUB OUTPUT arguments and 'set' magic

p4raw-id: //depot/win32/perl@492

1 files changed, 16 insertions, 5 deletions

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index d257b196eb..07abd10564 100644
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -268,17 +268,25 @@ be seen by Perl.
 
 The OUTPUT: keyword will also allow an output parameter to
 be mapped to a matching piece of code rather than to a
-typemap.  The following duplicates the behavior of the
-typemap:
+typemap.
 
      bool_t
      rpcb_gettime(host,timep)
           char *host
           time_t &timep
           OUTPUT:
-          timep SvSetMagicNV(ST(1), (double)timep);
-
-See L<perlguts> for details about C<SvSetMagicNV()>.
+          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
 
@@ -575,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