home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / pod / perlxs.pod < prev    next >
Text File  |  2000-02-27  |  58KB  |  1,640 lines

  1. =head1 NAME
  2.  
  3. perlxs - XS language reference manual
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. =head2 Introduction
  8.  
  9. XS is an interface description file format used to create an extension
  10. interface between Perl and C code (or a C library) which one wishes
  11. to use with Perl.  The XS interface is combined with the library to
  12. create a new library which can then be either dynamically loaded
  13. or statically linked into perl.  The XS interface description is
  14. written in the XS language and is the core component of the Perl
  15. extension interface.
  16.  
  17. An B<XSUB> forms the basic unit of the XS interface.  After compilation
  18. by the B<xsubpp> compiler, each XSUB amounts to a C function definition
  19. which will provide the glue between Perl calling conventions and C
  20. calling conventions.
  21.  
  22. The glue code pulls the arguments from the Perl stack, converts these
  23. Perl values to the formats expected by a C function, call this C function,
  24. transfers the return values of the C function back to Perl.
  25. Return values here may be a conventional C return value or any C
  26. function arguments that may serve as output parameters.  These return
  27. values may be passed back to Perl either by putting them on the
  28. Perl stack, or by modifying the arguments supplied from the Perl side.
  29.  
  30. The above is a somewhat simplified view of what really happens.  Since
  31. Perl allows more flexible calling conventions than C, XSUBs may do much
  32. more in practice, such as checking input parameters for validity,
  33. throwing exceptions (or returning undef/empty list) if the return value
  34. from the C function indicates failure, calling different C functions
  35. based on numbers and types of the arguments, providing an object-oriented
  36. interface, etc.
  37.  
  38. Of course, one could write such glue code directly in C.  However, this
  39. would be a tedious task, especially if one needs to write glue for
  40. multiple C functions, and/or one is not familiar enough with the Perl
  41. stack discipline and other such arcana.  XS comes to the rescue here:
  42. instead of writing this glue C code in long-hand, one can write
  43. a more concise short-hand I<description> of what should be done by
  44. the glue, and let the XS compiler B<xsubpp> handle the rest.
  45.  
  46. The XS language allows one to describe the mapping between how the C
  47. routine is used, and how the corresponding Perl routine is used.  It
  48. also allows creation of Perl routines which are directly translated to
  49. C code and which are not related to a pre-existing C function.  In cases
  50. when the C interface coincides with the Perl interface, the XSUB
  51. declaration is almost identical to a declaration of a C function (in K&R
  52. style).  In such circumstances, there is another tool called C<h2xs>
  53. that is able to translate an entire C header file into a corresponding
  54. XS file that will provide glue to the functions/macros described in
  55. the header file.
  56.  
  57. The XS compiler is called B<xsubpp>.  This compiler creates
  58. the constructs necessary to let an XSUB manipulate Perl values, and
  59. creates the glue necessary to let Perl call the XSUB.  The compiler
  60. uses B<typemaps> to determine how to map C function parameters
  61. and output values to Perl values and back.  The default typemap
  62. (which comes with Perl) handles many common C types.  A supplementary
  63. typemap may also be needed to handle any special structures and types
  64. for the library being linked.
  65.  
  66. A file in XS format starts with a C language section which goes until the
  67. first C<MODULE =Z<>> directive.  Other XS directives and XSUB definitions
  68. may follow this line.  The "language" used in this part of the file
  69. is usually referred to as the XS language.
  70.  
  71. See L<perlxstut> for a tutorial on the whole extension creation process.
  72.  
  73. Note: For some extensions, Dave Beazley's SWIG system may provide a
  74. significantly more convenient mechanism for creating the extension glue
  75. code. See L<http://www.swig.org> for more 
  76. information.
  77.  
  78. =head2 On The Road
  79.  
  80. Many of the examples which follow will concentrate on creating an interface
  81. between Perl and the ONC+ RPC bind library functions.  The rpcb_gettime()
  82. function is used to demonstrate many features of the XS language.  This
  83. function has two parameters; the first is an input parameter and the second
  84. is an output parameter.  The function also returns a status value.
  85.  
  86.     bool_t rpcb_gettime(const char *host, time_t *timep);
  87.  
  88. From C this function will be called with the following
  89. statements.
  90.  
  91.      #include <rpc/rpc.h>
  92.      bool_t status;
  93.      time_t timep;
  94.      status = rpcb_gettime( "localhost", &timep );
  95.  
  96. If an XSUB is created to offer a direct translation between this function
  97. and Perl, then this XSUB will be used from Perl with the following code.
  98. The $status and $timep variables will contain the output of the function.
  99.  
  100.      use RPC;
  101.      $status = rpcb_gettime( "localhost", $timep );
  102.  
  103. The following XS file shows an XS subroutine, or XSUB, which
  104. demonstrates one possible interface to the rpcb_gettime()
  105. function.  This XSUB represents a direct translation between
  106. C and Perl and so preserves the interface even from Perl.
  107. This XSUB will be invoked from Perl with the usage shown
  108. above.  Note that the first three #include statements, for
  109. C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
  110. beginning of an XS file.  This approach and others will be
  111. expanded later in this document.
  112.  
  113.      #include "EXTERN.h"
  114.      #include "perl.h"
  115.      #include "XSUB.h"
  116.      #include <rpc/rpc.h>
  117.  
  118.      MODULE = RPC  PACKAGE = RPC
  119.  
  120.      bool_t
  121.      rpcb_gettime(host,timep)
  122.           char *host
  123.           time_t &timep
  124.         OUTPUT:
  125.           timep
  126.  
  127. Any extension to Perl, including those containing XSUBs,
  128. should have a Perl module to serve as the bootstrap which
  129. pulls the extension into Perl.  This module will export the
  130. extension's functions and variables to the Perl program and
  131. will cause the extension's XSUBs to be linked into Perl.
  132. The following module will be used for most of the examples
  133. in this document and should be used from Perl with the C<use>
  134. command as shown earlier.  Perl modules are explained in
  135. more detail later in this document.
  136.  
  137.      package RPC;
  138.  
  139.      require Exporter;
  140.      require DynaLoader;
  141.      @ISA = qw(Exporter DynaLoader);
  142.      @EXPORT = qw( rpcb_gettime );
  143.  
  144.      bootstrap RPC;
  145.      1;
  146.  
  147. Throughout this document a variety of interfaces to the rpcb_gettime()
  148. XSUB will be explored.  The XSUBs will take their parameters in different
  149. orders or will take different numbers of parameters.  In each case the
  150. XSUB is an abstraction between Perl and the real C rpcb_gettime()
  151. function, and the XSUB must always ensure that the real rpcb_gettime()
  152. function is called with the correct parameters.  This abstraction will
  153. allow the programmer to create a more Perl-like interface to the C
  154. function.
  155.  
  156. =head2 The Anatomy of an XSUB
  157.  
  158. The simplest XSUBs consist of 3 parts: a description of the return
  159. value, the name of the XSUB routine and the names of its arguments,
  160. and a description of types or formats of the arguments.
  161.  
  162. The following XSUB allows a Perl program to access a C library function
  163. called sin().  The XSUB will imitate the C function which takes a single
  164. argument and returns a single value.
  165.  
  166.      double
  167.      sin(x)
  168.        double x
  169.  
  170. When using parameters with C pointer types, as in
  171.  
  172.      double string_to_double(char *s);
  173.  
  174. there may be two ways to describe this argument to B<xsubpp>:
  175.  
  176.      char *  s
  177.      char    &s
  178.  
  179. Both these XS declarations correspond to the C<char*> C type, but they have
  180. different semantics.  It is convenient to think that the indirection operator
  181. C<*> should be considered as a part of the type and the address operator C<&>
  182. should be considered part of the variable.  See L<"The Typemap"> and
  183. L<"The & Unary Operator"> for more info about handling qualifiers and unary
  184. operators in C types.
  185.  
  186. The function name and the return type must be placed on
  187. separate lines and should be flush left-adjusted.
  188.  
  189.   INCORRECT                        CORRECT
  190.  
  191.   double sin(x)                    double
  192.     double x                       sin(x)
  193.                      double x
  194.  
  195. The function body may be indented or left-adjusted.  The following example
  196. shows a function with its body left-adjusted.  Most examples in this
  197. document will indent the body for better readability.
  198.  
  199.   CORRECT
  200.  
  201.   double
  202.   sin(x)
  203.   double x
  204.  
  205. More complicated XSUBs may contain many other sections.  Each section of
  206. an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
  207. However, the first two lines of an XSUB always contain the same data:
  208. descriptions of the return type and the names of the function and its
  209. parameters.  Whatever immediately follows these is considered to be
  210. an INPUT: section unless explicitly marked with another keyword.
  211. (See L<The INPUT: Keyword>.)
  212.  
  213. An XSUB section continues until another section-start keyword is found.
  214.  
  215. =head2 The Argument Stack
  216.  
  217. The Perl argument stack is used to store the values which are
  218. sent as parameters to the XSUB and to store the XSUB's
  219. return value(s).  In reality all Perl functions (including non-XSUB
  220. ones) keep their values on this stack all the same time, each limited
  221. to its own range of positions on the stack.  In this document the
  222. first position on that stack which belongs to the active
  223. function will be referred to as position 0 for that function.
  224.  
  225. XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
  226. refers to a position in this XSUB's part of the stack.  Position 0 for that
  227. function would be known to the XSUB as ST(0).  The XSUB's incoming
  228. parameters and outgoing return values always begin at ST(0).  For many
  229. simple cases the B<xsubpp> compiler will generate the code necessary to
  230. handle the argument stack by embedding code fragments found in the
  231. typemaps.  In more complex cases the programmer must supply the code.
  232.  
  233. =head2 The RETVAL Variable
  234.  
  235. The RETVAL variable is a special C variable that is declared automatically
  236. for you.  The C type of RETVAL matches the return type of the C library
  237. function.  The B<xsubpp> compiler will declare this variable in each XSUB
  238. with non-C<void> return type.  By default the generated C function
  239. will use RETVAL to hold the return value of the C library function being
  240. called.  In simple cases the value of RETVAL will be placed in ST(0) of
  241. the argument stack where it can be received by Perl as the return value
  242. of the XSUB.
  243.  
  244. If the XSUB has a return type of C<void> then the compiler will
  245. not declare a RETVAL variable for that function.  When using
  246. a PPCODE: section no manipulation of the RETVAL variable is required, the
  247. section may use direct stack manipulation to place output values on the stack.
  248.  
  249. If PPCODE: directive is not used, C<void> return value should be used
  250. only for subroutines which do not return a value, I<even if> CODE:
  251. directive is used which sets ST(0) explicitly.
  252.  
  253. Older versions of this document recommended to use C<void> return
  254. value in such cases. It was discovered that this could lead to
  255. segfaults in cases when XSUB was I<truly> C<void>. This practice is
  256. now deprecated, and may be not supported at some future version. Use
  257. the return value C<SV *> in such cases. (Currently C<xsubpp> contains
  258. some heuristic code which tries to disambiguate between "truly-void"
  259. and "old-practice-declared-as-void" functions. Hence your code is at
  260. mercy of this heuristics unless you use C<SV *> as return value.)
  261.  
  262. =head2 The MODULE Keyword
  263.  
  264. The MODULE keyword is used to start the XS code and to
  265. specify the package of the functions which are being
  266. defined.  All text preceding the first MODULE keyword is
  267. considered C code and is passed through to the output
  268. untouched.  Every XS module will have a bootstrap function
  269. which is used to hook the XSUBs into Perl.  The package name
  270. of this bootstrap function will match the value of the last
  271. MODULE statement in the XS source files.  The value of
  272. MODULE should always remain constant within the same XS
  273. file, though this is not required.
  274.  
  275. The following example will start the XS code and will place
  276. all functions in a package named RPC.
  277.  
  278.      MODULE = RPC
  279.  
  280. =head2 The PACKAGE Keyword
  281.  
  282. When functions within an XS source file must be separated into packages
  283. the PACKAGE keyword should be used.  This keyword is used with the MODULE
  284. keyword and must follow immediately after it when used.
  285.  
  286.      MODULE = RPC  PACKAGE = RPC
  287.  
  288.      [ XS code in package RPC ]
  289.  
  290.      MODULE = RPC  PACKAGE = RPCB
  291.  
  292.      [ XS code in package RPCB ]
  293.  
  294.      MODULE = RPC  PACKAGE = RPC
  295.  
  296.      [ XS code in package RPC ]
  297.  
  298. Although this keyword is optional and in some cases provides redundant
  299. information it should always be used.  This keyword will ensure that the
  300. XSUBs appear in the desired package.
  301.  
  302. =head2 The PREFIX Keyword
  303.  
  304. The PREFIX keyword designates prefixes which should be
  305. removed from the Perl function names.  If the C function is
  306. C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
  307. see this function as C<gettime()>.
  308.  
  309. This keyword should follow the PACKAGE keyword when used.
  310. If PACKAGE is not used then PREFIX should follow the MODULE
  311. keyword.
  312.  
  313.      MODULE = RPC  PREFIX = rpc_
  314.  
  315.      MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
  316.  
  317. =head2 The OUTPUT: Keyword
  318.  
  319. The OUTPUT: keyword indicates that certain function parameters should be
  320. updated (new values made visible to Perl) when the XSUB terminates or that
  321. certain values should be returned to the calling Perl function.  For
  322. simple functions which have no CODE: or PPCODE: section,
  323. such as the sin() function above, the RETVAL variable is
  324. automatically designated as an output value.  For more complex functions
  325. the B<xsubpp> compiler will need help to determine which variables are output
  326. variables.
  327.  
  328. This keyword will normally be used to complement the CODE:  keyword.
  329. The RETVAL variable is not recognized as an output variable when the
  330. CODE: keyword is present.  The OUTPUT:  keyword is used in this
  331. situation to tell the compiler that RETVAL really is an output
  332. variable.
  333.  
  334. The OUTPUT: keyword can also be used to indicate that function parameters
  335. are output variables.  This may be necessary when a parameter has been
  336. modified within the function and the programmer would like the update to
  337. be seen by Perl.
  338.  
  339.      bool_t
  340.      rpcb_gettime(host,timep)
  341.           char *host
  342.           time_t &timep
  343.         OUTPUT:
  344.           timep
  345.  
  346. The OUTPUT: keyword will also allow an output parameter to
  347. be mapped to a matching piece of code rather than to a
  348. typemap.
  349.  
  350.      bool_t
  351.      rpcb_gettime(host,timep)
  352.           char *host
  353.           time_t &timep
  354.         OUTPUT:
  355.           timep sv_setnv(ST(1), (double)timep);
  356.  
  357. B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
  358. OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
  359. behavior, as it takes care of properly invoking 'set' magic on output
  360. parameters (needed for hash or array element parameters that must be
  361. created if they didn't exist).  If for some reason, this behavior is
  362. not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
  363. to disable it for the remainder of the parameters in the OUTPUT section.
  364. Likewise,  C<SETMAGIC: ENABLE> can be used to reenable it for the
  365. remainder of the OUTPUT section.  See L<perlguts> for more details
  366. about 'set' magic.
  367.  
  368. =head2 The CODE: Keyword
  369.  
  370. This keyword is used in more complicated XSUBs which require
  371. special handling for the C function.  The RETVAL variable is
  372. still declared, but it will not be returned unless it is specified
  373. in the OUTPUT: section.
  374.  
  375. The following XSUB is for a C function which requires special handling of
  376. its parameters.  The Perl usage is given first.
  377.  
  378.      $status = rpcb_gettime( "localhost", $timep );
  379.  
  380. The XSUB follows.
  381.  
  382.      bool_t
  383.      rpcb_gettime(host,timep)
  384.           char *host
  385.           time_t timep
  386.         CODE:
  387.                RETVAL = rpcb_gettime( host, &timep );
  388.         OUTPUT:
  389.           timep
  390.           RETVAL
  391.  
  392. =head2 The INIT: Keyword
  393.  
  394. The INIT: keyword allows initialization to be inserted into the XSUB before
  395. the compiler generates the call to the C function.  Unlike the CODE: keyword
  396. above, this keyword does not affect the way the compiler handles RETVAL.
  397.  
  398.     bool_t
  399.     rpcb_gettime(host,timep)
  400.           char *host
  401.           time_t &timep
  402.     INIT:
  403.       printf("# Host is %s\n", host );
  404.         OUTPUT:
  405.           timep
  406.  
  407. Another use for the INIT: section is to check for preconditions before
  408. making a call to the C function:
  409.  
  410.     long long
  411.     lldiv(a,b)
  412.     long long a
  413.     long long b
  414.       INIT:
  415.     if (a == 0 && b == 0)
  416.         XSRETURN_UNDEF;
  417.     if (b == 0)
  418.         croak("lldiv: cannot divide by 0");
  419.  
  420. =head2 The NO_INIT Keyword
  421.  
  422. The NO_INIT keyword is used to indicate that a function
  423. parameter is being used only as an output value.  The B<xsubpp>
  424. compiler will normally generate code to read the values of
  425. all function parameters from the argument stack and assign
  426. them to C variables upon entry to the function.  NO_INIT
  427. will tell the compiler that some parameters will be used for
  428. output rather than for input and that they will be handled
  429. before the function terminates.
  430.  
  431. The following example shows a variation of the rpcb_gettime() function.
  432. This function uses the timep variable only as an output variable and does
  433. not care about its initial contents.
  434.  
  435.      bool_t
  436.      rpcb_gettime(host,timep)
  437.           char *host
  438.           time_t &timep = NO_INIT
  439.         OUTPUT:
  440.           timep
  441.  
  442. =head2 Initializing Function Parameters
  443.  
  444. C function parameters are normally initialized with their values from
  445. the argument stack (which in turn contains the parameters that were
  446. passed to the XSUB from Perl).  The typemaps contain the
  447. code segments which are used to translate the Perl values to
  448. the C parameters.  The programmer, however, is allowed to
  449. override the typemaps and supply alternate (or additional)
  450. initialization code.  Initialization code starts with the first
  451. C<=>, C<;> or C<+> on a line in the INPUT: section.  The only
  452. exception happens if this C<;> terminates the line, then this C<;>
  453. is quietly ignored.
  454.  
  455. The following code demonstrates how to supply initialization code for
  456. function parameters.  The initialization code is eval'd within double
  457. quotes by the compiler before it is added to the output so anything
  458. which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
  459. must be protected with backslashes.  The variables $var, $arg,
  460. and $type can be used as in typemaps.
  461.  
  462.      bool_t
  463.      rpcb_gettime(host,timep)
  464.           char *host = (char *)SvPV($arg,PL_na);
  465.           time_t &timep = 0;
  466.         OUTPUT:
  467.           timep
  468.  
  469. This should not be used to supply default values for parameters.  One
  470. would normally use this when a function parameter must be processed by
  471. another library function before it can be used.  Default parameters are
  472. covered in the next section.
  473.  
  474. If the initialization begins with C<=>, then it is output in
  475. the declaration for the input variable, replacing the initialization
  476. supplied by the typemap.  If the initialization
  477. begins with C<;> or C<+>, then it is performed after
  478. all of the input variables have been declared.  In the C<;>
  479. case the initialization normally supplied by the typemap is not performed.
  480. For the C<+> case, the declaration for the variable will include the
  481. initialization from the typemap.  A global
  482. variable, C<%v>, is available for the truly rare case where
  483. information from one initialization is needed in another
  484. initialization.
  485.  
  486. Here's a truly obscure example:
  487.  
  488.      bool_t
  489.      rpcb_gettime(host,timep)
  490.           time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
  491.           char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
  492.         OUTPUT:
  493.           timep
  494.  
  495. The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
  496. example has a two-fold purpose: first, when this line is processed by
  497. B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated.  Second,
  498. the text of the evaluated snippet is output into the generated C file
  499. (inside a C comment)!  During the processing of C<char *host> line,
  500. $arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
  501. C<ST(1)>.
  502.  
  503. =head2 Default Parameter Values
  504.  
  505. Default values for XSUB arguments can be specified by placing an
  506. assignment statement in the parameter list.  The default value may
  507. be a number, a string or the special string C<NO_INIT>.  Defaults should
  508. always be used on the right-most parameters only.
  509.  
  510. To allow the XSUB for rpcb_gettime() to have a default host
  511. value the parameters to the XSUB could be rearranged.  The
  512. XSUB will then call the real rpcb_gettime() function with
  513. the parameters in the correct order.  This XSUB can be called
  514. from Perl with either of the following statements:
  515.  
  516.      $status = rpcb_gettime( $timep, $host );
  517.  
  518.      $status = rpcb_gettime( $timep );
  519.  
  520. The XSUB will look like the code  which  follows.   A  CODE:
  521. block  is used to call the real rpcb_gettime() function with
  522. the parameters in the correct order for that function.
  523.  
  524.      bool_t
  525.      rpcb_gettime(timep,host="localhost")
  526.           char *host
  527.           time_t timep = NO_INIT
  528.         CODE:
  529.                RETVAL = rpcb_gettime( host, &timep );
  530.         OUTPUT:
  531.           timep
  532.           RETVAL
  533.  
  534. =head2 The PREINIT: Keyword
  535.  
  536. The PREINIT: keyword allows extra variables to be declared immediately
  537. before or after the declartions of the parameters from the INPUT: section
  538. are emitted.
  539.  
  540. If a variable is declared inside a CODE: section it will follow any typemap
  541. code that is emitted for the input parameters.  This may result in the
  542. declaration ending up after C code, which is C syntax error.  Similar
  543. errors may happen with an explicit C<;>-type or C<+>-type initialization of
  544. parameters is used (see L<"Initializing Function Parameters">).  Declaring
  545. these variables in an INIT: section will not help.
  546.  
  547. In such cases, to force an additional variable to be declared together
  548. with declarations of other variables, place the declaration into a
  549. PREINIT: section.  The PREINIT: keyword may be used one or more times
  550. within an XSUB.
  551.  
  552. The following examples are equivalent, but if the code is using complex
  553. typemaps then the first example is safer.
  554.  
  555.      bool_t
  556.      rpcb_gettime(timep)
  557.           time_t timep = NO_INIT
  558.     PREINIT:
  559.           char *host = "localhost";
  560.         CODE:
  561.       RETVAL = rpcb_gettime( host, &timep );
  562.         OUTPUT:
  563.           timep
  564.           RETVAL
  565.  
  566. For this particular case an INIT: keyword would generate the
  567. same C code as the PREINIT: keyword.  Another correct, but error-prone example:
  568.  
  569.      bool_t
  570.      rpcb_gettime(timep)
  571.           time_t timep = NO_INIT
  572.     CODE:
  573.           char *host = "localhost";
  574.       RETVAL = rpcb_gettime( host, &timep );
  575.         OUTPUT:
  576.           timep
  577.           RETVAL
  578.  
  579. Another way to declare C<host> is to use a C block in the CODE: section:
  580.  
  581.      bool_t
  582.      rpcb_gettime(timep)
  583.           time_t timep = NO_INIT
  584.     CODE:
  585.       {
  586.             char *host = "localhost";
  587.         RETVAL = rpcb_gettime( host, &timep );
  588.       }
  589.         OUTPUT:
  590.           timep
  591.           RETVAL
  592.  
  593. The ability to put additional declarations before the typemap entries are
  594. processed is very handy in the cases when typemap conversions manipulate
  595. some global state:
  596.  
  597.     MyObject
  598.     mutate(o)
  599.     PREINIT:
  600.         MyState st = global_state;
  601.     INPUT:
  602.         MyObject o;
  603.     CLEANUP:
  604.         reset_to(global_state, st);
  605.  
  606. Here we suppose that conversion to C<MyObject> in the INPUT: section and from
  607. MyObject when processing RETVAL will modify a global variable C<global_state>.
  608. After these conversions are performed, we restore the old value of
  609. C<global_state> (to avoid memory leaks, for example).
  610.  
  611. There is another way to trade clarity for compactness: INPUT sections allow
  612. declaration of C variables which do not appear in the parameter list of
  613. a subroutine.  Thus the above code for mutate() can be rewritten as
  614.  
  615.     MyObject
  616.     mutate(o)
  617.       MyState st = global_state;
  618.       MyObject o;
  619.     CLEANUP:
  620.       reset_to(global_state, st);
  621.  
  622. and the code for rpcb_gettime() can be rewritten as
  623.  
  624.      bool_t
  625.      rpcb_gettime(timep)
  626.       time_t timep = NO_INIT
  627.       char *host = "localhost";
  628.     C_ARGS:
  629.       host, &timep
  630.     OUTPUT:
  631.           timep
  632.           RETVAL
  633.  
  634. =head2 The SCOPE: Keyword
  635.  
  636. The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
  637. enabled, the XSUB will invoke ENTER and LEAVE automatically.
  638.  
  639. To support potentially complex type mappings, if a typemap entry used
  640. by an XSUB contains a comment like C</*scope*/> then scoping will
  641. be automatically enabled for that XSUB.
  642.  
  643. To enable scoping:
  644.  
  645.     SCOPE: ENABLE
  646.  
  647. To disable scoping:
  648.  
  649.     SCOPE: DISABLE
  650.  
  651. =head2 The INPUT: Keyword
  652.  
  653. The XSUB's parameters are usually evaluated immediately after entering the
  654. XSUB.  The INPUT: keyword can be used to force those parameters to be
  655. evaluated a little later.  The INPUT: keyword can be used multiple times
  656. within an XSUB and can be used to list one or more input variables.  This
  657. keyword is used with the PREINIT: keyword.
  658.  
  659. The following example shows how the input parameter C<timep> can be
  660. evaluated late, after a PREINIT.
  661.  
  662.     bool_t
  663.     rpcb_gettime(host,timep)
  664.           char *host
  665.     PREINIT:
  666.       time_t tt;
  667.     INPUT:
  668.           time_t timep
  669.         CODE:
  670.                RETVAL = rpcb_gettime( host, &tt );
  671.            timep = tt;
  672.         OUTPUT:
  673.           timep
  674.           RETVAL
  675.  
  676. The next example shows each input parameter evaluated late.
  677.  
  678.     bool_t
  679.     rpcb_gettime(host,timep)
  680.     PREINIT:
  681.       time_t tt;
  682.     INPUT:
  683.           char *host
  684.     PREINIT:
  685.       char *h;
  686.     INPUT:
  687.           time_t timep
  688.         CODE:
  689.            h = host;
  690.            RETVAL = rpcb_gettime( h, &tt );
  691.            timep = tt;
  692.         OUTPUT:
  693.           timep
  694.           RETVAL
  695.  
  696. Since INPUT sections allow declaration of C variables which do not appear
  697. in the parameter list of a subroutine, this may be shortened to:
  698.  
  699.     bool_t
  700.     rpcb_gettime(host,timep)
  701.       time_t tt;
  702.           char *host;
  703.       char *h = host;
  704.           time_t timep;
  705.         CODE:
  706.       RETVAL = rpcb_gettime( h, &tt );
  707.       timep = tt;
  708.         OUTPUT:
  709.           timep
  710.           RETVAL
  711.  
  712. (We used our knowledge that input conversion for C<char *> is a "simple" one,
  713. thus C<host> is initialized on the declaration line, and our assignment
  714. C<h = host> is not performed too early.  Otherwise one would need to have the
  715. assignment C<h = host> in a CODE: or INIT: section.)
  716.  
  717. =head2 Variable-length Parameter Lists
  718.  
  719. XSUBs can have variable-length parameter lists by specifying an ellipsis
  720. C<(...)> in the parameter list.  This use of the ellipsis is similar to that
  721. found in ANSI C.  The programmer is able to determine the number of
  722. arguments passed to the XSUB by examining the C<items> variable which the
  723. B<xsubpp> compiler supplies for all XSUBs.  By using this mechanism one can
  724. create an XSUB which accepts a list of parameters of unknown length.
  725.  
  726. The I<host> parameter for the rpcb_gettime() XSUB can be
  727. optional so the ellipsis can be used to indicate that the
  728. XSUB will take a variable number of parameters.  Perl should
  729. be able to call this XSUB with either of the following statements.
  730.  
  731.      $status = rpcb_gettime( $timep, $host );
  732.  
  733.      $status = rpcb_gettime( $timep );
  734.  
  735. The XS code, with ellipsis, follows.
  736.  
  737.      bool_t
  738.      rpcb_gettime(timep, ...)
  739.           time_t timep = NO_INIT
  740.     PREINIT:
  741.           char *host = "localhost";
  742.       STRLEN n_a;
  743.         CODE:
  744.       if( items > 1 )
  745.            host = (char *)SvPV(ST(1), n_a);
  746.       RETVAL = rpcb_gettime( host, &timep );
  747.         OUTPUT:
  748.           timep
  749.           RETVAL
  750.  
  751. =head2 The C_ARGS: Keyword
  752.  
  753. The C_ARGS: keyword allows creating of XSUBS which have different
  754. calling sequence from Perl than from C, without a need to write
  755. CODE: or PPCODE: section.  The contents of the C_ARGS: paragraph is
  756. put as the argument to the called C function without any change.
  757.  
  758. For example, suppose that a C function is declared as
  759.  
  760.     symbolic nth_derivative(int n, symbolic function, int flags);
  761.  
  762. and that the default flags are kept in a global C variable
  763. C<default_flags>.  Suppose that you want to create an interface which
  764. is called as
  765.  
  766.     $second_deriv = $function->nth_derivative(2);
  767.  
  768. To do this, declare the XSUB as
  769.  
  770.     symbolic
  771.     nth_derivative(function, n)
  772.     symbolic    function
  773.     int        n
  774.       C_ARGS:
  775.     n, function, default_flags
  776.  
  777. =head2 The PPCODE: Keyword
  778.  
  779. The PPCODE: keyword is an alternate form of the CODE: keyword and is used
  780. to tell the B<xsubpp> compiler that the programmer is supplying the code to
  781. control the argument stack for the XSUBs return values.  Occasionally one
  782. will want an XSUB to return a list of values rather than a single value.
  783. In these cases one must use PPCODE: and then explicitly push the list of
  784. values on the stack.  The PPCODE: and CODE:  keywords should not be used
  785. together within the same XSUB.
  786.  
  787. The actual difference between PPCODE: and CODE: sections is in the
  788. initialization of C<SP> macro (which stands for the I<current> Perl
  789. stack pointer), and in the handling of data on the stack when returning
  790. from an XSUB.  In CODE: sections SP preserves the value which was on
  791. entry to the XSUB: SP is on the function pointer (which follows the
  792. last parameter).  In PPCODE: sections SP is moved backward to the
  793. beginning of the parameter list, which allows C<PUSH*()> macros
  794. to place output values in the place Perl expects them to be when
  795. the XSUB returns back to Perl.
  796.  
  797. The generated trailer for a CODE: section ensures that the number of return
  798. values Perl will see is either 0 or 1 (depending on the C<void>ness of the
  799. return value of the C function, and heuristics mentioned in
  800. L<"The RETVAL Variable">).  The trailer generated for a PPCODE: section
  801. is based on the number of return values and on the number of times
  802. C<SP> was updated by C<[X]PUSH*()> macros.
  803.  
  804. Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
  805. well in CODE: sections and PPCODE: sections.
  806.  
  807. The following XSUB will call the C rpcb_gettime() function
  808. and will return its two output values, timep and status, to
  809. Perl as a single list.
  810.  
  811.      void
  812.      rpcb_gettime(host)
  813.           char *host
  814.     PREINIT:
  815.           time_t  timep;
  816.           bool_t  status;
  817.         PPCODE:
  818.           status = rpcb_gettime( host, &timep );
  819.           EXTEND(SP, 2);
  820.           PUSHs(sv_2mortal(newSViv(status)));
  821.           PUSHs(sv_2mortal(newSViv(timep)));
  822.  
  823. Notice that the programmer must supply the C code necessary
  824. to have the real rpcb_gettime() function called and to have
  825. the return values properly placed on the argument stack.
  826.  
  827. The C<void> return type for this function tells the B<xsubpp> compiler that
  828. the RETVAL variable is not needed or used and that it should not be created.
  829. In most scenarios the void return type should be used with the PPCODE:
  830. directive.
  831.  
  832. The EXTEND() macro is used to make room on the argument
  833. stack for 2 return values.  The PPCODE: directive causes the
  834. B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
  835. is this pointer which is being used in the EXTEND() macro.
  836. The values are then pushed onto the stack with the PUSHs()
  837. macro.
  838.  
  839. Now the rpcb_gettime() function can be used from Perl with
  840. the following statement.
  841.  
  842.      ($status, $timep) = rpcb_gettime("localhost");
  843.  
  844. When handling output parameters with a PPCODE section, be sure to handle
  845. 'set' magic properly.  See L<perlguts> for details about 'set' magic.
  846.  
  847. =head2 Returning Undef And Empty Lists
  848.  
  849. Occasionally the programmer will want to return simply
  850. C<undef> or an empty list if a function fails rather than a
  851. separate status value.  The rpcb_gettime() function offers
  852. just this situation.  If the function succeeds we would like
  853. to have it return the time and if it fails we would like to
  854. have undef returned.  In the following Perl code the value
  855. of $timep will either be undef or it will be a valid time.
  856.  
  857.      $timep = rpcb_gettime( "localhost" );
  858.  
  859. The following XSUB uses the C<SV *> return type as a mnemonic only,
  860. and uses a CODE: block to indicate to the compiler
  861. that the programmer has supplied all the necessary code.  The
  862. sv_newmortal() call will initialize the return value to undef, making that
  863. the default return value.
  864.  
  865.      SV *
  866.      rpcb_gettime(host)
  867.           char *  host
  868.     PREINIT:
  869.           time_t  timep;
  870.           bool_t x;
  871.         CODE:
  872.           ST(0) = sv_newmortal();
  873.           if( rpcb_gettime( host, &timep ) )
  874.                sv_setnv( ST(0), (double)timep);
  875.  
  876. The next example demonstrates how one would place an explicit undef in the
  877. return value, should the need arise.
  878.  
  879.      SV *
  880.      rpcb_gettime(host)
  881.           char *  host
  882.     PREINIT:
  883.           time_t  timep;
  884.           bool_t x;
  885.         CODE:
  886.           ST(0) = sv_newmortal();
  887.           if( rpcb_gettime( host, &timep ) ){
  888.                sv_setnv( ST(0), (double)timep);
  889.           }
  890.           else{
  891.                ST(0) = &PL_sv_undef;
  892.           }
  893.  
  894. To return an empty list one must use a PPCODE: block and
  895. then not push return values on the stack.
  896.  
  897.      void
  898.      rpcb_gettime(host)
  899.           char *host
  900.     PREINIT:
  901.           time_t  timep;
  902.         PPCODE:
  903.           if( rpcb_gettime( host, &timep ) )
  904.                PUSHs(sv_2mortal(newSViv(timep)));
  905.           else{
  906.           /* Nothing pushed on stack, so an empty
  907.            * list is implicitly returned. */
  908.           }
  909.  
  910. Some people may be inclined to include an explicit C<return> in the above
  911. XSUB, rather than letting control fall through to the end.  In those
  912. situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that
  913. the XSUB stack is properly adjusted.  Consult L<perlguts/"API LISTING"> for
  914. other C<XSRETURN> macros.
  915.  
  916. Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
  917. rewrite this example as:
  918.  
  919.      int
  920.      rpcb_gettime(host)
  921.           char *host
  922.     PREINIT:
  923.           time_t  timep;
  924.         CODE:
  925.           RETVAL = rpcb_gettime( host, &timep );
  926.       if (RETVAL == 0)
  927.         XSRETURN_UNDEF;
  928.     OUTPUT:
  929.       RETVAL
  930.  
  931. In fact, one can put this check into a CLEANUP: section as well.  Together
  932. with PREINIT: simplifications, this leads to:
  933.  
  934.      int
  935.      rpcb_gettime(host)
  936.           char *host
  937.           time_t  timep;
  938.     CLEANUP:
  939.       if (RETVAL == 0)
  940.         XSRETURN_UNDEF;
  941.  
  942. =head2 The REQUIRE: Keyword
  943.  
  944. The REQUIRE: keyword is used to indicate the minimum version of the
  945. B<xsubpp> compiler needed to compile the XS module.  An XS module which
  946. contains the following statement will compile with only B<xsubpp> version
  947. 1.922 or greater:
  948.  
  949.     REQUIRE: 1.922
  950.  
  951. =head2 The CLEANUP: Keyword
  952.  
  953. This keyword can be used when an XSUB requires special cleanup procedures
  954. before it terminates.  When the CLEANUP:  keyword is used it must follow
  955. any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB.  The
  956. code specified for the cleanup block will be added as the last statements
  957. in the XSUB.
  958.  
  959. =head2 The BOOT: Keyword
  960.  
  961. The BOOT: keyword is used to add code to the extension's bootstrap
  962. function.  The bootstrap function is generated by the B<xsubpp> compiler and
  963. normally holds the statements necessary to register any XSUBs with Perl.
  964. With the BOOT: keyword the programmer can tell the compiler to add extra
  965. statements to the bootstrap function.
  966.  
  967. This keyword may be used any time after the first MODULE keyword and should
  968. appear on a line by itself.  The first blank line after the keyword will
  969. terminate the code block.
  970.  
  971.      BOOT:
  972.      # The following message will be printed when the
  973.      # bootstrap function executes.
  974.      printf("Hello from the bootstrap!\n");
  975.  
  976. =head2 The VERSIONCHECK: Keyword
  977.  
  978. The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
  979. C<-noversioncheck> options.  This keyword overrides the command line
  980. options.  Version checking is enabled by default.  When version checking is
  981. enabled the XS module will attempt to verify that its version matches the
  982. version of the PM module.
  983.  
  984. To enable version checking:
  985.  
  986.     VERSIONCHECK: ENABLE
  987.  
  988. To disable version checking:
  989.  
  990.     VERSIONCHECK: DISABLE
  991.  
  992. =head2 The PROTOTYPES: Keyword
  993.  
  994. The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
  995. C<-noprototypes> options.  This keyword overrides the command line options.
  996. Prototypes are enabled by default.  When prototypes are enabled XSUBs will
  997. be given Perl prototypes.  This keyword may be used multiple times in an XS
  998. module to enable and disable prototypes for different parts of the module.
  999.  
  1000. To enable prototypes:
  1001.  
  1002.     PROTOTYPES: ENABLE
  1003.  
  1004. To disable prototypes:
  1005.  
  1006.     PROTOTYPES: DISABLE
  1007.  
  1008. =head2 The PROTOTYPE: Keyword
  1009.  
  1010. This keyword is similar to the PROTOTYPES: keyword above but can be used to
  1011. force B<xsubpp> to use a specific prototype for the XSUB.  This keyword
  1012. overrides all other prototype options and keywords but affects only the
  1013. current XSUB.  Consult L<perlsub/Prototypes> for information about Perl
  1014. prototypes.
  1015.  
  1016.     bool_t
  1017.     rpcb_gettime(timep, ...)
  1018.           time_t timep = NO_INIT
  1019.     PROTOTYPE: $;$
  1020.     PREINIT:
  1021.           char *host = "localhost";
  1022.       STRLEN n_a;
  1023.         CODE:
  1024.           if( items > 1 )
  1025.                host = (char *)SvPV(ST(1), n_a);
  1026.           RETVAL = rpcb_gettime( host, &timep );
  1027.         OUTPUT:
  1028.           timep
  1029.           RETVAL
  1030.  
  1031. =head2 The ALIAS: Keyword
  1032.  
  1033. The ALIAS: keyword allows an XSUB to have two or more unique Perl names
  1034. and to know which of those names was used when it was invoked.  The Perl
  1035. names may be fully-qualified with package names.  Each alias is given an
  1036. index.  The compiler will setup a variable called C<ix> which contain the
  1037. index of the alias which was used.  When the XSUB is called with its
  1038. declared name C<ix> will be 0.
  1039.  
  1040. The following example will create aliases C<FOO::gettime()> and
  1041. C<BAR::getit()> for this function.
  1042.  
  1043.     bool_t
  1044.     rpcb_gettime(host,timep)
  1045.           char *host
  1046.           time_t &timep
  1047.     ALIAS:
  1048.         FOO::gettime = 1
  1049.         BAR::getit = 2
  1050.     INIT:
  1051.       printf("# ix = %d\n", ix );
  1052.         OUTPUT:
  1053.           timep
  1054.  
  1055. =head2 The INTERFACE: Keyword
  1056.  
  1057. This keyword declares the current XSUB as a keeper of the given
  1058. calling signature.  If some text follows this keyword, it is
  1059. considered as a list of functions which have this signature, and
  1060. should be attached to the current XSUB.
  1061.  
  1062. For example, if you have 4 C functions multiply(), divide(), add(),
  1063. subtract() all having the signature:
  1064.  
  1065.     symbolic f(symbolic, symbolic);
  1066.  
  1067. you can make them all to use the same XSUB using this:
  1068.  
  1069.     symbolic
  1070.     interface_s_ss(arg1, arg2)  
  1071.     symbolic    arg1
  1072.     symbolic    arg2
  1073.     INTERFACE:
  1074.     multiply divide 
  1075.     add subtract
  1076.  
  1077. (This is the complete XSUB code for 4 Perl functions!)  Four generated
  1078. Perl function share names with corresponding C functions.
  1079.  
  1080. The advantage of this approach comparing to ALIAS: keyword is that there
  1081. is no need to code a switch statement, each Perl function (which shares
  1082. the same XSUB) knows which C function it should call.  Additionally, one
  1083. can attach an extra function remainder() at runtime by using
  1084.  
  1085.     CV *mycv = newXSproto("Symbolic::remainder", 
  1086.               XS_Symbolic_interface_s_ss, __FILE__, "$$");
  1087.     XSINTERFACE_FUNC_SET(mycv, remainder);
  1088.  
  1089. say, from another XSUB.  (This example supposes that there was no
  1090. INTERFACE_MACRO: section, otherwise one needs to use something else instead of
  1091. C<XSINTERFACE_FUNC_SET>, see the next section.)
  1092.  
  1093. =head2 The INTERFACE_MACRO: Keyword
  1094.  
  1095. This keyword allows one to define an INTERFACE using a different way
  1096. to extract a function pointer from an XSUB.  The text which follows
  1097. this keyword should give the name of macros which would extract/set a
  1098. function pointer.  The extractor macro is given return type, C<CV*>,
  1099. and C<XSANY.any_dptr> for this C<CV*>.  The setter macro is given cv,
  1100. and the function pointer.
  1101.  
  1102. The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
  1103. An INTERFACE keyword with an empty list of functions can be omitted if
  1104. INTERFACE_MACRO keyword is used.
  1105.  
  1106. Suppose that in the previous example functions pointers for 
  1107. multiply(), divide(), add(), subtract() are kept in a global C array
  1108. C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
  1109. C<subtract_off>.  Then one can use 
  1110.  
  1111.     #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
  1112.     ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
  1113.     #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
  1114.     CvXSUBANY(cv).any_i32 = CAT2( f, _off )
  1115.  
  1116. in C section,
  1117.  
  1118.     symbolic
  1119.     interface_s_ss(arg1, arg2)  
  1120.     symbolic    arg1
  1121.     symbolic    arg2
  1122.       INTERFACE_MACRO: 
  1123.     XSINTERFACE_FUNC_BYOFFSET
  1124.     XSINTERFACE_FUNC_BYOFFSET_set
  1125.       INTERFACE:
  1126.     multiply divide 
  1127.     add subtract
  1128.  
  1129. in XSUB section.
  1130.  
  1131. =head2 The INCLUDE: Keyword
  1132.  
  1133. This keyword can be used to pull other files into the XS module.  The other
  1134. files may have XS code.  INCLUDE: can also be used to run a command to
  1135. generate the XS code to be pulled into the module.
  1136.  
  1137. The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
  1138.  
  1139.     bool_t
  1140.     rpcb_gettime(host,timep)
  1141.           char *host
  1142.           time_t &timep
  1143.         OUTPUT:
  1144.           timep
  1145.  
  1146. The XS module can use INCLUDE: to pull that file into it.
  1147.  
  1148.     INCLUDE: Rpcb1.xsh
  1149.  
  1150. If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
  1151. the compiler will interpret the parameters as a command.
  1152.  
  1153.     INCLUDE: cat Rpcb1.xsh |
  1154.  
  1155. =head2 The CASE: Keyword
  1156.  
  1157. The CASE: keyword allows an XSUB to have multiple distinct parts with each
  1158. part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
  1159. other XS keywords must be contained within a CASE:.  This means nothing may
  1160. precede the first CASE: in the XSUB and anything following the last CASE: is
  1161. included in that case.
  1162.  
  1163. A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
  1164. variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
  1165. (see L<"Variable-length Parameter Lists">).  The last CASE: becomes the
  1166. B<default> case if it is not associated with a conditional.  The following
  1167. example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
  1168. having an alias C<x_gettime()>.  When the function is called as
  1169. C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
  1170. but when the function is called as C<x_gettime()> its parameters are
  1171. reversed, C<(time_t *timep, char *host)>.
  1172.  
  1173.     long
  1174.     rpcb_gettime(a,b)
  1175.       CASE: ix == 1
  1176.     ALIAS:
  1177.       x_gettime = 1
  1178.     INPUT:
  1179.       # 'a' is timep, 'b' is host
  1180.           char *b
  1181.           time_t a = NO_INIT
  1182.         CODE:
  1183.                RETVAL = rpcb_gettime( b, &a );
  1184.         OUTPUT:
  1185.           a
  1186.           RETVAL
  1187.       CASE:
  1188.       # 'a' is host, 'b' is timep
  1189.           char *a
  1190.           time_t &b = NO_INIT
  1191.         OUTPUT:
  1192.           b
  1193.           RETVAL
  1194.  
  1195. That function can be called with either of the following statements.  Note
  1196. the different argument lists.
  1197.  
  1198.     $status = rpcb_gettime( $host, $timep );
  1199.  
  1200.     $status = x_gettime( $timep, $host );
  1201.  
  1202. =head2 The & Unary Operator
  1203.  
  1204. The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
  1205. that it should convert a Perl value to/from C using the C type to the left
  1206. of C<&>, but provide a pointer to this value when the C function is called.
  1207.  
  1208. This is useful to avoid a CODE: block for a C function which takes a parameter
  1209. by reference.  Typically, the parameter should be not a pointer type (an
  1210. C<int> or C<long> but not a C<int*> or C<long*>).
  1211.  
  1212. The following XSUB will generate incorrect C code.  The B<xsubpp> compiler will
  1213. turn this into code which calls C<rpcb_gettime()> with parameters C<(char
  1214. *host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
  1215. parameter to be of type C<time_t*> rather than C<time_t>.
  1216.  
  1217.     bool_t
  1218.     rpcb_gettime(host,timep)
  1219.           char *host
  1220.           time_t timep
  1221.         OUTPUT:
  1222.           timep
  1223.  
  1224. That problem is corrected by using the C<&> operator.  The B<xsubpp> compiler
  1225. will now turn this into code which calls C<rpcb_gettime()> correctly with
  1226. parameters C<(char *host, time_t *timep)>.  It does this by carrying the
  1227. C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
  1228.  
  1229.     bool_t
  1230.     rpcb_gettime(host,timep)
  1231.           char *host
  1232.           time_t &timep
  1233.         OUTPUT:
  1234.           timep
  1235.  
  1236. =head2 Inserting Comments and C Preprocessor Directives
  1237.  
  1238. C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
  1239. CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
  1240. Comments are allowed anywhere after the MODULE keyword.  The compiler
  1241. will pass the preprocessor directives through untouched and will remove
  1242. the commented lines.
  1243.  
  1244. Comments can be added to XSUBs by placing a C<#> as the first
  1245. non-whitespace of a line.  Care should be taken to avoid making the
  1246. comment look like a C preprocessor directive, lest it be interpreted as
  1247. such.  The simplest way to prevent this is to put whitespace in front of
  1248. the C<#>.
  1249.  
  1250. If you use preprocessor directives to choose one of two
  1251. versions of a function, use
  1252.  
  1253.     #if ... version1
  1254.     #else /* ... version2  */
  1255.     #endif
  1256.  
  1257. and not
  1258.  
  1259.     #if ... version1
  1260.     #endif
  1261.     #if ... version2
  1262.     #endif
  1263.  
  1264. because otherwise B<xsubpp> will believe that you made a duplicate
  1265. definition of the function.  Also, put a blank line before the
  1266. #else/#endif so it will not be seen as part of the function body.
  1267.  
  1268. =head2 Using XS With C++
  1269.  
  1270. If an XSUB name contains C<::>, it is considered to be a C++ method.
  1271. The generated Perl function will assume that
  1272. its first argument is an object pointer.  The object pointer
  1273. will be stored in a variable called THIS.  The object should
  1274. have been created by C++ with the new() function and should
  1275. be blessed by Perl with the sv_setref_pv() macro.  The
  1276. blessing of the object by Perl can be handled by a typemap.  An example
  1277. typemap is shown at the end of this section.
  1278.  
  1279. If the return type of the XSUB includes C<static>, the method is considered
  1280. to be a static method.  It will call the C++
  1281. function using the class::method() syntax.  If the method is not static
  1282. the function will be called using the THIS-E<gt>method() syntax.
  1283.  
  1284. The next examples will use the following C++ class.
  1285.  
  1286.      class color {
  1287.           public:
  1288.           color();
  1289.           ~color();
  1290.           int blue();
  1291.           void set_blue( int );
  1292.  
  1293.           private:
  1294.           int c_blue;
  1295.      };
  1296.  
  1297. The XSUBs for the blue() and set_blue() methods are defined with the class
  1298. name but the parameter for the object (THIS, or "self") is implicit and is
  1299. not listed.
  1300.  
  1301.      int
  1302.      color::blue()
  1303.  
  1304.      void
  1305.      color::set_blue( val )
  1306.           int val
  1307.  
  1308. Both Perl functions will expect an object as the first parameter.  In the 
  1309. generated C++ code the object is called C<THIS>, and the method call will
  1310. be performed on this object.  So in the C++ code the blue() and set_blue()
  1311. methods will be called as this:
  1312.  
  1313.      RETVAL = THIS->blue();
  1314.  
  1315.      THIS->set_blue( val );
  1316.  
  1317. You could also write a single get/set method using an optional argument:
  1318.  
  1319.      int
  1320.      color::blue( val = NO_INIT )
  1321.          int val
  1322.          PROTOTYPE $;$
  1323.          CODE:
  1324.              if (items > 1)
  1325.                  THIS->set_blue( val );
  1326.              RETVAL = THIS->blue();
  1327.          OUTPUT:
  1328.              RETVAL
  1329.  
  1330. If the function's name is B<DESTROY> then the C++ C<delete> function will be
  1331. called and C<THIS> will be given as its parameter.  The generated C++ code for
  1332.  
  1333.      void
  1334.      color::DESTROY()
  1335.  
  1336. will look like this:
  1337.  
  1338.      color *THIS = ...;    // Initialized as in typemap
  1339.  
  1340.      delete THIS;
  1341.  
  1342. If the function's name is B<new> then the C++ C<new> function will be called
  1343. to create a dynamic C++ object.  The XSUB will expect the class name, which
  1344. will be kept in a variable called C<CLASS>, to be given as the first
  1345. argument.
  1346.  
  1347.      color *
  1348.      color::new()
  1349.  
  1350. The generated C++ code will call C<new>.
  1351.  
  1352.      RETVAL = new color();
  1353.  
  1354. The following is an example of a typemap that could be used for this C++
  1355. example.
  1356.  
  1357.     TYPEMAP
  1358.     color *        O_OBJECT
  1359.  
  1360.     OUTPUT
  1361.     # The Perl object is blessed into 'CLASS', which should be a
  1362.     # char* having the name of the package for the blessing.
  1363.     O_OBJECT
  1364.         sv_setref_pv( $arg, CLASS, (void*)$var );
  1365.  
  1366.     INPUT
  1367.     O_OBJECT
  1368.         if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
  1369.             $var = ($type)SvIV((SV*)SvRV( $arg ));
  1370.         else{
  1371.             warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
  1372.             XSRETURN_UNDEF;
  1373.         }
  1374.  
  1375. =head2 Interface Strategy
  1376.  
  1377. When designing an interface between Perl and a C library a straight
  1378. translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
  1379. However, sometimes the interface will look
  1380. very C-like and occasionally nonintuitive, especially when the C function
  1381. modifies one of its parameters, or returns failure inband (as in "negative
  1382. return values mean failure").  In cases where the programmer wishes to
  1383. create a more Perl-like interface the following strategy may help to
  1384. identify the more critical parts of the interface.
  1385.  
  1386. Identify the C functions with input/output or output parameters.  The XSUBs for
  1387. these functions may be able to return lists to Perl.
  1388.  
  1389. Identify the C functions which use some inband info as an indication
  1390. of failure.  They may be
  1391. candidates to return undef or an empty list in case of failure.  If the
  1392. failure may be detected without a call to the C function, you may want to use
  1393. an INIT: section to report the failure.  For failures detectable after the C
  1394. function returns one may want to use a CLEANUP: section to process the
  1395. failure.  In more complicated cases use CODE: or PPCODE: sections.
  1396.  
  1397. If many functions use the same failure indication based on the return value,
  1398. you may want to create a special typedef to handle this situation.  Put
  1399.  
  1400.   typedef int negative_is_failure;
  1401.  
  1402. near the beginning of XS file, and create an OUTPUT typemap entry
  1403. for C<negative_is_failure> which converts negative values to C<undef>, or
  1404. maybe croak()s.  After this the return value of type C<negative_is_failure>
  1405. will create more Perl-like interface.
  1406.  
  1407. Identify which values are used by only the C and XSUB functions
  1408. themselves, say, when a parameter to a function should be a contents of a
  1409. global variable.  If Perl does not need to access the contents of the value
  1410. then it may not be necessary to provide a translation for that value
  1411. from C to Perl.
  1412.  
  1413. Identify the pointers in the C function parameter lists and return
  1414. values.  Some pointers may be used to implement input/output or
  1415. output parameters, they can be handled in XS with the C<&> unary operator,
  1416. and, possibly, using the NO_INIT keyword.
  1417. Some others will require handling of types like C<int *>, and one needs
  1418. to decide what a useful Perl translation will do in such a case.  When
  1419. the semantic is clear, it is advisable to put the translation into a typemap
  1420. file.
  1421.  
  1422. Identify the structures used by the C functions.  In many
  1423. cases it may be helpful to use the T_PTROBJ typemap for
  1424. these structures so they can be manipulated by Perl as
  1425. blessed objects.  (This is handled automatically by C<h2xs -x>.)
  1426.  
  1427. If the same C type is used in several different contexts which require
  1428. different translations, C<typedef> several new types mapped to this C type,
  1429. and create separate F<typemap> entries for these new types.  Use these
  1430. types in declarations of return type and parameters to XSUBs.
  1431.  
  1432. =head2 Perl Objects And C Structures
  1433.  
  1434. When dealing with C structures one should select either
  1435. B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
  1436. designed to handle pointers to complex objects.  The
  1437. T_PTRREF type will allow the Perl object to be unblessed
  1438. while the T_PTROBJ type requires that the object be blessed.
  1439. By using T_PTROBJ one can achieve a form of type-checking
  1440. because the XSUB will attempt to verify that the Perl object
  1441. is of the expected type.
  1442.  
  1443. The following XS code shows the getnetconfigent() function which is used
  1444. with ONC+ TIRPC.  The getnetconfigent() function will return a pointer to a
  1445. C structure and has the C prototype shown below.  The example will
  1446. demonstrate how the C pointer will become a Perl reference.  Perl will
  1447. consider this reference to be a pointer to a blessed object and will
  1448. attempt to call a destructor for the object.  A destructor will be
  1449. provided in the XS source to free the memory used by getnetconfigent().
  1450. Destructors in XS can be created by specifying an XSUB function whose name
  1451. ends with the word B<DESTROY>.  XS destructors can be used to free memory
  1452. which may have been malloc'd by another XSUB.
  1453.  
  1454.      struct netconfig *getnetconfigent(const char *netid);
  1455.  
  1456. A C<typedef> will be created for C<struct netconfig>.  The Perl
  1457. object will be blessed in a class matching the name of the C
  1458. type, with the tag C<Ptr> appended, and the name should not
  1459. have embedded spaces if it will be a Perl package name.  The
  1460. destructor will be placed in a class corresponding to the
  1461. class of the object and the PREFIX keyword will be used to
  1462. trim the name to the word DESTROY as Perl will expect.
  1463.  
  1464.      typedef struct netconfig Netconfig;
  1465.  
  1466.      MODULE = RPC  PACKAGE = RPC
  1467.  
  1468.      Netconfig *
  1469.      getnetconfigent(netid)
  1470.           char *netid
  1471.  
  1472.      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
  1473.  
  1474.      void
  1475.      rpcb_DESTROY(netconf)
  1476.           Netconfig *netconf
  1477.         CODE:
  1478.           printf("Now in NetconfigPtr::DESTROY\n");
  1479.           free( netconf );
  1480.  
  1481. This example requires the following typemap entry.  Consult the typemap
  1482. section for more information about adding new typemaps for an extension.
  1483.  
  1484.      TYPEMAP
  1485.      Netconfig *  T_PTROBJ
  1486.  
  1487. This example will be used with the following Perl statements.
  1488.  
  1489.      use RPC;
  1490.      $netconf = getnetconfigent("udp");
  1491.  
  1492. When Perl destroys the object referenced by $netconf it will send the
  1493. object to the supplied XSUB DESTROY function.  Perl cannot determine, and
  1494. does not care, that this object is a C struct and not a Perl object.  In
  1495. this sense, there is no difference between the object created by the
  1496. getnetconfigent() XSUB and an object created by a normal Perl subroutine.
  1497.  
  1498. =head2 The Typemap
  1499.  
  1500. The typemap is a collection of code fragments which are used by the B<xsubpp>
  1501. compiler to map C function parameters and values to Perl values.  The
  1502. typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
  1503. C<OUTPUT>.  An unlabelled initial section is assumed to be a C<TYPEMAP>
  1504. section.  The INPUT section tells
  1505. the compiler how to translate Perl values
  1506. into variables of certain C types.  The OUTPUT section tells the compiler
  1507. how to translate the values from certain C types into values Perl can
  1508. understand.  The TYPEMAP section tells the compiler which of the INPUT and
  1509. OUTPUT code fragments should be used to map a given C type to a Perl value.
  1510. The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
  1511. in the first column on a line by themselves, and must be in uppercase.
  1512.  
  1513. The default typemap in the C<ext> directory of the Perl source contains many
  1514. useful types which can be used by Perl extensions.  Some extensions define
  1515. additional typemaps which they keep in their own directory.  These
  1516. additional typemaps may reference INPUT and OUTPUT maps in the main
  1517. typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
  1518. override any mappings which are in the default typemap.
  1519.  
  1520. Most extensions which require a custom typemap will need only the TYPEMAP
  1521. section of the typemap file.  The custom typemap used in the
  1522. getnetconfigent() example shown earlier demonstrates what may be the typical
  1523. use of extension typemaps.  That typemap is used to equate a C structure
  1524. with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
  1525. here.  Note that the C type is separated from the XS type with a tab and
  1526. that the C unary operator C<*> is considered to be a part of the C type name.
  1527.  
  1528.     TYPEMAP
  1529.     Netconfig *<tab>T_PTROBJ
  1530.  
  1531. Here's a more complicated example: suppose that you wanted C<struct
  1532. netconfig> to be blessed into the class C<Net::Config>.  One way to do
  1533. this is to use underscores (_) to separate package names, as follows:
  1534.  
  1535.         typedef struct netconfig * Net_Config;
  1536.  
  1537. And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
  1538. double-colons (::), and declare C<Net_Config> to be of that type:
  1539.  
  1540.  
  1541.         TYPEMAP
  1542.         Net_Config      T_PTROBJ_SPECIAL
  1543.  
  1544.         INPUT
  1545.         T_PTROBJ_SPECIAL
  1546.                 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
  1547.                         IV tmp = SvIV((SV*)SvRV($arg));
  1548.                 $var = ($type) tmp;
  1549.                 }
  1550.                 else
  1551.                         croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
  1552.  
  1553.         OUTPUT
  1554.         T_PTROBJ_SPECIAL
  1555.                 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
  1556.                 (void*)$var);
  1557.  
  1558. The INPUT and OUTPUT sections substitute underscores for double-colons
  1559. on the fly, giving the desired effect.  This example demonstrates some
  1560. of the power and versatility of the typemap facility.
  1561.  
  1562. =head1 EXAMPLES
  1563.  
  1564. File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
  1565.  
  1566.      #include "EXTERN.h"
  1567.      #include "perl.h"
  1568.      #include "XSUB.h"
  1569.  
  1570.      #include <rpc/rpc.h>
  1571.  
  1572.      typedef struct netconfig Netconfig;
  1573.  
  1574.      MODULE = RPC  PACKAGE = RPC
  1575.  
  1576.      SV *
  1577.      rpcb_gettime(host="localhost")
  1578.           char *host
  1579.     PREINIT:
  1580.           time_t  timep;
  1581.         CODE:
  1582.           ST(0) = sv_newmortal();
  1583.           if( rpcb_gettime( host, &timep ) )
  1584.                sv_setnv( ST(0), (double)timep );
  1585.  
  1586.      Netconfig *
  1587.      getnetconfigent(netid="udp")
  1588.           char *netid
  1589.  
  1590.      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
  1591.  
  1592.      void
  1593.      rpcb_DESTROY(netconf)
  1594.           Netconfig *netconf
  1595.         CODE:
  1596.           printf("NetconfigPtr::DESTROY\n");
  1597.           free( netconf );
  1598.  
  1599. File C<typemap>: Custom typemap for RPC.xs.
  1600.  
  1601.      TYPEMAP
  1602.      Netconfig *  T_PTROBJ
  1603.  
  1604. File C<RPC.pm>: Perl module for the RPC extension.
  1605.  
  1606.      package RPC;
  1607.  
  1608.      require Exporter;
  1609.      require DynaLoader;
  1610.      @ISA = qw(Exporter DynaLoader);
  1611.      @EXPORT = qw(rpcb_gettime getnetconfigent);
  1612.  
  1613.      bootstrap RPC;
  1614.      1;
  1615.  
  1616. File C<rpctest.pl>: Perl test program for the RPC extension.
  1617.  
  1618.      use RPC;
  1619.  
  1620.      $netconf = getnetconfigent();
  1621.      $a = rpcb_gettime();
  1622.      print "time = $a\n";
  1623.      print "netconf = $netconf\n";
  1624.  
  1625.      $netconf = getnetconfigent("tcp");
  1626.      $a = rpcb_gettime("poplar");
  1627.      print "time = $a\n";
  1628.      print "netconf = $netconf\n";
  1629.  
  1630.  
  1631. =head1 XS VERSION
  1632.  
  1633. This document covers features supported by C<xsubpp> 1.935.
  1634.  
  1635. =head1 AUTHOR
  1636.  
  1637. Originally written by Dean Roehrich <F<roehrich@cray.com>>.
  1638.  
  1639. Maintained since 1996 by The Perl Porters <F<perlbug@perl.com>>.
  1640.