pod/perlxs.pod

   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 declarations 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>>.