Integrate with Sarathy. perl.h and util.c required manual resolving.

[perl5.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index c4a064d..ee582e0 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -181,10 +181,10 @@ 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
-segfaults in cases when XSUB was I<truely> C<void>. This practice is
+segfaults in cases when XSUB was I<truly> C<void>. This practice is
 now deprecated, and may be not supported at some future version. Use
 the return value C<SV *> in such cases. (Currently C<xsubpp> contains
-some heuristic code which tries to disambiguate between "truely-void"
+some heuristic code which tries to disambiguate between "truly-void"
 and "old-practice-declared-as-void" functions. Hence your code is at
 mercy of this heuristics unless you use C<SV *> as return value.)
 
@@ -360,17 +360,19 @@ Function parameters are normally initialized with their
 values from the argument stack.  The typemaps contain the
 code segments which are used to transfer the Perl values to
 the C parameters.  The programmer, however, is allowed to
-override the typemaps and supply alternate initialization
-code.
+override the typemaps and supply alternate (or additional)
+initialization code.
 
 The following code demonstrates how to supply initialization code for
-function parameters.  The initialization code is eval'd by the compiler
-before it is added to the output so anything which should be interpreted
-literally, such as double quotes, must be protected with backslashes.
+function parameters.  The initialization code is eval'd within double
+quotes by the compiler before it is added to the output so anything
+which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
+must be protected with backslashes.  The variables $var, $arg,
+and $type can be used as in typemaps.
 
      bool_t
      rpcb_gettime(host,timep)
-          char *host = (char *)SvPV(ST(0),na);
+          char *host = (char *)SvPV($arg,PL_na);
           time_t &timep = 0;
           OUTPUT:
           timep
@@ -380,6 +382,24 @@ would normally use this when a function parameter must be processed by
 another library function before it can be used.  Default parameters are
 covered in the next section.
 
+If the initialization begins with C<=>, then it is output on
+the same line where the input variable is declared.  If the
+initialization begins with C<;> or C<+>, then it is output after
+all of the input variables have been declared.  The C<=> and C<;>
+cases replace the initialization normally supplied from the typemap.
+For the C<+> case, the initialization from the typemap will precede
+the initialization code included after the C<+>.  A global
+variable, C<%v>, is available for the truly rare case where
+information from one initialization is needed in another
+initialization.
+
+     bool_t
+     rpcb_gettime(host,timep)
+          time_t &timep ; /*\$v{time}=@{[$v{time}=$arg]}*/
+          char *host + SvOK($v{time}) ? SvPV($arg,PL_na) : NULL;
+          OUTPUT:
+          timep
+
 =head2 Default Parameter Values
 
 Default values can be specified for function parameters by
@@ -533,9 +553,10 @@ 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), na);
+                      host = (char *)SvPV(ST(1), n_a);
                  RETVAL = rpcb_gettime( host, &timep );
           OUTPUT:
           timep
@@ -661,7 +682,7 @@ return value, should the need arise.
                sv_setnv( ST(0), (double)timep);
           }
           else{
-               ST(0) = &sv_undef;
+               ST(0) = &PL_sv_undef;
           }
 
 To return an empty list one must use a PPCODE: block and
@@ -766,9 +787,10 @@ prototypes.
          PROTOTYPE: $;$
          PREINIT:
           char *host = "localhost";
+         STRLEN n_a;
           CODE:
                  if( items > 1 )
-                      host = (char *)SvPV(ST(1), na);
+                      host = (char *)SvPV(ST(1), n_a);
                  RETVAL = rpcb_gettime( host, &timep );
           OUTPUT:
           timep
@@ -1192,13 +1214,15 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine.
 The typemap is a collection of code fragments which are used by the B<xsubpp>
 compiler to map C function parameters and values to Perl values.  The
 typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>.  The INPUT section tells the compiler how to translate Perl values
+C<OUTPUT>.  Any unlabelled initial section is assumed to be a C<TYPEMAP>
+section if a name is not explicitly specified.  The INPUT section tells
+the compiler how to translate Perl values
 into variables of certain C types.  The OUTPUT section tells the compiler
 how to translate the values from certain C types into values Perl can
 understand.  The TYPEMAP section tells the compiler which of the INPUT and
 OUTPUT code fragments should be used to map a given C type to a Perl value.
-Each of the sections of the typemap must be preceded by one of the TYPEMAP,
-INPUT, or OUTPUT keywords.
+The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
+in the first column on a line by themselves, and must be in uppercase.
 
 The default typemap in the C<ext> directory of the Perl source contains many
 useful types which can be used by Perl extensions.  Some extensions define