[Summary view] [Print] [Text view]

   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.  B<xsubpp> recognizes and
  70  skips POD (see L<perlpod>) in both the C and XS language sections, which
  71  allows the XS file to contain embedded documentation. 
  72  
  73  See L<perlxstut> for a tutorial on the whole extension creation process.
  74  
  75  Note: For some extensions, Dave Beazley's SWIG system may provide a
  76  significantly more convenient mechanism for creating the extension
  77  glue code.  See http://www.swig.org/ for more information.
  78  
  79  =head2 On The Road
  80  
  81  Many of the examples which follow will concentrate on creating an interface
  82  between Perl and the ONC+ RPC bind library functions.  The rpcb_gettime()
  83  function is used to demonstrate many features of the XS language.  This
  84  function has two parameters; the first is an input parameter and the second
  85  is an output parameter.  The function also returns a status value.
  86  
  87      bool_t rpcb_gettime(const char *host, time_t *timep);
  88  
  89  From C this function will be called with the following
  90  statements.
  91  
  92       #include <rpc/rpc.h>
  93       bool_t status;
  94       time_t timep;
  95       status = rpcb_gettime( "localhost", &timep );
  96  
  97  If an XSUB is created to offer a direct translation between this function
  98  and Perl, then this XSUB will be used from Perl with the following code.
  99  The $status and $timep variables will contain the output of the function.
 100  
 101       use RPC;
 102       $status = rpcb_gettime( "localhost", $timep );
 103  
 104  The following XS file shows an XS subroutine, or XSUB, which
 105  demonstrates one possible interface to the rpcb_gettime()
 106  function.  This XSUB represents a direct translation between
 107  C and Perl and so preserves the interface even from Perl.
 108  This XSUB will be invoked from Perl with the usage shown
 109  above.  Note that the first three #include statements, for
 110  C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
 111  beginning of an XS file.  This approach and others will be
 112  expanded later in this document.
 113  
 114       #include "EXTERN.h"
 115       #include "perl.h"
 116       #include "XSUB.h"
 117       #include <rpc/rpc.h>
 118  
 119       MODULE = RPC  PACKAGE = RPC
 120  
 121       bool_t
 122       rpcb_gettime(host,timep)
 123            char *host
 124            time_t &timep
 125          OUTPUT:
 126            timep
 127  
 128  Any extension to Perl, including those containing XSUBs,
 129  should have a Perl module to serve as the bootstrap which
 130  pulls the extension into Perl.  This module will export the
 131  extension's functions and variables to the Perl program and
 132  will cause the extension's XSUBs to be linked into Perl.
 133  The following module will be used for most of the examples
 134  in this document and should be used from Perl with the C<use>
 135  command as shown earlier.  Perl modules are explained in
 136  more detail later in this document.
 137  
 138       package RPC;
 139  
 140       require Exporter;
 141       require DynaLoader;
 142       @ISA = qw(Exporter DynaLoader);
 143       @EXPORT = qw( rpcb_gettime );
 144  
 145       bootstrap RPC;
 146       1;
 147  
 148  Throughout this document a variety of interfaces to the rpcb_gettime()
 149  XSUB will be explored.  The XSUBs will take their parameters in different
 150  orders or will take different numbers of parameters.  In each case the
 151  XSUB is an abstraction between Perl and the real C rpcb_gettime()
 152  function, and the XSUB must always ensure that the real rpcb_gettime()
 153  function is called with the correct parameters.  This abstraction will
 154  allow the programmer to create a more Perl-like interface to the C
 155  function.
 156  
 157  =head2 The Anatomy of an XSUB
 158  
 159  The simplest XSUBs consist of 3 parts: a description of the return
 160  value, the name of the XSUB routine and the names of its arguments,
 161  and a description of types or formats of the arguments.
 162  
 163  The following XSUB allows a Perl program to access a C library function
 164  called sin().  The XSUB will imitate the C function which takes a single
 165  argument and returns a single value.
 166  
 167       double
 168       sin(x)
 169         double x
 170  
 171  Optionally, one can merge the description of types and the list of
 172  argument names, rewriting this as
 173  
 174       double
 175       sin(double x)
 176  
 177  This makes this XSUB look similar to an ANSI C declaration.  An optional
 178  semicolon is allowed after the argument list, as in
 179  
 180       double
 181       sin(double x);
 182  
 183  Parameters with C pointer types can have different semantic: C functions
 184  with similar declarations
 185  
 186       bool string_looks_as_a_number(char *s);
 187       bool make_char_uppercase(char *c);
 188  
 189  are used in absolutely incompatible manner.  Parameters to these functions
 190  could be described B<xsubpp> like this:
 191  
 192       char *  s
 193       char    &c
 194  
 195  Both these XS declarations correspond to the C<char*> C type, but they have
 196  different semantics, see L<"The & Unary Operator">.
 197  
 198  It is convenient to think that the indirection operator
 199  C<*> should be considered as a part of the type and the address operator C<&>
 200  should be considered part of the variable.  See L<"The Typemap">
 201  for more info about handling qualifiers and unary operators in C types.
 202  
 203  The function name and the return type must be placed on
 204  separate lines and should be flush left-adjusted.
 205  
 206    INCORRECT                        CORRECT
 207  
 208    double sin(x)                    double
 209      double x                       sin(x)
 210                       double x
 211  
 212  The rest of the function description may be indented or left-adjusted. The
 213  following example shows a function with its body left-adjusted.  Most
 214  examples in this document will indent the body for better readability.
 215  
 216    CORRECT
 217  
 218    double
 219    sin(x)
 220    double x
 221  
 222  More complicated XSUBs may contain many other sections.  Each section of
 223  an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
 224  However, the first two lines of an XSUB always contain the same data:
 225  descriptions of the return type and the names of the function and its
 226  parameters.  Whatever immediately follows these is considered to be
 227  an INPUT: section unless explicitly marked with another keyword.
 228  (See L<The INPUT: Keyword>.)
 229  
 230  An XSUB section continues until another section-start keyword is found.
 231  
 232  =head2 The Argument Stack
 233  
 234  The Perl argument stack is used to store the values which are
 235  sent as parameters to the XSUB and to store the XSUB's
 236  return value(s).  In reality all Perl functions (including non-XSUB
 237  ones) keep their values on this stack all the same time, each limited
 238  to its own range of positions on the stack.  In this document the
 239  first position on that stack which belongs to the active
 240  function will be referred to as position 0 for that function.
 241  
 242  XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
 243  refers to a position in this XSUB's part of the stack.  Position 0 for that
 244  function would be known to the XSUB as ST(0).  The XSUB's incoming
 245  parameters and outgoing return values always begin at ST(0).  For many
 246  simple cases the B<xsubpp> compiler will generate the code necessary to
 247  handle the argument stack by embedding code fragments found in the
 248  typemaps.  In more complex cases the programmer must supply the code.
 249  
 250  =head2 The RETVAL Variable
 251  
 252  The RETVAL variable is a special C variable that is declared automatically
 253  for you.  The C type of RETVAL matches the return type of the C library
 254  function.  The B<xsubpp> compiler will declare this variable in each XSUB
 255  with non-C<void> return type.  By default the generated C function
 256  will use RETVAL to hold the return value of the C library function being
 257  called.  In simple cases the value of RETVAL will be placed in ST(0) of
 258  the argument stack where it can be received by Perl as the return value
 259  of the XSUB.
 260  
 261  If the XSUB has a return type of C<void> then the compiler will
 262  not declare a RETVAL variable for that function.  When using
 263  a PPCODE: section no manipulation of the RETVAL variable is required, the
 264  section may use direct stack manipulation to place output values on the stack.
 265  
 266  If PPCODE: directive is not used, C<void> return value should be used
 267  only for subroutines which do not return a value, I<even if> CODE:
 268  directive is used which sets ST(0) explicitly.
 269  
 270  Older versions of this document recommended to use C<void> return
 271  value in such cases. It was discovered that this could lead to
 272  segfaults in cases when XSUB was I<truly> C<void>. This practice is
 273  now deprecated, and may be not supported at some future version. Use
 274  the return value C<SV *> in such cases. (Currently C<xsubpp> contains
 275  some heuristic code which tries to disambiguate between "truly-void"
 276  and "old-practice-declared-as-void" functions. Hence your code is at
 277  mercy of this heuristics unless you use C<SV *> as return value.)
 278  
 279  =head2 Returning SVs, AVs and HVs through RETVAL
 280  
 281  When you're using RETVAL to return an C<SV *>, there's some magic
 282  going on behind the scenes that should be mentioned. When you're
 283  manipulating the argument stack using the ST(x) macro, for example,
 284  you usually have to pay special attention to reference counts. (For
 285  more about reference counts, see L<perlguts>.) To make your life
 286  easier, the typemap file automatically makes C<RETVAL> mortal when
 287  you're returning an C<SV *>. Thus, the following two XSUBs are more
 288  or less equivalent:
 289  
 290    void
 291    alpha()
 292        PPCODE:
 293            ST(0) = newSVpv("Hello World",0);
 294            sv_2mortal(ST(0));
 295            XSRETURN(1);
 296    
 297    SV *
 298    beta()
 299        CODE:
 300            RETVAL = newSVpv("Hello World",0);
 301        OUTPUT:
 302            RETVAL
 303  
 304  This is quite useful as it usually improves readability. While
 305  this works fine for an C<SV *>, it's unfortunately not as easy
 306  to have C<AV *> or C<HV *> as a return value. You I<should> be
 307  able to write:
 308  
 309    AV *
 310    array()
 311        CODE:
 312            RETVAL = newAV();
 313            /* do something with RETVAL */
 314        OUTPUT:
 315            RETVAL
 316  
 317  But due to an unfixable bug (fixing it would break lots of existing
 318  CPAN modules) in the typemap file, the reference count of the C<AV *>
 319  is not properly decremented. Thus, the above XSUB would leak memory
 320  whenever it is being called. The same problem exists for C<HV *>.
 321  
 322  When you're returning an C<AV *> or a C<HV *>, you have make sure
 323  their reference count is decremented by making the AV or HV mortal:
 324  
 325    AV *
 326    array()
 327        CODE:
 328            RETVAL = newAV();
 329            sv_2mortal((SV*)RETVAL);
 330            /* do something with RETVAL */
 331        OUTPUT:
 332            RETVAL
 333  
 334  And also remember that you don't have to do this for an C<SV *>.
 335  
 336  =head2 The MODULE Keyword
 337  
 338  The MODULE keyword is used to start the XS code and to specify the package
 339  of the functions which are being defined.  All text preceding the first
 340  MODULE keyword is considered C code and is passed through to the output with
 341  POD stripped, but otherwise untouched.  Every XS module will have a
 342  bootstrap function which is used to hook the XSUBs into Perl.  The package
 343  name of this bootstrap function will match the value of the last MODULE
 344  statement in the XS source files.  The value of MODULE should always remain
 345  constant within the same XS file, though this is not required.
 346  
 347  The following example will start the XS code and will place
 348  all functions in a package named RPC.
 349  
 350       MODULE = RPC
 351  
 352  =head2 The PACKAGE Keyword
 353  
 354  When functions within an XS source file must be separated into packages
 355  the PACKAGE keyword should be used.  This keyword is used with the MODULE
 356  keyword and must follow immediately after it when used.
 357  
 358       MODULE = RPC  PACKAGE = RPC
 359  
 360       [ XS code in package RPC ]
 361  
 362       MODULE = RPC  PACKAGE = RPCB
 363  
 364       [ XS code in package RPCB ]
 365  
 366       MODULE = RPC  PACKAGE = RPC
 367  
 368       [ XS code in package RPC ]
 369  
 370  The same package name can be used more than once, allowing for
 371  non-contiguous code. This is useful if you have a stronger ordering
 372  principle than package names.
 373  
 374  Although this keyword is optional and in some cases provides redundant
 375  information it should always be used.  This keyword will ensure that the
 376  XSUBs appear in the desired package.
 377  
 378  =head2 The PREFIX Keyword
 379  
 380  The PREFIX keyword designates prefixes which should be
 381  removed from the Perl function names.  If the C function is
 382  C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
 383  see this function as C<gettime()>.
 384  
 385  This keyword should follow the PACKAGE keyword when used.
 386  If PACKAGE is not used then PREFIX should follow the MODULE
 387  keyword.
 388  
 389       MODULE = RPC  PREFIX = rpc_
 390  
 391       MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
 392  
 393  =head2 The OUTPUT: Keyword
 394  
 395  The OUTPUT: keyword indicates that certain function parameters should be
 396  updated (new values made visible to Perl) when the XSUB terminates or that
 397  certain values should be returned to the calling Perl function.  For
 398  simple functions which have no CODE: or PPCODE: section,
 399  such as the sin() function above, the RETVAL variable is
 400  automatically designated as an output value.  For more complex functions
 401  the B<xsubpp> compiler will need help to determine which variables are output
 402  variables.
 403  
 404  This keyword will normally be used to complement the CODE:  keyword.
 405  The RETVAL variable is not recognized as an output variable when the
 406  CODE: keyword is present.  The OUTPUT:  keyword is used in this
 407  situation to tell the compiler that RETVAL really is an output
 408  variable.
 409  
 410  The OUTPUT: keyword can also be used to indicate that function parameters
 411  are output variables.  This may be necessary when a parameter has been
 412  modified within the function and the programmer would like the update to
 413  be seen by Perl.
 414  
 415       bool_t
 416       rpcb_gettime(host,timep)
 417            char *host
 418            time_t &timep
 419          OUTPUT:
 420            timep
 421  
 422  The OUTPUT: keyword will also allow an output parameter to
 423  be mapped to a matching piece of code rather than to a
 424  typemap.
 425  
 426       bool_t
 427       rpcb_gettime(host,timep)
 428            char *host
 429            time_t &timep
 430          OUTPUT:
 431            timep sv_setnv(ST(1), (double)timep);
 432  
 433  B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
 434  OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
 435  behavior, as it takes care of properly invoking 'set' magic on output
 436  parameters (needed for hash or array element parameters that must be
 437  created if they didn't exist).  If for some reason, this behavior is
 438  not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
 439  to disable it for the remainder of the parameters in the OUTPUT section.
 440  Likewise,  C<SETMAGIC: ENABLE> can be used to reenable it for the
 441  remainder of the OUTPUT section.  See L<perlguts> for more details
 442  about 'set' magic.
 443  
 444  =head2 The NO_OUTPUT Keyword
 445  
 446  The NO_OUTPUT can be placed as the first token of the XSUB.  This keyword
 447  indicates that while the C subroutine we provide an interface to has
 448  a non-C<void> return type, the return value of this C subroutine should not
 449  be returned from the generated Perl subroutine.
 450  
 451  With this keyword present L<The RETVAL Variable> is created, and in the
 452  generated call to the subroutine this variable is assigned to, but the value
 453  of this variable is not going to be used in the auto-generated code.
 454  
 455  This keyword makes sense only if C<RETVAL> is going to be accessed by the
 456  user-supplied code.  It is especially useful to make a function interface
 457  more Perl-like, especially when the C return value is just an error condition
 458  indicator.  For example,
 459  
 460    NO_OUTPUT int
 461    delete_file(char *name)
 462      POSTCALL:
 463        if (RETVAL != 0)
 464        croak("Error %d while deleting file '%s'", RETVAL, name);
 465  
 466  Here the generated XS function returns nothing on success, and will die()
 467  with a meaningful error message on error.
 468  
 469  =head2 The CODE: Keyword
 470  
 471  This keyword is used in more complicated XSUBs which require
 472  special handling for the C function.  The RETVAL variable is
 473  still declared, but it will not be returned unless it is specified
 474  in the OUTPUT: section.
 475  
 476  The following XSUB is for a C function which requires special handling of
 477  its parameters.  The Perl usage is given first.
 478  
 479       $status = rpcb_gettime( "localhost", $timep );
 480  
 481  The XSUB follows.
 482  
 483       bool_t
 484       rpcb_gettime(host,timep)
 485            char *host
 486            time_t timep
 487          CODE:
 488                 RETVAL = rpcb_gettime( host, &timep );
 489          OUTPUT:
 490            timep
 491            RETVAL
 492  
 493  =head2 The INIT: Keyword
 494  
 495  The INIT: keyword allows initialization to be inserted into the XSUB before
 496  the compiler generates the call to the C function.  Unlike the CODE: keyword
 497  above, this keyword does not affect the way the compiler handles RETVAL.
 498  
 499      bool_t
 500      rpcb_gettime(host,timep)
 501            char *host
 502            time_t &timep
 503      INIT:
 504        printf("# Host is %s\n", host );
 505          OUTPUT:
 506            timep
 507  
 508  Another use for the INIT: section is to check for preconditions before
 509  making a call to the C function:
 510  
 511      long long
 512      lldiv(a,b)
 513      long long a
 514      long long b
 515        INIT:
 516      if (a == 0 && b == 0)
 517          XSRETURN_UNDEF;
 518      if (b == 0)
 519          croak("lldiv: cannot divide by 0");
 520  
 521  =head2 The NO_INIT Keyword
 522  
 523  The NO_INIT keyword is used to indicate that a function
 524  parameter is being used only as an output value.  The B<xsubpp>
 525  compiler will normally generate code to read the values of
 526  all function parameters from the argument stack and assign
 527  them to C variables upon entry to the function.  NO_INIT
 528  will tell the compiler that some parameters will be used for
 529  output rather than for input and that they will be handled
 530  before the function terminates.
 531  
 532  The following example shows a variation of the rpcb_gettime() function.
 533  This function uses the timep variable only as an output variable and does
 534  not care about its initial contents.
 535  
 536       bool_t
 537       rpcb_gettime(host,timep)
 538            char *host
 539            time_t &timep = NO_INIT
 540          OUTPUT:
 541            timep
 542  
 543  =head2 Initializing Function Parameters
 544  
 545  C function parameters are normally initialized with their values from
 546  the argument stack (which in turn contains the parameters that were
 547  passed to the XSUB from Perl).  The typemaps contain the
 548  code segments which are used to translate the Perl values to
 549  the C parameters.  The programmer, however, is allowed to
 550  override the typemaps and supply alternate (or additional)
 551  initialization code.  Initialization code starts with the first
 552  C<=>, C<;> or C<+> on a line in the INPUT: section.  The only
 553  exception happens if this C<;> terminates the line, then this C<;>
 554  is quietly ignored.
 555  
 556  The following code demonstrates how to supply initialization code for
 557  function parameters.  The initialization code is eval'ed within double
 558  quotes by the compiler before it is added to the output so anything
 559  which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
 560  must be protected with backslashes.  The variables $var, $arg,
 561  and $type can be used as in typemaps.
 562  
 563       bool_t
 564       rpcb_gettime(host,timep)
 565            char *host = (char *)SvPV($arg,PL_na);
 566            time_t &timep = 0;
 567          OUTPUT:
 568            timep
 569  
 570  This should not be used to supply default values for parameters.  One
 571  would normally use this when a function parameter must be processed by
 572  another library function before it can be used.  Default parameters are
 573  covered in the next section.
 574  
 575  If the initialization begins with C<=>, then it is output in
 576  the declaration for the input variable, replacing the initialization
 577  supplied by the typemap.  If the initialization
 578  begins with C<;> or C<+>, then it is performed after
 579  all of the input variables have been declared.  In the C<;>
 580  case the initialization normally supplied by the typemap is not performed.
 581  For the C<+> case, the declaration for the variable will include the
 582  initialization from the typemap.  A global
 583  variable, C<%v>, is available for the truly rare case where
 584  information from one initialization is needed in another
 585  initialization.
 586  
 587  Here's a truly obscure example:
 588  
 589       bool_t
 590       rpcb_gettime(host,timep)
 591            time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
 592            char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
 593          OUTPUT:
 594            timep
 595  
 596  The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
 597  example has a two-fold purpose: first, when this line is processed by
 598  B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated.  Second,
 599  the text of the evaluated snippet is output into the generated C file
 600  (inside a C comment)!  During the processing of C<char *host> line,
 601  $arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
 602  C<ST(1)>.
 603  
 604  =head2 Default Parameter Values
 605  
 606  Default values for XSUB arguments can be specified by placing an
 607  assignment statement in the parameter list.  The default value may
 608  be a number, a string or the special string C<NO_INIT>.  Defaults should
 609  always be used on the right-most parameters only.
 610  
 611  To allow the XSUB for rpcb_gettime() to have a default host
 612  value the parameters to the XSUB could be rearranged.  The
 613  XSUB will then call the real rpcb_gettime() function with
 614  the parameters in the correct order.  This XSUB can be called
 615  from Perl with either of the following statements:
 616  
 617       $status = rpcb_gettime( $timep, $host );
 618  
 619       $status = rpcb_gettime( $timep );
 620  
 621  The XSUB will look like the code  which  follows.   A  CODE:
 622  block  is used to call the real rpcb_gettime() function with
 623  the parameters in the correct order for that function.
 624  
 625       bool_t
 626       rpcb_gettime(timep,host="localhost")
 627            char *host
 628            time_t timep = NO_INIT
 629          CODE:
 630                 RETVAL = rpcb_gettime( host, &timep );
 631          OUTPUT:
 632            timep
 633            RETVAL
 634  
 635  =head2 The PREINIT: Keyword
 636  
 637  The PREINIT: keyword allows extra variables to be declared immediately
 638  before or after the declarations of the parameters from the INPUT: section
 639  are emitted.
 640  
 641  If a variable is declared inside a CODE: section it will follow any typemap
 642  code that is emitted for the input parameters.  This may result in the
 643  declaration ending up after C code, which is C syntax error.  Similar
 644  errors may happen with an explicit C<;>-type or C<+>-type initialization of
 645  parameters is used (see L<"Initializing Function Parameters">).  Declaring
 646  these variables in an INIT: section will not help.
 647  
 648  In such cases, to force an additional variable to be declared together
 649  with declarations of other variables, place the declaration into a
 650  PREINIT: section.  The PREINIT: keyword may be used one or more times
 651  within an XSUB.
 652  
 653  The following examples are equivalent, but if the code is using complex
 654  typemaps then the first example is safer.
 655  
 656       bool_t
 657       rpcb_gettime(timep)
 658            time_t timep = NO_INIT
 659      PREINIT:
 660            char *host = "localhost";
 661          CODE:
 662        RETVAL = rpcb_gettime( host, &timep );
 663          OUTPUT:
 664            timep
 665            RETVAL
 666  
 667  For this particular case an INIT: keyword would generate the
 668  same C code as the PREINIT: keyword.  Another correct, but error-prone example:
 669  
 670       bool_t
 671       rpcb_gettime(timep)
 672            time_t timep = NO_INIT
 673      CODE:
 674            char *host = "localhost";
 675        RETVAL = rpcb_gettime( host, &timep );
 676          OUTPUT:
 677            timep
 678            RETVAL
 679  
 680  Another way to declare C<host> is to use a C block in the CODE: section:
 681  
 682       bool_t
 683       rpcb_gettime(timep)
 684            time_t timep = NO_INIT
 685      CODE:
 686        {
 687              char *host = "localhost";
 688          RETVAL = rpcb_gettime( host, &timep );
 689        }
 690          OUTPUT:
 691            timep
 692            RETVAL
 693  
 694  The ability to put additional declarations before the typemap entries are
 695  processed is very handy in the cases when typemap conversions manipulate
 696  some global state:
 697  
 698      MyObject
 699      mutate(o)
 700      PREINIT:
 701          MyState st = global_state;
 702      INPUT:
 703          MyObject o;
 704      CLEANUP:
 705          reset_to(global_state, st);
 706  
 707  Here we suppose that conversion to C<MyObject> in the INPUT: section and from
 708  MyObject when processing RETVAL will modify a global variable C<global_state>.
 709  After these conversions are performed, we restore the old value of
 710  C<global_state> (to avoid memory leaks, for example).
 711  
 712  There is another way to trade clarity for compactness: INPUT sections allow
 713  declaration of C variables which do not appear in the parameter list of
 714  a subroutine.  Thus the above code for mutate() can be rewritten as
 715  
 716      MyObject
 717      mutate(o)
 718        MyState st = global_state;
 719        MyObject o;
 720      CLEANUP:
 721        reset_to(global_state, st);
 722  
 723  and the code for rpcb_gettime() can be rewritten as
 724  
 725       bool_t
 726       rpcb_gettime(timep)
 727        time_t timep = NO_INIT
 728        char *host = "localhost";
 729      C_ARGS:
 730        host, &timep
 731      OUTPUT:
 732            timep
 733            RETVAL
 734  
 735  =head2 The SCOPE: Keyword
 736  
 737  The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
 738  enabled, the XSUB will invoke ENTER and LEAVE automatically.
 739  
 740  To support potentially complex type mappings, if a typemap entry used
 741  by an XSUB contains a comment like C</*scope*/> then scoping will
 742  be automatically enabled for that XSUB.
 743  
 744  To enable scoping:
 745  
 746      SCOPE: ENABLE
 747  
 748  To disable scoping:
 749  
 750      SCOPE: DISABLE
 751  
 752  =head2 The INPUT: Keyword
 753  
 754  The XSUB's parameters are usually evaluated immediately after entering the
 755  XSUB.  The INPUT: keyword can be used to force those parameters to be
 756  evaluated a little later.  The INPUT: keyword can be used multiple times
 757  within an XSUB and can be used to list one or more input variables.  This
 758  keyword is used with the PREINIT: keyword.
 759  
 760  The following example shows how the input parameter C<timep> can be
 761  evaluated late, after a PREINIT.
 762  
 763      bool_t
 764      rpcb_gettime(host,timep)
 765            char *host
 766      PREINIT:
 767        time_t tt;
 768      INPUT:
 769            time_t timep
 770          CODE:
 771                 RETVAL = rpcb_gettime( host, &tt );
 772             timep = tt;
 773          OUTPUT:
 774            timep
 775            RETVAL
 776  
 777  The next example shows each input parameter evaluated late.
 778  
 779      bool_t
 780      rpcb_gettime(host,timep)
 781      PREINIT:
 782        time_t tt;
 783      INPUT:
 784            char *host
 785      PREINIT:
 786        char *h;
 787      INPUT:
 788            time_t timep
 789          CODE:
 790             h = host;
 791             RETVAL = rpcb_gettime( h, &tt );
 792             timep = tt;
 793          OUTPUT:
 794            timep
 795            RETVAL
 796  
 797  Since INPUT sections allow declaration of C variables which do not appear
 798  in the parameter list of a subroutine, this may be shortened to:
 799  
 800      bool_t
 801      rpcb_gettime(host,timep)
 802        time_t tt;
 803            char *host;
 804        char *h = host;
 805            time_t timep;
 806          CODE:
 807        RETVAL = rpcb_gettime( h, &tt );
 808        timep = tt;
 809          OUTPUT:
 810            timep
 811            RETVAL
 812  
 813  (We used our knowledge that input conversion for C<char *> is a "simple" one,
 814  thus C<host> is initialized on the declaration line, and our assignment
 815  C<h = host> is not performed too early.  Otherwise one would need to have the
 816  assignment C<h = host> in a CODE: or INIT: section.)
 817  
 818  =head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
 819  
 820  In the list of parameters for an XSUB, one can precede parameter names
 821  by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords.
 822  C<IN> keyword is the default, the other keywords indicate how the Perl
 823  interface should differ from the C interface.
 824  
 825  Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT>
 826  keywords are considered to be used by the C subroutine I<via
 827  pointers>.  C<OUTLIST>/C<OUT> keywords indicate that the C subroutine
 828  does not inspect the memory pointed by this parameter, but will write
 829  through this pointer to provide additional return values.
 830  
 831  Parameters preceded by C<OUTLIST> keyword do not appear in the usage
 832  signature of the generated Perl function.
 833  
 834  Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as
 835  parameters to the Perl function.  With the exception of
 836  C<OUT>-parameters, these parameters are converted to the corresponding
 837  C type, then pointers to these data are given as arguments to the C
 838  function.  It is expected that the C function will write through these
 839  pointers.
 840  
 841  The return list of the generated Perl function consists of the C return value
 842  from the function (unless the XSUB is of C<void> return type or
 843  C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST>
 844  and C<IN_OUTLIST> parameters (in the order of appearance).  On the
 845  return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be
 846  modified to have the values written by the C function.
 847  
 848  For example, an XSUB
 849  
 850    void
 851    day_month(OUTLIST day, IN unix_time, OUTLIST month)
 852      int day
 853      int unix_time
 854      int month
 855  
 856  should be used from Perl as
 857  
 858    my ($day, $month) = day_month(time);
 859  
 860  The C signature of the corresponding function should be
 861  
 862    void day_month(int *day, int unix_time, int *month);
 863  
 864  The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be
 865  mixed with ANSI-style declarations, as in
 866  
 867    void
 868    day_month(OUTLIST int day, int unix_time, OUTLIST int month)
 869  
 870  (here the optional C<IN> keyword is omitted).
 871  
 872  The C<IN_OUT> parameters are identical with parameters introduced with
 873  L<The & Unary Operator> and put into the C<OUTPUT:> section (see
 874  L<The OUTPUT: Keyword>).  The C<IN_OUTLIST> parameters are very similar,
 875  the only difference being that the value C function writes through the
 876  pointer would not modify the Perl parameter, but is put in the output
 877  list.
 878  
 879  The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT>
 880  parameters only by the initial value of the Perl parameter not
 881  being read (and not being given to the C function - which gets some
 882  garbage instead).  For example, the same C function as above can be
 883  interfaced with as
 884  
 885    void day_month(OUT int day, int unix_time, OUT int month);
 886  
 887  or
 888  
 889    void
 890    day_month(day, unix_time, month)
 891        int &day = NO_INIT
 892        int  unix_time
 893        int &month = NO_INIT
 894      OUTPUT:
 895        day
 896        month
 897  
 898  However, the generated Perl function is called in very C-ish style:
 899  
 900    my ($day, $month);
 901    day_month($day, time, $month);
 902  
 903  =head2 The C<length(NAME)> Keyword
 904  
 905  If one of the input arguments to the C function is the length of a string
 906  argument C<NAME>, one can substitute the name of the length-argument by
 907  C<length(NAME)> in the XSUB declaration.  This argument must be omitted when
 908  the generated Perl function is called.  E.g.,
 909  
 910    void
 911    dump_chars(char *s, short l)
 912    {
 913      short n = 0;
 914      while (n < l) {
 915          printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
 916          n++;
 917      }
 918    }
 919  
 920    MODULE = x        PACKAGE = x
 921  
 922    void dump_chars(char *s, short length(s))
 923  
 924  should be called as C<dump_chars($string)>.
 925  
 926  This directive is supported with ANSI-type function declarations only.
 927  
 928  =head2 Variable-length Parameter Lists
 929  
 930  XSUBs can have variable-length parameter lists by specifying an ellipsis
 931  C<(...)> in the parameter list.  This use of the ellipsis is similar to that
 932  found in ANSI C.  The programmer is able to determine the number of
 933  arguments passed to the XSUB by examining the C<items> variable which the
 934  B<xsubpp> compiler supplies for all XSUBs.  By using this mechanism one can
 935  create an XSUB which accepts a list of parameters of unknown length.
 936  
 937  The I<host> parameter for the rpcb_gettime() XSUB can be
 938  optional so the ellipsis can be used to indicate that the
 939  XSUB will take a variable number of parameters.  Perl should
 940  be able to call this XSUB with either of the following statements.
 941  
 942       $status = rpcb_gettime( $timep, $host );
 943  
 944       $status = rpcb_gettime( $timep );
 945  
 946  The XS code, with ellipsis, follows.
 947  
 948       bool_t
 949       rpcb_gettime(timep, ...)
 950            time_t timep = NO_INIT
 951      PREINIT:
 952            char *host = "localhost";
 953        STRLEN n_a;
 954          CODE:
 955        if( items > 1 )
 956             host = (char *)SvPV(ST(1), n_a);
 957        RETVAL = rpcb_gettime( host, &timep );
 958          OUTPUT:
 959            timep
 960            RETVAL
 961  
 962  =head2 The C_ARGS: Keyword
 963  
 964  The C_ARGS: keyword allows creating of XSUBS which have different
 965  calling sequence from Perl than from C, without a need to write
 966  CODE: or PPCODE: section.  The contents of the C_ARGS: paragraph is
 967  put as the argument to the called C function without any change.
 968  
 969  For example, suppose that a C function is declared as
 970  
 971      symbolic nth_derivative(int n, symbolic function, int flags);
 972  
 973  and that the default flags are kept in a global C variable
 974  C<default_flags>.  Suppose that you want to create an interface which
 975  is called as
 976  
 977      $second_deriv = $function->nth_derivative(2);
 978  
 979  To do this, declare the XSUB as
 980  
 981      symbolic
 982      nth_derivative(function, n)
 983      symbolic    function
 984      int        n
 985        C_ARGS:
 986      n, function, default_flags
 987  
 988  =head2 The PPCODE: Keyword
 989  
 990  The PPCODE: keyword is an alternate form of the CODE: keyword and is used
 991  to tell the B<xsubpp> compiler that the programmer is supplying the code to
 992  control the argument stack for the XSUBs return values.  Occasionally one
 993  will want an XSUB to return a list of values rather than a single value.
 994  In these cases one must use PPCODE: and then explicitly push the list of
 995  values on the stack.  The PPCODE: and CODE:  keywords should not be used
 996  together within the same XSUB.
 997  
 998  The actual difference between PPCODE: and CODE: sections is in the
 999  initialization of C<SP> macro (which stands for the I<current> Perl
1000  stack pointer), and in the handling of data on the stack when returning
1001  from an XSUB.  In CODE: sections SP preserves the value which was on
1002  entry to the XSUB: SP is on the function pointer (which follows the
1003  last parameter).  In PPCODE: sections SP is moved backward to the
1004  beginning of the parameter list, which allows C<PUSH*()> macros
1005  to place output values in the place Perl expects them to be when
1006  the XSUB returns back to Perl.
1007  
1008  The generated trailer for a CODE: section ensures that the number of return
1009  values Perl will see is either 0 or 1 (depending on the C<void>ness of the
1010  return value of the C function, and heuristics mentioned in
1011  L<"The RETVAL Variable">).  The trailer generated for a PPCODE: section
1012  is based on the number of return values and on the number of times
1013  C<SP> was updated by C<[X]PUSH*()> macros.
1014  
1015  Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
1016  well in CODE: sections and PPCODE: sections.
1017  
1018  The following XSUB will call the C rpcb_gettime() function
1019  and will return its two output values, timep and status, to
1020  Perl as a single list.
1021  
1022       void
1023       rpcb_gettime(host)
1024            char *host
1025      PREINIT:
1026            time_t  timep;
1027            bool_t  status;
1028          PPCODE:
1029            status = rpcb_gettime( host, &timep );
1030            EXTEND(SP, 2);
1031            PUSHs(sv_2mortal(newSViv(status)));
1032            PUSHs(sv_2mortal(newSViv(timep)));
1033  
1034  Notice that the programmer must supply the C code necessary
1035  to have the real rpcb_gettime() function called and to have
1036  the return values properly placed on the argument stack.
1037  
1038  The C<void> return type for this function tells the B<xsubpp> compiler that
1039  the RETVAL variable is not needed or used and that it should not be created.
1040  In most scenarios the void return type should be used with the PPCODE:
1041  directive.
1042  
1043  The EXTEND() macro is used to make room on the argument
1044  stack for 2 return values.  The PPCODE: directive causes the
1045  B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
1046  is this pointer which is being used in the EXTEND() macro.
1047  The values are then pushed onto the stack with the PUSHs()
1048  macro.
1049  
1050  Now the rpcb_gettime() function can be used from Perl with
1051  the following statement.
1052  
1053       ($status, $timep) = rpcb_gettime("localhost");
1054  
1055  When handling output parameters with a PPCODE section, be sure to handle
1056  'set' magic properly.  See L<perlguts> for details about 'set' magic.
1057  
1058  =head2 Returning Undef And Empty Lists
1059  
1060  Occasionally the programmer will want to return simply
1061  C<undef> or an empty list if a function fails rather than a
1062  separate status value.  The rpcb_gettime() function offers
1063  just this situation.  If the function succeeds we would like
1064  to have it return the time and if it fails we would like to
1065  have undef returned.  In the following Perl code the value
1066  of $timep will either be undef or it will be a valid time.
1067  
1068       $timep = rpcb_gettime( "localhost" );
1069  
1070  The following XSUB uses the C<SV *> return type as a mnemonic only,
1071  and uses a CODE: block to indicate to the compiler
1072  that the programmer has supplied all the necessary code.  The
1073  sv_newmortal() call will initialize the return value to undef, making that
1074  the default return value.
1075  
1076       SV *
1077       rpcb_gettime(host)
1078            char *  host
1079      PREINIT:
1080            time_t  timep;
1081            bool_t x;
1082          CODE:
1083            ST(0) = sv_newmortal();
1084            if( rpcb_gettime( host, &timep ) )
1085                 sv_setnv( ST(0), (double)timep);
1086  
1087  The next example demonstrates how one would place an explicit undef in the
1088  return value, should the need arise.
1089  
1090       SV *
1091       rpcb_gettime(host)
1092            char *  host
1093      PREINIT:
1094            time_t  timep;
1095            bool_t x;
1096          CODE:
1097            ST(0) = sv_newmortal();
1098            if( rpcb_gettime( host, &timep ) ){
1099                 sv_setnv( ST(0), (double)timep);
1100            }
1101            else{
1102                 ST(0) = &PL_sv_undef;
1103            }
1104  
1105  To return an empty list one must use a PPCODE: block and
1106  then not push return values on the stack.
1107  
1108       void
1109       rpcb_gettime(host)
1110            char *host
1111      PREINIT:
1112            time_t  timep;
1113          PPCODE:
1114            if( rpcb_gettime( host, &timep ) )
1115                 PUSHs(sv_2mortal(newSViv(timep)));
1116            else{
1117            /* Nothing pushed on stack, so an empty
1118             * list is implicitly returned. */
1119            }
1120  
1121  Some people may be inclined to include an explicit C<return> in the above
1122  XSUB, rather than letting control fall through to the end.  In those
1123  situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that
1124  the XSUB stack is properly adjusted.  Consult L<perlapi> for other
1125  C<XSRETURN> macros.
1126  
1127  Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
1128  rewrite this example as:
1129  
1130       int
1131       rpcb_gettime(host)
1132            char *host
1133      PREINIT:
1134            time_t  timep;
1135          CODE:
1136            RETVAL = rpcb_gettime( host, &timep );
1137        if (RETVAL == 0)
1138          XSRETURN_UNDEF;
1139      OUTPUT:
1140        RETVAL
1141  
1142  In fact, one can put this check into a POSTCALL: section as well.  Together
1143  with PREINIT: simplifications, this leads to:
1144  
1145       int
1146       rpcb_gettime(host)
1147            char *host
1148            time_t  timep;
1149      POSTCALL:
1150        if (RETVAL == 0)
1151          XSRETURN_UNDEF;
1152  
1153  =head2 The REQUIRE: Keyword
1154  
1155  The REQUIRE: keyword is used to indicate the minimum version of the
1156  B<xsubpp> compiler needed to compile the XS module.  An XS module which
1157  contains the following statement will compile with only B<xsubpp> version
1158  1.922 or greater:
1159  
1160      REQUIRE: 1.922
1161  
1162  =head2 The CLEANUP: Keyword
1163  
1164  This keyword can be used when an XSUB requires special cleanup procedures
1165  before it terminates.  When the CLEANUP:  keyword is used it must follow
1166  any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB.  The
1167  code specified for the cleanup block will be added as the last statements
1168  in the XSUB.
1169  
1170  =head2 The POSTCALL: Keyword
1171  
1172  This keyword can be used when an XSUB requires special procedures
1173  executed after the C subroutine call is performed.  When the POSTCALL:
1174  keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1175  present in the XSUB.
1176  
1177  See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">.
1178  
1179  The POSTCALL: block does not make a lot of sense when the C subroutine
1180  call is supplied by user by providing either CODE: or PPCODE: section.
1181  
1182  =head2 The BOOT: Keyword
1183  
1184  The BOOT: keyword is used to add code to the extension's bootstrap
1185  function.  The bootstrap function is generated by the B<xsubpp> compiler and
1186  normally holds the statements necessary to register any XSUBs with Perl.
1187  With the BOOT: keyword the programmer can tell the compiler to add extra
1188  statements to the bootstrap function.
1189  
1190  This keyword may be used any time after the first MODULE keyword and should
1191  appear on a line by itself.  The first blank line after the keyword will
1192  terminate the code block.
1193  
1194       BOOT:
1195       # The following message will be printed when the
1196       # bootstrap function executes.
1197       printf("Hello from the bootstrap!\n");
1198  
1199  =head2 The VERSIONCHECK: Keyword
1200  
1201  The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
1202  C<-noversioncheck> options.  This keyword overrides the command line
1203  options.  Version checking is enabled by default.  When version checking is
1204  enabled the XS module will attempt to verify that its version matches the
1205  version of the PM module.
1206  
1207  To enable version checking:
1208  
1209      VERSIONCHECK: ENABLE
1210  
1211  To disable version checking:
1212  
1213      VERSIONCHECK: DISABLE
1214  
1215  =head2 The PROTOTYPES: Keyword
1216  
1217  The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
1218  C<-noprototypes> options.  This keyword overrides the command line options.
1219  Prototypes are enabled by default.  When prototypes are enabled XSUBs will
1220  be given Perl prototypes.  This keyword may be used multiple times in an XS
1221  module to enable and disable prototypes for different parts of the module.
1222  
1223  To enable prototypes:
1224  
1225      PROTOTYPES: ENABLE
1226  
1227  To disable prototypes:
1228  
1229      PROTOTYPES: DISABLE
1230  
1231  =head2 The PROTOTYPE: Keyword
1232  
1233  This keyword is similar to the PROTOTYPES: keyword above but can be used to
1234  force B<xsubpp> to use a specific prototype for the XSUB.  This keyword
1235  overrides all other prototype options and keywords but affects only the
1236  current XSUB.  Consult L<perlsub/Prototypes> for information about Perl
1237  prototypes.
1238  
1239      bool_t
1240      rpcb_gettime(timep, ...)
1241            time_t timep = NO_INIT
1242      PROTOTYPE: $;$
1243      PREINIT:
1244            char *host = "localhost";
1245        STRLEN n_a;
1246          CODE:
1247            if( items > 1 )
1248                 host = (char *)SvPV(ST(1), n_a);
1249            RETVAL = rpcb_gettime( host, &timep );
1250          OUTPUT:
1251            timep
1252            RETVAL
1253  
1254  If the prototypes are enabled, you can disable it locally for a given
1255  XSUB as in the following example:
1256  
1257      void
1258      rpcb_gettime_noproto()
1259          PROTOTYPE: DISABLE
1260      ...
1261  
1262  =head2 The ALIAS: Keyword
1263  
1264  The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1265  and to know which of those names was used when it was invoked.  The Perl
1266  names may be fully-qualified with package names.  Each alias is given an
1267  index.  The compiler will setup a variable called C<ix> which contain the
1268  index of the alias which was used.  When the XSUB is called with its
1269  declared name C<ix> will be 0.
1270  
1271  The following example will create aliases C<FOO::gettime()> and
1272  C<BAR::getit()> for this function.
1273  
1274      bool_t
1275      rpcb_gettime(host,timep)
1276            char *host
1277            time_t &timep
1278      ALIAS:
1279          FOO::gettime = 1
1280          BAR::getit = 2
1281      INIT:
1282        printf("# ix = %d\n", ix );
1283          OUTPUT:
1284            timep
1285  
1286  =head2 The OVERLOAD: Keyword
1287  
1288  Instead of writing an overloaded interface using pure Perl, you
1289  can also use the OVERLOAD keyword to define additional Perl names
1290  for your functions (like the ALIAS: keyword above).  However, the
1291  overloaded functions must be defined with three parameters (except
1292  for the nomethod() function which needs four parameters).  If any
1293  function has the OVERLOAD: keyword, several additional lines
1294  will be defined in the c file generated by xsubpp in order to 
1295  register with the overload magic.
1296  
1297  Since blessed objects are actually stored as RV's, it is useful
1298  to use the typemap features to preprocess parameters and extract
1299  the actual SV stored within the blessed RV. See the sample for
1300  T_PTROBJ_SPECIAL below.
1301  
1302  To use the OVERLOAD: keyword, create an XS function which takes
1303  three input parameters ( or use the c style '...' definition) like
1304  this:
1305  
1306      SV *
1307      cmp (lobj, robj, swap)
1308      My_Module_obj    lobj
1309      My_Module_obj    robj
1310      IV               swap
1311      OVERLOAD: cmp <=>
1312      { /* function defined here */}
1313  
1314  In this case, the function will overload both of the three way
1315  comparison operators.  For all overload operations using non-alpha
1316  characters, you must type the parameter without quoting, separating
1317  multiple overloads with whitespace.  Note that "" (the stringify 
1318  overload) should be entered as \"\" (i.e. escaped).
1319  
1320  =head2 The FALLBACK: Keyword
1321  
1322  In addition to the OVERLOAD keyword, if you need to control how
1323  Perl autogenerates missing overloaded operators, you can set the
1324  FALLBACK keyword in the module header section, like this:
1325  
1326      MODULE = RPC  PACKAGE = RPC
1327  
1328      FALLBACK: TRUE
1329      ...
1330  
1331  where FALLBACK can take any of the three values TRUE, FALSE, or
1332  UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
1333  it defaults to UNDEF.  FALLBACK is not used except when one or 
1334  more functions using OVERLOAD have been defined.  Please see
1335  L<overload/Fallback> for more details.
1336  
1337  =head2 The INTERFACE: Keyword
1338  
1339  This keyword declares the current XSUB as a keeper of the given
1340  calling signature.  If some text follows this keyword, it is
1341  considered as a list of functions which have this signature, and
1342  should be attached to the current XSUB.
1343  
1344  For example, if you have 4 C functions multiply(), divide(), add(),
1345  subtract() all having the signature:
1346  
1347      symbolic f(symbolic, symbolic);
1348  
1349  you can make them all to use the same XSUB using this:
1350  
1351      symbolic
1352      interface_s_ss(arg1, arg2)  
1353      symbolic    arg1
1354      symbolic    arg2
1355      INTERFACE:
1356      multiply divide 
1357      add subtract
1358  
1359  (This is the complete XSUB code for 4 Perl functions!)  Four generated
1360  Perl function share names with corresponding C functions.
1361  
1362  The advantage of this approach comparing to ALIAS: keyword is that there
1363  is no need to code a switch statement, each Perl function (which shares
1364  the same XSUB) knows which C function it should call.  Additionally, one
1365  can attach an extra function remainder() at runtime by using
1366  
1367      CV *mycv = newXSproto("Symbolic::remainder", 
1368                XS_Symbolic_interface_s_ss, __FILE__, "$$");
1369      XSINTERFACE_FUNC_SET(mycv, remainder);
1370  
1371  say, from another XSUB.  (This example supposes that there was no
1372  INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1373  C<XSINTERFACE_FUNC_SET>, see the next section.)
1374  
1375  =head2 The INTERFACE_MACRO: Keyword
1376  
1377  This keyword allows one to define an INTERFACE using a different way
1378  to extract a function pointer from an XSUB.  The text which follows
1379  this keyword should give the name of macros which would extract/set a
1380  function pointer.  The extractor macro is given return type, C<CV*>,
1381  and C<XSANY.any_dptr> for this C<CV*>.  The setter macro is given cv,
1382  and the function pointer.
1383  
1384  The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1385  An INTERFACE keyword with an empty list of functions can be omitted if
1386  INTERFACE_MACRO keyword is used.
1387  
1388  Suppose that in the previous example functions pointers for 
1389  multiply(), divide(), add(), subtract() are kept in a global C array
1390  C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1391  C<subtract_off>.  Then one can use 
1392  
1393      #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1394      ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1395      #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1396      CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1397  
1398  in C section,
1399  
1400      symbolic
1401      interface_s_ss(arg1, arg2)  
1402      symbolic    arg1
1403      symbolic    arg2
1404        INTERFACE_MACRO: 
1405      XSINTERFACE_FUNC_BYOFFSET
1406      XSINTERFACE_FUNC_BYOFFSET_set
1407        INTERFACE:
1408      multiply divide 
1409      add subtract
1410  
1411  in XSUB section.
1412  
1413  =head2 The INCLUDE: Keyword
1414  
1415  This keyword can be used to pull other files into the XS module.  The other
1416  files may have XS code.  INCLUDE: can also be used to run a command to
1417  generate the XS code to be pulled into the module.
1418  
1419  The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1420  
1421      bool_t
1422      rpcb_gettime(host,timep)
1423            char *host
1424            time_t &timep
1425          OUTPUT:
1426            timep
1427  
1428  The XS module can use INCLUDE: to pull that file into it.
1429  
1430      INCLUDE: Rpcb1.xsh
1431  
1432  If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1433  the compiler will interpret the parameters as a command.
1434  
1435      INCLUDE: cat Rpcb1.xsh |
1436  
1437  =head2 The CASE: Keyword
1438  
1439  The CASE: keyword allows an XSUB to have multiple distinct parts with each
1440  part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
1441  other XS keywords must be contained within a CASE:.  This means nothing may
1442  precede the first CASE: in the XSUB and anything following the last CASE: is
1443  included in that case.
1444  
1445  A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1446  variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1447  (see L<"Variable-length Parameter Lists">).  The last CASE: becomes the
1448  B<default> case if it is not associated with a conditional.  The following
1449  example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1450  having an alias C<x_gettime()>.  When the function is called as
1451  C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1452  but when the function is called as C<x_gettime()> its parameters are
1453  reversed, C<(time_t *timep, char *host)>.
1454  
1455      long
1456      rpcb_gettime(a,b)
1457        CASE: ix == 1
1458      ALIAS:
1459        x_gettime = 1
1460      INPUT:
1461        # 'a' is timep, 'b' is host
1462            char *b
1463            time_t a = NO_INIT
1464          CODE:
1465                 RETVAL = rpcb_gettime( b, &a );
1466          OUTPUT:
1467            a
1468            RETVAL
1469        CASE:
1470        # 'a' is host, 'b' is timep
1471            char *a
1472            time_t &b = NO_INIT
1473          OUTPUT:
1474            b
1475            RETVAL
1476  
1477  That function can be called with either of the following statements.  Note
1478  the different argument lists.
1479  
1480      $status = rpcb_gettime( $host, $timep );
1481  
1482      $status = x_gettime( $timep, $host );
1483  
1484  =head2 The & Unary Operator
1485  
1486  The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1487  that it should convert a Perl value to/from C using the C type to the left
1488  of C<&>, but provide a pointer to this value when the C function is called.
1489  
1490  This is useful to avoid a CODE: block for a C function which takes a parameter
1491  by reference.  Typically, the parameter should be not a pointer type (an
1492  C<int> or C<long> but not an C<int*> or C<long*>).
1493  
1494  The following XSUB will generate incorrect C code.  The B<xsubpp> compiler will
1495  turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1496  *host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1497  parameter to be of type C<time_t*> rather than C<time_t>.
1498  
1499      bool_t
1500      rpcb_gettime(host,timep)
1501            char *host
1502            time_t timep
1503          OUTPUT:
1504            timep
1505  
1506  That problem is corrected by using the C<&> operator.  The B<xsubpp> compiler
1507  will now turn this into code which calls C<rpcb_gettime()> correctly with
1508  parameters C<(char *host, time_t *timep)>.  It does this by carrying the
1509  C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1510  
1511      bool_t
1512      rpcb_gettime(host,timep)
1513            char *host
1514            time_t &timep
1515          OUTPUT:
1516            timep
1517  
1518  =head2 Inserting POD, Comments and C Preprocessor Directives
1519  
1520  C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
1521  PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
1522  Comments are allowed anywhere after the MODULE keyword.  The compiler will
1523  pass the preprocessor directives through untouched and will remove the
1524  commented lines. POD documentation is allowed at any point, both in the
1525  C and XS language sections. POD must be terminated with a C<=cut> command;
1526  C<xsubpp> will exit with an error if it does not. It is very unlikely that
1527  human generated C code will be mistaken for POD, as most indenting styles
1528  result in whitespace in front of any line starting with C<=>. Machine
1529  generated XS files may fall into this trap unless care is taken to
1530  ensure that a space breaks the sequence "\n=".
1531  
1532  Comments can be added to XSUBs by placing a C<#> as the first
1533  non-whitespace of a line.  Care should be taken to avoid making the
1534  comment look like a C preprocessor directive, lest it be interpreted as
1535  such.  The simplest way to prevent this is to put whitespace in front of
1536  the C<#>.
1537  
1538  If you use preprocessor directives to choose one of two
1539  versions of a function, use
1540  
1541      #if ... version1
1542      #else /* ... version2  */
1543      #endif
1544  
1545  and not
1546  
1547      #if ... version1
1548      #endif
1549      #if ... version2
1550      #endif
1551  
1552  because otherwise B<xsubpp> will believe that you made a duplicate
1553  definition of the function.  Also, put a blank line before the
1554  #else/#endif so it will not be seen as part of the function body.
1555  
1556  =head2 Using XS With C++
1557  
1558  If an XSUB name contains C<::>, it is considered to be a C++ method.
1559  The generated Perl function will assume that
1560  its first argument is an object pointer.  The object pointer
1561  will be stored in a variable called THIS.  The object should
1562  have been created by C++ with the new() function and should
1563  be blessed by Perl with the sv_setref_pv() macro.  The
1564  blessing of the object by Perl can be handled by a typemap.  An example
1565  typemap is shown at the end of this section.
1566  
1567  If the return type of the XSUB includes C<static>, the method is considered
1568  to be a static method.  It will call the C++
1569  function using the class::method() syntax.  If the method is not static
1570  the function will be called using the THIS-E<gt>method() syntax.
1571  
1572  The next examples will use the following C++ class.
1573  
1574       class color {
1575            public:
1576            color();
1577            ~color();
1578            int blue();
1579            void set_blue( int );
1580  
1581            private:
1582            int c_blue;
1583       };
1584  
1585  The XSUBs for the blue() and set_blue() methods are defined with the class
1586  name but the parameter for the object (THIS, or "self") is implicit and is
1587  not listed.
1588  
1589       int
1590       color::blue()
1591  
1592       void
1593       color::set_blue( val )
1594            int val
1595  
1596  Both Perl functions will expect an object as the first parameter.  In the 
1597  generated C++ code the object is called C<THIS>, and the method call will
1598  be performed on this object.  So in the C++ code the blue() and set_blue()
1599  methods will be called as this:
1600  
1601       RETVAL = THIS->blue();
1602  
1603       THIS->set_blue( val );
1604  
1605  You could also write a single get/set method using an optional argument:
1606  
1607       int
1608       color::blue( val = NO_INIT )
1609           int val
1610           PROTOTYPE $;$
1611           CODE:
1612               if (items > 1)
1613                   THIS->set_blue( val );
1614               RETVAL = THIS->blue();
1615           OUTPUT:
1616               RETVAL
1617  
1618  If the function's name is B<DESTROY> then the C++ C<delete> function will be
1619  called and C<THIS> will be given as its parameter.  The generated C++ code for
1620  
1621       void
1622       color::DESTROY()
1623  
1624  will look like this:
1625  
1626       color *THIS = ...;    // Initialized as in typemap
1627  
1628       delete THIS;
1629  
1630  If the function's name is B<new> then the C++ C<new> function will be called
1631  to create a dynamic C++ object.  The XSUB will expect the class name, which
1632  will be kept in a variable called C<CLASS>, to be given as the first
1633  argument.
1634  
1635       color *
1636       color::new()
1637  
1638  The generated C++ code will call C<new>.
1639  
1640       RETVAL = new color();
1641  
1642  The following is an example of a typemap that could be used for this C++
1643  example.
1644  
1645      TYPEMAP
1646      color *        O_OBJECT
1647  
1648      OUTPUT
1649      # The Perl object is blessed into 'CLASS', which should be a
1650      # char* having the name of the package for the blessing.
1651      O_OBJECT
1652          sv_setref_pv( $arg, CLASS, (void*)$var );
1653  
1654      INPUT
1655      O_OBJECT
1656          if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1657              $var = ($type)SvIV((SV*)SvRV( $arg ));
1658          else{
1659              warn( \"$Package}::$func_name() -- $var is not a blessed SV reference\" );
1660              XSRETURN_UNDEF;
1661          }
1662  
1663  =head2 Interface Strategy
1664  
1665  When designing an interface between Perl and a C library a straight
1666  translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1667  However, sometimes the interface will look
1668  very C-like and occasionally nonintuitive, especially when the C function
1669  modifies one of its parameters, or returns failure inband (as in "negative
1670  return values mean failure").  In cases where the programmer wishes to
1671  create a more Perl-like interface the following strategy may help to
1672  identify the more critical parts of the interface.
1673  
1674  Identify the C functions with input/output or output parameters.  The XSUBs for
1675  these functions may be able to return lists to Perl.
1676  
1677  Identify the C functions which use some inband info as an indication
1678  of failure.  They may be
1679  candidates to return undef or an empty list in case of failure.  If the
1680  failure may be detected without a call to the C function, you may want to use
1681  an INIT: section to report the failure.  For failures detectable after the C
1682  function returns one may want to use a POSTCALL: section to process the
1683  failure.  In more complicated cases use CODE: or PPCODE: sections.
1684  
1685  If many functions use the same failure indication based on the return value,
1686  you may want to create a special typedef to handle this situation.  Put
1687  
1688    typedef int negative_is_failure;
1689  
1690  near the beginning of XS file, and create an OUTPUT typemap entry
1691  for C<negative_is_failure> which converts negative values to C<undef>, or
1692  maybe croak()s.  After this the return value of type C<negative_is_failure>
1693  will create more Perl-like interface.
1694  
1695  Identify which values are used by only the C and XSUB functions
1696  themselves, say, when a parameter to a function should be a contents of a
1697  global variable.  If Perl does not need to access the contents of the value
1698  then it may not be necessary to provide a translation for that value
1699  from C to Perl.
1700  
1701  Identify the pointers in the C function parameter lists and return
1702  values.  Some pointers may be used to implement input/output or
1703  output parameters, they can be handled in XS with the C<&> unary operator,
1704  and, possibly, using the NO_INIT keyword.
1705  Some others will require handling of types like C<int *>, and one needs
1706  to decide what a useful Perl translation will do in such a case.  When
1707  the semantic is clear, it is advisable to put the translation into a typemap
1708  file.
1709  
1710  Identify the structures used by the C functions.  In many
1711  cases it may be helpful to use the T_PTROBJ typemap for
1712  these structures so they can be manipulated by Perl as
1713  blessed objects.  (This is handled automatically by C<h2xs -x>.)
1714  
1715  If the same C type is used in several different contexts which require
1716  different translations, C<typedef> several new types mapped to this C type,
1717  and create separate F<typemap> entries for these new types.  Use these
1718  types in declarations of return type and parameters to XSUBs.
1719  
1720  =head2 Perl Objects And C Structures
1721  
1722  When dealing with C structures one should select either
1723  B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
1724  designed to handle pointers to complex objects.  The
1725  T_PTRREF type will allow the Perl object to be unblessed
1726  while the T_PTROBJ type requires that the object be blessed.
1727  By using T_PTROBJ one can achieve a form of type-checking
1728  because the XSUB will attempt to verify that the Perl object
1729  is of the expected type.
1730  
1731  The following XS code shows the getnetconfigent() function which is used
1732  with ONC+ TIRPC.  The getnetconfigent() function will return a pointer to a
1733  C structure and has the C prototype shown below.  The example will
1734  demonstrate how the C pointer will become a Perl reference.  Perl will
1735  consider this reference to be a pointer to a blessed object and will
1736  attempt to call a destructor for the object.  A destructor will be
1737  provided in the XS source to free the memory used by getnetconfigent().
1738  Destructors in XS can be created by specifying an XSUB function whose name
1739  ends with the word B<DESTROY>.  XS destructors can be used to free memory
1740  which may have been malloc'd by another XSUB.
1741  
1742       struct netconfig *getnetconfigent(const char *netid);
1743  
1744  A C<typedef> will be created for C<struct netconfig>.  The Perl
1745  object will be blessed in a class matching the name of the C
1746  type, with the tag C<Ptr> appended, and the name should not
1747  have embedded spaces if it will be a Perl package name.  The
1748  destructor will be placed in a class corresponding to the
1749  class of the object and the PREFIX keyword will be used to
1750  trim the name to the word DESTROY as Perl will expect.
1751  
1752       typedef struct netconfig Netconfig;
1753  
1754       MODULE = RPC  PACKAGE = RPC
1755  
1756       Netconfig *
1757       getnetconfigent(netid)
1758            char *netid
1759  
1760       MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1761  
1762       void
1763       rpcb_DESTROY(netconf)
1764            Netconfig *netconf
1765          CODE:
1766            printf("Now in NetconfigPtr::DESTROY\n");
1767            free( netconf );
1768  
1769  This example requires the following typemap entry.  Consult the typemap
1770  section for more information about adding new typemaps for an extension.
1771  
1772       TYPEMAP
1773       Netconfig *  T_PTROBJ
1774  
1775  This example will be used with the following Perl statements.
1776  
1777       use RPC;
1778       $netconf = getnetconfigent("udp");
1779  
1780  When Perl destroys the object referenced by $netconf it will send the
1781  object to the supplied XSUB DESTROY function.  Perl cannot determine, and
1782  does not care, that this object is a C struct and not a Perl object.  In
1783  this sense, there is no difference between the object created by the
1784  getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1785  
1786  =head2 The Typemap
1787  
1788  The typemap is a collection of code fragments which are used by the B<xsubpp>
1789  compiler to map C function parameters and values to Perl values.  The
1790  typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
1791  C<OUTPUT>.  An unlabelled initial section is assumed to be a C<TYPEMAP>
1792  section.  The INPUT section tells
1793  the compiler how to translate Perl values
1794  into variables of certain C types.  The OUTPUT section tells the compiler
1795  how to translate the values from certain C types into values Perl can
1796  understand.  The TYPEMAP section tells the compiler which of the INPUT and
1797  OUTPUT code fragments should be used to map a given C type to a Perl value.
1798  The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
1799  in the first column on a line by themselves, and must be in uppercase.
1800  
1801  The default typemap in the C<lib/ExtUtils> directory of the Perl source
1802  contains many useful types which can be used by Perl extensions.  Some
1803  extensions define additional typemaps which they keep in their own directory.
1804  These additional typemaps may reference INPUT and OUTPUT maps in the main
1805  typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
1806  override any mappings which are in the default typemap.
1807  
1808  Most extensions which require a custom typemap will need only the TYPEMAP
1809  section of the typemap file.  The custom typemap used in the
1810  getnetconfigent() example shown earlier demonstrates what may be the typical
1811  use of extension typemaps.  That typemap is used to equate a C structure
1812  with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
1813  here.  Note that the C type is separated from the XS type with a tab and
1814  that the C unary operator C<*> is considered to be a part of the C type name.
1815  
1816      TYPEMAP
1817      Netconfig *<tab>T_PTROBJ
1818  
1819  Here's a more complicated example: suppose that you wanted C<struct
1820  netconfig> to be blessed into the class C<Net::Config>.  One way to do
1821  this is to use underscores (_) to separate package names, as follows:
1822  
1823          typedef struct netconfig * Net_Config;
1824  
1825  And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1826  double-colons (::), and declare C<Net_Config> to be of that type:
1827  
1828  
1829          TYPEMAP
1830          Net_Config      T_PTROBJ_SPECIAL
1831  
1832          INPUT
1833          T_PTROBJ_SPECIAL
1834                  if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1835                          IV tmp = SvIV((SV*)SvRV($arg));
1836                          $var = INT2PTR($type, tmp);
1837                  }
1838                  else
1839                          croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1840  
1841          OUTPUT
1842          T_PTROBJ_SPECIAL
1843                  sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1844                  (void*)$var);
1845  
1846  The INPUT and OUTPUT sections substitute underscores for double-colons
1847  on the fly, giving the desired effect.  This example demonstrates some
1848  of the power and versatility of the typemap facility.
1849  
1850  The INT2PTR macro (defined in perl.h) casts an integer to a pointer, 
1851  of a given type, taking care of the possible different size of integers
1852  and pointers.  There are also PTR2IV, PTR2UV, PTR2NV macros,
1853  to map the other way, which may be useful in OUTPUT sections.
1854  
1855  =head2 Safely Storing Static Data in XS
1856  
1857  Starting with Perl 5.8, a macro framework has been defined to allow
1858  static data to be safely stored in XS modules that will be accessed from
1859  a multi-threaded Perl.
1860  
1861  Although primarily designed for use with multi-threaded Perl, the macros
1862  have been designed so that they will work with non-threaded Perl as well.
1863  
1864  It is therefore strongly recommended that these macros be used by all
1865  XS modules that make use of static data.
1866  
1867  The easiest way to get a template set of macros to use is by specifying
1868  the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
1869  
1870  Below is an example module that makes use of the macros.
1871  
1872      #include "EXTERN.h"
1873      #include "perl.h"
1874      #include "XSUB.h"
1875  
1876      /* Global Data */
1877  
1878      #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1879  
1880      typedef struct {
1881          int count;
1882          char name[3][100];
1883      } my_cxt_t;
1884  
1885      START_MY_CXT
1886  
1887      MODULE = BlindMice           PACKAGE = BlindMice
1888  
1889      BOOT:
1890      {
1891          MY_CXT_INIT;
1892          MY_CXT.count = 0;
1893          strcpy(MY_CXT.name[0], "None");
1894          strcpy(MY_CXT.name[1], "None");
1895          strcpy(MY_CXT.name[2], "None");
1896      }                              
1897  
1898      int
1899      newMouse(char * name)
1900          char * name;
1901          PREINIT:
1902            dMY_CXT;
1903          CODE:
1904            if (MY_CXT.count >= 3) {
1905                warn("Already have 3 blind mice");
1906                RETVAL = 0;
1907            }
1908            else {
1909                RETVAL = ++ MY_CXT.count;
1910                strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1911            }
1912  
1913      char *
1914      get_mouse_name(index)
1915        int index
1916        CODE:
1917          dMY_CXT;
1918          RETVAL = MY_CXT.lives ++;
1919          if (index > MY_CXT.count)
1920            croak("There are only 3 blind mice.");
1921          else
1922            RETVAL = newSVpv(MY_CXT.name[index - 1]);
1923  
1924      void
1925      CLONE(...)
1926      CODE:
1927      MY_CXT_CLONE;
1928  
1929  B<REFERENCE>
1930  
1931  =over 5
1932  
1933  =item MY_CXT_KEY
1934  
1935  This macro is used to define a unique key to refer to the static data
1936  for an XS module. The suggested naming scheme, as used by h2xs, is to
1937  use a string that consists of the module name, the string "::_guts"
1938  and the module version number.
1939  
1940      #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1941  
1942  =item typedef my_cxt_t
1943  
1944  This struct typedef I<must> always be called C<my_cxt_t> -- the other
1945  C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
1946  
1947  Declare a typedef named C<my_cxt_t> that is a structure that contains
1948  all the data that needs to be interpreter-local.
1949  
1950      typedef struct {
1951          int some_value;
1952      } my_cxt_t;
1953  
1954  =item START_MY_CXT
1955  
1956  Always place the START_MY_CXT macro directly after the declaration
1957  of C<my_cxt_t>.
1958  
1959  =item MY_CXT_INIT
1960  
1961  The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
1962  
1963  It I<must> be called exactly once -- typically in a BOOT: section. If you
1964  are maintaining multiple interpreters, it should be called once in each
1965  interpreter instance, except for interpreters cloned from existing ones.
1966  (But see C<MY_CXT_CLONE> below.)
1967  
1968  =item dMY_CXT
1969  
1970  Use the dMY_CXT macro (a declaration) in all the functions that access
1971  MY_CXT.
1972  
1973  =item MY_CXT
1974  
1975  Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
1976  example, if C<my_cxt_t> is 
1977  
1978      typedef struct {
1979          int index;
1980      } my_cxt_t;
1981  
1982  then use this to access the C<index> member
1983  
1984      dMY_CXT;
1985      MY_CXT.index = 2;
1986  
1987  =item aMY_CXT/pMY_CXT
1988  
1989  C<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead
1990  of invoking it in each function it is possible to pass the declaration
1991  onto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg
1992  
1993      void sub1() {
1994      dMY_CXT;
1995      MY_CXT.index = 1;
1996      sub2(aMY_CXT);
1997      }
1998  
1999      void sub2(pMY_CXT) {
2000      MY_CXT.index = 2;
2001      }
2002  
2003  Analogously to C<pTHX>, there are equivalent forms for when the macro is the
2004  first or last in multiple arguments, where an underscore represents a
2005  comma, i.e.  C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>.
2006  
2007  =item MY_CXT_CLONE
2008  
2009  By default, when a new interpreter is created as a copy of an existing one
2010  (eg via C<<threads->create()>>), both interpreters share the same physical
2011  my_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's
2012  C<CLONE()> function), causes a byte-for-byte copy of the structure to be
2013  taken, and any future dMY_CXT will cause the copy to be accessed instead.
2014  
2015  =item MY_CXT_INIT_INTERP(my_perl)
2016  
2017  =item dMY_CXT_INTERP(my_perl)
2018  
2019  These are versions of the macros which take an explicit interpreter as an
2020  argument.
2021  
2022  =back
2023  
2024  Note that these macros will only work together within the I<same> source
2025  file; that is, a dMY_CTX in one source file will access a different structure
2026  than a dMY_CTX in another source file.
2027  
2028  =head2 Thread-aware system interfaces
2029  
2030  Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
2031  system/library interfaces that have thread-aware versions
2032  (e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that
2033  correctly handle the multithreaded interaction with the Perl
2034  interpreter.  This will happen transparently, the only thing
2035  you need to do is to instantiate a Perl interpreter.
2036  
2037  This wrapping happens always when compiling Perl core source
2038  (PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
2039  defined).  When compiling XS code outside of Perl core the wrapping
2040  does not take place.  Note, however, that intermixing the _r-forms
2041  (as Perl compiled for multithreaded operation will do) and the _r-less
2042  forms is neither well-defined (inconsistent results, data corruption,
2043  or even crashes become more likely), nor is it very portable.
2044  
2045  =head1 EXAMPLES
2046  
2047  File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
2048  
2049       #include "EXTERN.h"
2050       #include "perl.h"
2051       #include "XSUB.h"
2052  
2053       #include <rpc/rpc.h>
2054  
2055       typedef struct netconfig Netconfig;
2056  
2057       MODULE = RPC  PACKAGE = RPC
2058  
2059       SV *
2060       rpcb_gettime(host="localhost")
2061            char *host
2062      PREINIT:
2063            time_t  timep;
2064          CODE:
2065            ST(0) = sv_newmortal();
2066            if( rpcb_gettime( host, &timep ) )
2067                 sv_setnv( ST(0), (double)timep );
2068  
2069       Netconfig *
2070       getnetconfigent(netid="udp")
2071            char *netid
2072  
2073       MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
2074  
2075       void
2076       rpcb_DESTROY(netconf)
2077            Netconfig *netconf
2078          CODE:
2079            printf("NetconfigPtr::DESTROY\n");
2080            free( netconf );
2081  
2082  File C<typemap>: Custom typemap for RPC.xs.
2083  
2084       TYPEMAP
2085       Netconfig *  T_PTROBJ
2086  
2087  File C<RPC.pm>: Perl module for the RPC extension.
2088  
2089       package RPC;
2090  
2091       require Exporter;
2092       require DynaLoader;
2093       @ISA = qw(Exporter DynaLoader);
2094       @EXPORT = qw(rpcb_gettime getnetconfigent);
2095  
2096       bootstrap RPC;
2097       1;
2098  
2099  File C<rpctest.pl>: Perl test program for the RPC extension.
2100  
2101       use RPC;
2102  
2103       $netconf = getnetconfigent();
2104       $a = rpcb_gettime();
2105       print "time = $a\n";
2106       print "netconf = $netconf\n";
2107  
2108       $netconf = getnetconfigent("tcp");
2109       $a = rpcb_gettime("poplar");
2110       print "time = $a\n";
2111       print "netconf = $netconf\n";
2112  
2113  
2114  =head1 XS VERSION
2115  
2116  This document covers features supported by C<xsubpp> 1.935.
2117  
2118  =head1 AUTHOR
2119  
2120  Originally written by Dean Roehrich <F<roehrich@cray.com>>.
2121  
2122  Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.