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 a language used to create an extension interface
  10 between Perl and some C library which one wishes to use with
  11 Perl.  The XS interface is combined with the library to
  12 create a new library which can be linked to Perl.  An B<XSUB>
  13 is a function in the XS language and is the core component
  14 of the Perl application interface.
  15
  16 The XS compiler is called B<xsubpp>.  This compiler will embed
  17 the constructs necessary to let an XSUB, which is really a C
  18 function in disguise, manipulate Perl values and creates the
  19 glue necessary to let Perl access the XSUB.  The compiler
  20 uses B<typemaps> to determine how to map C function parameters
  21 and variables to Perl values.  The default typemap handles
  22 many common C types.  A supplement typemap must be created
  23 to handle special structures and types for the library being
  24 linked.
  25
  26 See L<perlxstut> for a tutorial on the whole extension creation process.
  27
  28 =head2 On The Road
  29
  30 Many of the examples which follow will concentrate on creating an interface
  31 between Perl and the ONC+ RPC bind library functions.  The rpcb_gettime()
  32 function is used to demonstrate many features of the XS language.  This
  33 function has two parameters; the first is an input parameter and the second
  34 is an output parameter.  The function also returns a status value.
  35
  36         bool_t rpcb_gettime(const char *host, time_t *timep);
  37
  38 From C this function will be called with the following
  39 statements.
  40
  41      #include <rpc/rpc.h>
  42      bool_t status;
  43      time_t timep;
  44      status = rpcb_gettime( "localhost", &timep );
  45
  46 If an XSUB is created to offer a direct translation between this function
  47 and Perl, then this XSUB will be used from Perl with the following code.
  48 The $status and $timep variables will contain the output of the function.
  49
  50      use RPC;
  51      $status = rpcb_gettime( "localhost", $timep );
  52
  53 The following XS file shows an XS subroutine, or XSUB, which
  54 demonstrates one possible interface to the rpcb_gettime()
  55 function.  This XSUB represents a direct translation between
  56 C and Perl and so preserves the interface even from Perl.
  57 This XSUB will be invoked from Perl with the usage shown
  58 above.  Note that the first three #include statements, for
  59 C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
  60 beginning of an XS file.  This approach and others will be
  61 expanded later in this document.
  62
  63      #include "EXTERN.h"
  64      #include "perl.h"
  65      #include "XSUB.h"
  66      #include <rpc/rpc.h>
  67
  68      MODULE = RPC  PACKAGE = RPC
  69
  70      bool_t
  71      rpcb_gettime(host,timep)
  72           char *host
  73           time_t &timep
  74           OUTPUT:
  75           timep
  76
  77 Any extension to Perl, including those containing XSUBs,
  78 should have a Perl module to serve as the bootstrap which
  79 pulls the extension into Perl.  This module will export the
  80 extension's functions and variables to the Perl program and
  81 will cause the extension's XSUBs to be linked into Perl.
  82 The following module will be used for most of the examples
  83 in this document and should be used from Perl with the C<use>
  84 command as shown earlier.  Perl modules are explained in
  85 more detail later in this document.
  86
  87      package RPC;
  88
  89      require Exporter;
  90      require DynaLoader;
  91      @ISA = qw(Exporter DynaLoader);
  92      @EXPORT = qw( rpcb_gettime );
  93
  94      bootstrap RPC;
  95      1;
  96
  97 Throughout this document a variety of interfaces to the rpcb_gettime()
  98 XSUB will be explored.  The XSUBs will take their parameters in different
  99 orders or will take different numbers of parameters.  In each case the
 100 XSUB is an abstraction between Perl and the real C rpcb_gettime()
 101 function, and the XSUB must always ensure that the real rpcb_gettime()
 102 function is called with the correct parameters.  This abstraction will
 103 allow the programmer to create a more Perl-like interface to the C
 104 function.
 105
 106 =head2 The Anatomy of an XSUB
 107
 108 The following XSUB allows a Perl program to access a C library function
 109 called sin().  The XSUB will imitate the C function which takes a single
 110 argument and returns a single value.
 111
 112      double
 113      sin(x)
 114        double x
 115
 116 When using C pointers the indirection operator C<*> should be considered
 117 part of the type and the address operator C<&> should be considered part of
 118 the variable, as is demonstrated in the rpcb_gettime() function above.  See
 119 the section on typemaps for more about handling qualifiers and unary
 120 operators in C types.
 121
 122 The function name and the return type must be placed on
 123 separate lines.
 124
 125   INCORRECT                        CORRECT
 126
 127   double sin(x)                    double
 128     double x                       sin(x)
 129                                      double x
 130
 131 The function body may be indented or left-adjusted.  The following example
 132 shows a function with its body left-adjusted.  Most examples in this
 133 document will indent the body.
 134
 135   CORRECT
 136
 137   double
 138   sin(x)
 139   double x
 140
 141 =head2 The Argument Stack
 142
 143 The argument stack is used to store the values which are
 144 sent as parameters to the XSUB and to store the XSUB's
 145 return value.  In reality all Perl functions keep their
 146 values on this stack at the same time, each limited to its
 147 own range of positions on the stack.  In this document the
 148 first position on that stack which belongs to the active
 149 function will be referred to as position 0 for that function.
 150
 151 XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
 152 refers to a position in this XSUB's part of the stack.  Position 0 for that
 153 function would be known to the XSUB as ST(0).  The XSUB's incoming
 154 parameters and outgoing return values always begin at ST(0).  For many
 155 simple cases the B<xsubpp> compiler will generate the code necessary to
 156 handle the argument stack by embedding code fragments found in the
 157 typemaps.  In more complex cases the programmer must supply the code.
 158
 159 =head2 The RETVAL Variable
 160
 161 The RETVAL variable is a magic variable which always matches
 162 the return type of the C library function.  The B<xsubpp> compiler will
 163 supply this variable in each XSUB and by default will use it to hold the
 164 return value of the C library function being called.  In simple cases the
 165 value of RETVAL will be placed in ST(0) of the argument stack where it can
 166 be received by Perl as the return value of the XSUB.
 167
 168 If the XSUB has a return type of C<void> then the compiler will
 169 not supply a RETVAL variable for that function.  When using
 170 the PPCODE: directive the RETVAL variable is not needed, unless used
 171 explicitly.
 172
 173 If PPCODE: directive is not used, C<void> return value should be used
 174 only for subroutines which do not return a value, I<even if> CODE:
 175 directive is used which sets ST(0) explicitly.
 176
 177 Older versions of this document recommended to use C<void> return
 178 value in such cases. It was discovered that this could lead to
 179 segfaults in cases when XSUB was I<truely> C<void>. This practice is
 180 now deprecated, and may be not supported at some future version. Use
 181 the return value C<SV *> in such cases. (Currently C<xsubpp> contains
 182 some heuristic code which tries to disambiguate between "truely-void"
 183 and "old-practice-declared-as-void" functions. Hence your code is at
 184 mercy of this heuristics unless you use C<SV *> as return value.)
 185
 186 =head2 The MODULE Keyword
 187
 188 The MODULE keyword is used to start the XS code and to
 189 specify the package of the functions which are being
 190 defined.  All text preceding the first MODULE keyword is
 191 considered C code and is passed through to the output
 192 untouched.  Every XS module will have a bootstrap function
 193 which is used to hook the XSUBs into Perl.  The package name
 194 of this bootstrap function will match the value of the last
 195 MODULE statement in the XS source files.  The value of
 196 MODULE should always remain constant within the same XS
 197 file, though this is not required.
 198
 199 The following example will start the XS code and will place
 200 all functions in a package named RPC.
 201
 202      MODULE = RPC
 203
 204 =head2 The PACKAGE Keyword
 205
 206 When functions within an XS source file must be separated into packages
 207 the PACKAGE keyword should be used.  This keyword is used with the MODULE
 208 keyword and must follow immediately after it when used.
 209
 210      MODULE = RPC  PACKAGE = RPC
 211
 212      [ XS code in package RPC ]
 213
 214      MODULE = RPC  PACKAGE = RPCB
 215
 216      [ XS code in package RPCB ]
 217
 218      MODULE = RPC  PACKAGE = RPC
 219
 220      [ XS code in package RPC ]
 221
 222 Although this keyword is optional and in some cases provides redundant
 223 information it should always be used.  This keyword will ensure that the
 224 XSUBs appear in the desired package.
 225
 226 =head2 The PREFIX Keyword
 227
 228 The PREFIX keyword designates prefixes which should be
 229 removed from the Perl function names.  If the C function is
 230 C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
 231 see this function as C<gettime()>.
 232
 233 This keyword should follow the PACKAGE keyword when used.
 234 If PACKAGE is not used then PREFIX should follow the MODULE
 235 keyword.
 236
 237      MODULE = RPC  PREFIX = rpc_
 238
 239      MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
 240
 241 =head2 The OUTPUT: Keyword
 242
 243 The OUTPUT: keyword indicates that certain function parameters should be
 244 updated (new values made visible to Perl) when the XSUB terminates or that
 245 certain values should be returned to the calling Perl function.  For
 246 simple functions, such as the sin() function above, the RETVAL variable is
 247 automatically designated as an output value.  In more complex functions
 248 the B<xsubpp> compiler will need help to determine which variables are output
 249 variables.
 250
 251 This keyword will normally be used to complement the CODE:  keyword.
 252 The RETVAL variable is not recognized as an output variable when the
 253 CODE: keyword is present.  The OUTPUT:  keyword is used in this
 254 situation to tell the compiler that RETVAL really is an output
 255 variable.
 256
 257 The OUTPUT: keyword can also be used to indicate that function parameters
 258 are output variables.  This may be necessary when a parameter has been
 259 modified within the function and the programmer would like the update to
 260 be seen by Perl.
 261
 262      bool_t
 263      rpcb_gettime(host,timep)
 264           char *host
 265           time_t &timep
 266           OUTPUT:
 267           timep
 268
 269 The OUTPUT: keyword will also allow an output parameter to
 270 be mapped to a matching piece of code rather than to a
 271 typemap.
 272
 273      bool_t
 274      rpcb_gettime(host,timep)
 275           char *host
 276           time_t &timep
 277           OUTPUT:
 278           timep sv_setnv(ST(1), (double)timep);
 279
 280 B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
 281 OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
 282 behavior, as it takes care of properly invoking 'set' magic on output
 283 parameters (needed for hash or array element parameters that must be
 284 created if they didn't exist).  If for some reason, this behavior is
 285 not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
 286 to disable it for the remainder of the parameters in the OUTPUT section.
 287 Likewise,  C<SETMAGIC: ENABLE> can be used to reenable it for the
 288 remainder of the OUTPUT section.  See L<perlguts> for more details
 289 about 'set' magic.
 290
 291 =head2 The CODE: Keyword
 292
 293 This keyword is used in more complicated XSUBs which require
 294 special handling for the C function.  The RETVAL variable is
 295 available but will not be returned unless it is specified
 296 under the OUTPUT: keyword.
 297
 298 The following XSUB is for a C function which requires special handling of
 299 its parameters.  The Perl usage is given first.
 300
 301      $status = rpcb_gettime( "localhost", $timep );
 302
 303 The XSUB follows.
 304
 305      bool_t
 306      rpcb_gettime(host,timep)
 307           char *host
 308           time_t timep
 309           CODE:
 310                RETVAL = rpcb_gettime( host, &timep );
 311           OUTPUT:
 312           timep
 313           RETVAL
 314
 315 =head2 The INIT: Keyword
 316
 317 The INIT: keyword allows initialization to be inserted into the XSUB before
 318 the compiler generates the call to the C function.  Unlike the CODE: keyword
 319 above, this keyword does not affect the way the compiler handles RETVAL.
 320
 321     bool_t
 322     rpcb_gettime(host,timep)
 323           char *host
 324           time_t &timep
 325           INIT:
 326           printf("# Host is %s\n", host );
 327           OUTPUT:
 328           timep
 329
 330 =head2 The NO_INIT Keyword
 331
 332 The NO_INIT keyword is used to indicate that a function
 333 parameter is being used only as an output value.  The B<xsubpp>
 334 compiler will normally generate code to read the values of
 335 all function parameters from the argument stack and assign
 336 them to C variables upon entry to the function.  NO_INIT
 337 will tell the compiler that some parameters will be used for
 338 output rather than for input and that they will be handled
 339 before the function terminates.
 340
 341 The following example shows a variation of the rpcb_gettime() function.
 342 This function uses the timep variable only as an output variable and does
 343 not care about its initial contents.
 344
 345      bool_t
 346      rpcb_gettime(host,timep)
 347           char *host
 348           time_t &timep = NO_INIT
 349           OUTPUT:
 350           timep
 351
 352 =head2 Initializing Function Parameters
 353
 354 Function parameters are normally initialized with their
 355 values from the argument stack.  The typemaps contain the
 356 code segments which are used to transfer the Perl values to
 357 the C parameters.  The programmer, however, is allowed to
 358 override the typemaps and supply alternate initialization
 359 code.
 360
 361 The following code demonstrates how to supply initialization code for
 362 function parameters.  The initialization code is eval'd by the compiler
 363 before it is added to the output so anything which should be interpreted
 364 literally, such as double quotes, must be protected with backslashes.
 365
 366      bool_t
 367      rpcb_gettime(host,timep)
 368           char *host = (char *)SvPV(ST(0),na);
 369           time_t &timep = 0;
 370           OUTPUT:
 371           timep
 372
 373 This should not be used to supply default values for parameters.  One
 374 would normally use this when a function parameter must be processed by
 375 another library function before it can be used.  Default parameters are
 376 covered in the next section.
 377
 378 =head2 Default Parameter Values
 379
 380 Default values can be specified for function parameters by
 381 placing an assignment statement in the parameter list.  The
 382 default value may be a number or a string.  Defaults should
 383 always be used on the right-most parameters only.
 384
 385 To allow the XSUB for rpcb_gettime() to have a default host
 386 value the parameters to the XSUB could be rearranged.  The
 387 XSUB will then call the real rpcb_gettime() function with
 388 the parameters in the correct order.  Perl will call this
 389 XSUB with either of the following statements.
 390
 391      $status = rpcb_gettime( $timep, $host );
 392
 393      $status = rpcb_gettime( $timep );
 394
 395 The XSUB will look like the code  which  follows.   A  CODE:
 396 block  is used to call the real rpcb_gettime() function with
 397 the parameters in the correct order for that function.
 398
 399      bool_t
 400      rpcb_gettime(timep,host="localhost")
 401           char *host
 402           time_t timep = NO_INIT
 403           CODE:
 404                RETVAL = rpcb_gettime( host, &timep );
 405           OUTPUT:
 406           timep
 407           RETVAL
 408
 409 =head2 The PREINIT: Keyword
 410
 411 The PREINIT: keyword allows extra variables to be declared before the
 412 typemaps are expanded.  If a variable is declared in a CODE: block then that
 413 variable will follow any typemap code.  This may result in a C syntax
 414 error.  To force the variable to be declared before the typemap code, place
 415 it into a PREINIT: block.  The PREINIT: keyword may be used one or more
 416 times within an XSUB.
 417
 418 The following examples are equivalent, but if the code is using complex
 419 typemaps then the first example is safer.
 420
 421      bool_t
 422      rpcb_gettime(timep)
 423           time_t timep = NO_INIT
 424           PREINIT:
 425           char *host = "localhost";
 426           CODE:
 427           RETVAL = rpcb_gettime( host, &timep );
 428           OUTPUT:
 429           timep
 430           RETVAL
 431
 432 A correct, but error-prone example.
 433
 434      bool_t
 435      rpcb_gettime(timep)
 436           time_t timep = NO_INIT
 437           CODE:
 438           char *host = "localhost";
 439           RETVAL = rpcb_gettime( host, &timep );
 440           OUTPUT:
 441           timep
 442           RETVAL
 443
 444 =head2 The SCOPE: Keyword
 445
 446 The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
 447 enabled, the XSUB will invoke ENTER and LEAVE automatically.
 448
 449 To support potentially complex type mappings, if a typemap entry used
 450 by this XSUB contains a comment like C</*scope*/> then scoping will
 451 automatically be enabled for that XSUB.
 452
 453 To enable scoping:
 454
 455     SCOPE: ENABLE
 456
 457 To disable scoping:
 458
 459     SCOPE: DISABLE
 460
 461 =head2 The INPUT: Keyword
 462
 463 The XSUB's parameters are usually evaluated immediately after entering the
 464 XSUB.  The INPUT: keyword can be used to force those parameters to be
 465 evaluated a little later.  The INPUT: keyword can be used multiple times
 466 within an XSUB and can be used to list one or more input variables.  This
 467 keyword is used with the PREINIT: keyword.
 468
 469 The following example shows how the input parameter C<timep> can be
 470 evaluated late, after a PREINIT.
 471
 472     bool_t
 473     rpcb_gettime(host,timep)
 474           char *host
 475           PREINIT:
 476           time_t tt;
 477           INPUT:
 478           time_t timep
 479           CODE:
 480                RETVAL = rpcb_gettime( host, &tt );
 481                timep = tt;
 482           OUTPUT:
 483           timep
 484           RETVAL
 485
 486 The next example shows each input parameter evaluated late.
 487
 488     bool_t
 489     rpcb_gettime(host,timep)
 490           PREINIT:
 491           time_t tt;
 492           INPUT:
 493           char *host
 494           PREINIT:
 495           char *h;
 496           INPUT:
 497           time_t timep
 498           CODE:
 499                h = host;
 500                RETVAL = rpcb_gettime( h, &tt );
 501                timep = tt;
 502           OUTPUT:
 503           timep
 504           RETVAL
 505
 506 =head2 Variable-length Parameter Lists
 507
 508 XSUBs can have variable-length parameter lists by specifying an ellipsis
 509 C<(...)> in the parameter list.  This use of the ellipsis is similar to that
 510 found in ANSI C.  The programmer is able to determine the number of
 511 arguments passed to the XSUB by examining the C<items> variable which the
 512 B<xsubpp> compiler supplies for all XSUBs.  By using this mechanism one can
 513 create an XSUB which accepts a list of parameters of unknown length.
 514
 515 The I<host> parameter for the rpcb_gettime() XSUB can be
 516 optional so the ellipsis can be used to indicate that the
 517 XSUB will take a variable number of parameters.  Perl should
 518 be able to call this XSUB with either of the following statements.
 519
 520      $status = rpcb_gettime( $timep, $host );
 521
 522      $status = rpcb_gettime( $timep );
 523
 524 The XS code, with ellipsis, follows.
 525
 526      bool_t
 527      rpcb_gettime(timep, ...)
 528           time_t timep = NO_INIT
 529           PREINIT:
 530           char *host = "localhost";
 531           CODE:
 532                   if( items > 1 )
 533                        host = (char *)SvPV(ST(1), na);
 534                   RETVAL = rpcb_gettime( host, &timep );
 535           OUTPUT:
 536           timep
 537           RETVAL
 538
 539 =head2 The PPCODE: Keyword
 540
 541 The PPCODE: keyword is an alternate form of the CODE: keyword and is used
 542 to tell the B<xsubpp> compiler that the programmer is supplying the code to
 543 control the argument stack for the XSUBs return values.  Occasionally one
 544 will want an XSUB to return a list of values rather than a single value.
 545 In these cases one must use PPCODE: and then explicitly push the list of
 546 values on the stack.  The PPCODE: and CODE:  keywords are not used
 547 together within the same XSUB.
 548
 549 The following XSUB will call the C rpcb_gettime() function
 550 and will return its two output values, timep and status, to
 551 Perl as a single list.
 552
 553      void
 554      rpcb_gettime(host)
 555           char *host
 556           PREINIT:
 557           time_t  timep;
 558           bool_t  status;
 559           PPCODE:
 560           status = rpcb_gettime( host, &timep );
 561           EXTEND(SP, 2);
 562           PUSHs(sv_2mortal(newSViv(status)));
 563           PUSHs(sv_2mortal(newSViv(timep)));
 564
 565 Notice that the programmer must supply the C code necessary
 566 to have the real rpcb_gettime() function called and to have
 567 the return values properly placed on the argument stack.
 568
 569 The C<void> return type for this function tells the B<xsubpp> compiler that
 570 the RETVAL variable is not needed or used and that it should not be created.
 571 In most scenarios the void return type should be used with the PPCODE:
 572 directive.
 573
 574 The EXTEND() macro is used to make room on the argument
 575 stack for 2 return values.  The PPCODE: directive causes the
 576 B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
 577 is this pointer which is being used in the EXTEND() macro.
 578 The values are then pushed onto the stack with the PUSHs()
 579 macro.
 580
 581 Now the rpcb_gettime() function can be used from Perl with
 582 the following statement.
 583
 584      ($status, $timep) = rpcb_gettime("localhost");
 585
 586 When handling output parameters with a PPCODE section, be sure to handle
 587 'set' magic properly.  See L<perlguts> for details about 'set' magic.
 588
 589 =head2 Returning Undef And Empty Lists
 590
 591 Occasionally the programmer will want to return simply
 592 C<undef> or an empty list if a function fails rather than a
 593 separate status value.  The rpcb_gettime() function offers
 594 just this situation.  If the function succeeds we would like
 595 to have it return the time and if it fails we would like to
 596 have undef returned.  In the following Perl code the value
 597 of $timep will either be undef or it will be a valid time.
 598
 599      $timep = rpcb_gettime( "localhost" );
 600
 601 The following XSUB uses the C<SV *> return type as a mneumonic only,
 602 and uses a CODE: block to indicate to the compiler
 603 that the programmer has supplied all the necessary code.  The
 604 sv_newmortal() call will initialize the return value to undef, making that
 605 the default return value.
 606
 607      SV *
 608      rpcb_gettime(host)
 609           char *  host
 610           PREINIT:
 611           time_t  timep;
 612           bool_t x;
 613           CODE:
 614           ST(0) = sv_newmortal();
 615           if( rpcb_gettime( host, &timep ) )
 616                sv_setnv( ST(0), (double)timep);
 617
 618 The next example demonstrates how one would place an explicit undef in the
 619 return value, should the need arise.
 620
 621      SV *
 622      rpcb_gettime(host)
 623           char *  host
 624           PREINIT:
 625           time_t  timep;
 626           bool_t x;
 627           CODE:
 628           ST(0) = sv_newmortal();
 629           if( rpcb_gettime( host, &timep ) ){
 630                sv_setnv( ST(0), (double)timep);
 631           }
 632           else{
 633                ST(0) = &sv_undef;
 634           }
 635
 636 To return an empty list one must use a PPCODE: block and
 637 then not push return values on the stack.
 638
 639      void
 640      rpcb_gettime(host)
 641           char *host
 642           PREINIT:
 643           time_t  timep;
 644           PPCODE:
 645           if( rpcb_gettime( host, &timep ) )
 646                PUSHs(sv_2mortal(newSViv(timep)));
 647           else{
 648           /* Nothing pushed on stack, so an empty */
 649           /* list is implicitly returned. */
 650           }
 651
 652 Some people may be inclined to include an explicit C<return> in the above
 653 XSUB, rather than letting control fall through to the end.  In those
 654 situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that
 655 the XSUB stack is properly adjusted.  Consult L<perlguts/"API LISTING"> for
 656 other C<XSRETURN> macros.
 657
 658 =head2 The REQUIRE: Keyword
 659
 660 The REQUIRE: keyword is used to indicate the minimum version of the
 661 B<xsubpp> compiler needed to compile the XS module.  An XS module which
 662 contains the following statement will compile with only B<xsubpp> version
 663 1.922 or greater:
 664
 665         REQUIRE: 1.922
 666
 667 =head2 The CLEANUP: Keyword
 668
 669 This keyword can be used when an XSUB requires special cleanup procedures
 670 before it terminates.  When the CLEANUP:  keyword is used it must follow
 671 any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB.  The
 672 code specified for the cleanup block will be added as the last statements
 673 in the XSUB.
 674
 675 =head2 The BOOT: Keyword
 676
 677 The BOOT: keyword is used to add code to the extension's bootstrap
 678 function.  The bootstrap function is generated by the B<xsubpp> compiler and
 679 normally holds the statements necessary to register any XSUBs with Perl.
 680 With the BOOT: keyword the programmer can tell the compiler to add extra
 681 statements to the bootstrap function.
 682
 683 This keyword may be used any time after the first MODULE keyword and should
 684 appear on a line by itself.  The first blank line after the keyword will
 685 terminate the code block.
 686
 687      BOOT:
 688      # The following message will be printed when the
 689      # bootstrap function executes.
 690      printf("Hello from the bootstrap!\n");
 691
 692 =head2 The VERSIONCHECK: Keyword
 693
 694 The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
 695 C<-noversioncheck> options.  This keyword overrides the command line
 696 options.  Version checking is enabled by default.  When version checking is
 697 enabled the XS module will attempt to verify that its version matches the
 698 version of the PM module.
 699
 700 To enable version checking:
 701
 702     VERSIONCHECK: ENABLE
 703
 704 To disable version checking:
 705
 706     VERSIONCHECK: DISABLE
 707
 708 =head2 The PROTOTYPES: Keyword
 709
 710 The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
 711 C<-noprototypes> options.  This keyword overrides the command line options.
 712 Prototypes are enabled by default.  When prototypes are enabled XSUBs will
 713 be given Perl prototypes.  This keyword may be used multiple times in an XS
 714 module to enable and disable prototypes for different parts of the module.
 715
 716 To enable prototypes:
 717
 718     PROTOTYPES: ENABLE
 719
 720 To disable prototypes:
 721
 722     PROTOTYPES: DISABLE
 723
 724 =head2 The PROTOTYPE: Keyword
 725
 726 This keyword is similar to the PROTOTYPES: keyword above but can be used to
 727 force B<xsubpp> to use a specific prototype for the XSUB.  This keyword
 728 overrides all other prototype options and keywords but affects only the
 729 current XSUB.  Consult L<perlsub/Prototypes> for information about Perl
 730 prototypes.
 731
 732     bool_t
 733     rpcb_gettime(timep, ...)
 734           time_t timep = NO_INIT
 735           PROTOTYPE: $;$
 736           PREINIT:
 737           char *host = "localhost";
 738           CODE:
 739                   if( items > 1 )
 740                        host = (char *)SvPV(ST(1), na);
 741                   RETVAL = rpcb_gettime( host, &timep );
 742           OUTPUT:
 743           timep
 744           RETVAL
 745
 746 =head2 The ALIAS: Keyword
 747
 748 The ALIAS: keyword allows an XSUB to have two more unique Perl names
 749 and to know which of those names was used when it was invoked.  The Perl
 750 names may be fully-qualified with package names.  Each alias is given an
 751 index.  The compiler will setup a variable called C<ix> which contain the
 752 index of the alias which was used.  When the XSUB is called with its
 753 declared name C<ix> will be 0.
 754
 755 The following example will create aliases C<FOO::gettime()> and
 756 C<BAR::getit()> for this function.
 757
 758     bool_t
 759     rpcb_gettime(host,timep)
 760           char *host
 761           time_t &timep
 762           ALIAS:
 763             FOO::gettime = 1
 764             BAR::getit = 2
 765           INIT:
 766           printf("# ix = %d\n", ix );
 767           OUTPUT:
 768           timep
 769
 770 =head2 The INCLUDE: Keyword
 771
 772 This keyword can be used to pull other files into the XS module.  The other
 773 files may have XS code.  INCLUDE: can also be used to run a command to
 774 generate the XS code to be pulled into the module.
 775
 776 The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
 777
 778     bool_t
 779     rpcb_gettime(host,timep)
 780           char *host
 781           time_t &timep
 782           OUTPUT:
 783           timep
 784
 785 The XS module can use INCLUDE: to pull that file into it.
 786
 787     INCLUDE: Rpcb1.xsh
 788
 789 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
 790 the compiler will interpret the parameters as a command.
 791
 792     INCLUDE: cat Rpcb1.xsh |
 793
 794 =head2 The CASE: Keyword
 795
 796 The CASE: keyword allows an XSUB to have multiple distinct parts with each
 797 part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
 798 other XS keywords must be contained within a CASE:.  This means nothing may
 799 precede the first CASE: in the XSUB and anything following the last CASE: is
 800 included in that case.
 801
 802 A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
 803 variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
 804 (see L<"Variable-length Parameter Lists">).  The last CASE: becomes the
 805 B<default> case if it is not associated with a conditional.  The following
 806 example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
 807 having an alias C<x_gettime()>.  When the function is called as
 808 C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
 809 but when the function is called as C<x_gettime()> its parameters are
 810 reversed, C<(time_t *timep, char *host)>.
 811
 812     long
 813     rpcb_gettime(a,b)
 814       CASE: ix == 1
 815           ALIAS:
 816           x_gettime = 1
 817           INPUT:
 818           # 'a' is timep, 'b' is host
 819           char *b
 820           time_t a = NO_INIT
 821           CODE:
 822                RETVAL = rpcb_gettime( b, &a );
 823           OUTPUT:
 824           a
 825           RETVAL
 826       CASE:
 827           # 'a' is host, 'b' is timep
 828           char *a
 829           time_t &b = NO_INIT
 830           OUTPUT:
 831           b
 832           RETVAL
 833
 834 That function can be called with either of the following statements.  Note
 835 the different argument lists.
 836
 837         $status = rpcb_gettime( $host, $timep );
 838
 839         $status = x_gettime( $timep, $host );
 840
 841 =head2 The & Unary Operator
 842
 843 The & unary operator is used to tell the compiler that it should dereference
 844 the object when it calls the C function.  This is used when a CODE: block is
 845 not used and the object is a not a pointer type (the object is an C<int> or
 846 C<long> but not a C<int*> or C<long*>).
 847
 848 The following XSUB will generate incorrect C code.  The xsubpp compiler will
 849 turn this into code which calls C<rpcb_gettime()> with parameters C<(char
 850 *host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
 851 parameter to be of type C<time_t*> rather than C<time_t>.
 852
 853     bool_t
 854     rpcb_gettime(host,timep)
 855           char *host
 856           time_t timep
 857           OUTPUT:
 858           timep
 859
 860 That problem is corrected by using the C<&> operator.  The xsubpp compiler
 861 will now turn this into code which calls C<rpcb_gettime()> correctly with
 862 parameters C<(char *host, time_t *timep)>.  It does this by carrying the
 863 C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
 864
 865     bool_t
 866     rpcb_gettime(host,timep)
 867           char *host
 868           time_t &timep
 869           OUTPUT:
 870           timep
 871
 872 =head2 Inserting Comments and C Preprocessor Directives
 873
 874 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
 875 CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
 876 Comments are allowed anywhere after the MODULE keyword.  The compiler
 877 will pass the preprocessor directives through untouched and will remove
 878 the commented lines.
 879
 880 Comments can be added to XSUBs by placing a C<#> as the first
 881 non-whitespace of a line.  Care should be taken to avoid making the
 882 comment look like a C preprocessor directive, lest it be interpreted as
 883 such.  The simplest way to prevent this is to put whitespace in front of
 884 the C<#>.
 885
 886 If you use preprocessor directives to choose one of two
 887 versions of a function, use
 888
 889     #if ... version1
 890     #else /* ... version2  */
 891     #endif
 892
 893 and not
 894
 895     #if ... version1
 896     #endif
 897     #if ... version2
 898     #endif
 899
 900 because otherwise xsubpp will believe that you made a duplicate
 901 definition of the function.  Also, put a blank line before the
 902 #else/#endif so it will not be seen as part of the function body.
 903
 904 =head2 Using XS With C++
 905
 906 If a function is defined as a C++ method then it will assume
 907 its first argument is an object pointer.  The object pointer
 908 will be stored in a variable called THIS.  The object should
 909 have been created by C++ with the new() function and should
 910 be blessed by Perl with the sv_setref_pv() macro.  The
 911 blessing of the object by Perl can be handled by a typemap.  An example
 912 typemap is shown at the end of this section.
 913
 914 If the method is defined as static it will call the C++
 915 function using the class::method() syntax.  If the method is not static
 916 the function will be called using the THIS-E<gt>method() syntax.
 917
 918 The next examples will use the following C++ class.
 919
 920      class color {
 921           public:
 922           color();
 923           ~color();
 924           int blue();
 925           void set_blue( int );
 926
 927           private:
 928           int c_blue;
 929      };
 930
 931 The XSUBs for the blue() and set_blue() methods are defined with the class
 932 name but the parameter for the object (THIS, or "self") is implicit and is
 933 not listed.
 934
 935      int
 936      color::blue()
 937
 938      void
 939      color::set_blue( val )
 940           int val
 941
 942 Both functions will expect an object as the first parameter.  The xsubpp
 943 compiler will call that object C<THIS> and will use it to call the specified
 944 method.  So in the C++ code the blue() and set_blue() methods will be called
 945 in the following manner.
 946
 947      RETVAL = THIS->blue();
 948
 949      THIS->set_blue( val );
 950
 951 If the function's name is B<DESTROY> then the C++ C<delete> function will be
 952 called and C<THIS> will be given as its parameter.
 953
 954      void
 955      color::DESTROY()
 956
 957 The C++ code will call C<delete>.
 958
 959      delete THIS;
 960
 961 If the function's name is B<new> then the C++ C<new> function will be called
 962 to create a dynamic C++ object.  The XSUB will expect the class name, which
 963 will be kept in a variable called C<CLASS>, to be given as the first
 964 argument.
 965
 966      color *
 967      color::new()
 968
 969 The C++ code will call C<new>.
 970
 971         RETVAL = new color();
 972
 973 The following is an example of a typemap that could be used for this C++
 974 example.
 975
 976     TYPEMAP
 977     color *             O_OBJECT
 978
 979     OUTPUT
 980     # The Perl object is blessed into 'CLASS', which should be a
 981     # char* having the name of the package for the blessing.
 982     O_OBJECT
 983         sv_setref_pv( $arg, CLASS, (void*)$var );
 984
 985     INPUT
 986     O_OBJECT
 987         if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
 988                 $var = ($type)SvIV((SV*)SvRV( $arg ));
 989         else{
 990                 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
 991                 XSRETURN_UNDEF;
 992         }
 993
 994 =head2 Interface Strategy
 995
 996 When designing an interface between Perl and a C library a straight
 997 translation from C to XS is often sufficient.  The interface will often be
 998 very C-like and occasionally nonintuitive, especially when the C function
 999 modifies one of its parameters.  In cases where the programmer wishes to
1000 create a more Perl-like interface the following strategy may help to
1001 identify the more critical parts of the interface.
1002
1003 Identify the C functions which modify their parameters.  The XSUBs for
1004 these functions may be able to return lists to Perl, or may be
1005 candidates to return undef or an empty list in case of failure.
1006
1007 Identify which values are used by only the C and XSUB functions
1008 themselves.  If Perl does not need to access the contents of the value
1009 then it may not be necessary to provide a translation for that value
1010 from C to Perl.
1011
1012 Identify the pointers in the C function parameter lists and return
1013 values.  Some pointers can be handled in XS with the & unary operator on
1014 the variable name while others will require the use of the * operator on
1015 the type name.  In general it is easier to work with the & operator.
1016
1017 Identify the structures used by the C functions.  In many
1018 cases it may be helpful to use the T_PTROBJ typemap for
1019 these structures so they can be manipulated by Perl as
1020 blessed objects.
1021
1022 =head2 Perl Objects And C Structures
1023
1024 When dealing with C structures one should select either
1025 B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
1026 designed to handle pointers to complex objects.  The
1027 T_PTRREF type will allow the Perl object to be unblessed
1028 while the T_PTROBJ type requires that the object be blessed.
1029 By using T_PTROBJ one can achieve a form of type-checking
1030 because the XSUB will attempt to verify that the Perl object
1031 is of the expected type.
1032
1033 The following XS code shows the getnetconfigent() function which is used
1034 with ONC+ TIRPC.  The getnetconfigent() function will return a pointer to a
1035 C structure and has the C prototype shown below.  The example will
1036 demonstrate how the C pointer will become a Perl reference.  Perl will
1037 consider this reference to be a pointer to a blessed object and will
1038 attempt to call a destructor for the object.  A destructor will be
1039 provided in the XS source to free the memory used by getnetconfigent().
1040 Destructors in XS can be created by specifying an XSUB function whose name
1041 ends with the word B<DESTROY>.  XS destructors can be used to free memory
1042 which may have been malloc'd by another XSUB.
1043
1044      struct netconfig *getnetconfigent(const char *netid);
1045
1046 A C<typedef> will be created for C<struct netconfig>.  The Perl
1047 object will be blessed in a class matching the name of the C
1048 type, with the tag C<Ptr> appended, and the name should not
1049 have embedded spaces if it will be a Perl package name.  The
1050 destructor will be placed in a class corresponding to the
1051 class of the object and the PREFIX keyword will be used to
1052 trim the name to the word DESTROY as Perl will expect.
1053
1054      typedef struct netconfig Netconfig;
1055
1056      MODULE = RPC  PACKAGE = RPC
1057
1058      Netconfig *
1059      getnetconfigent(netid)
1060           char *netid
1061
1062      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1063
1064      void
1065      rpcb_DESTROY(netconf)
1066           Netconfig *netconf
1067           CODE:
1068           printf("Now in NetconfigPtr::DESTROY\n");
1069           free( netconf );
1070
1071 This example requires the following typemap entry.  Consult the typemap
1072 section for more information about adding new typemaps for an extension.
1073
1074      TYPEMAP
1075      Netconfig *  T_PTROBJ
1076
1077 This example will be used with the following Perl statements.
1078
1079      use RPC;
1080      $netconf = getnetconfigent("udp");
1081
1082 When Perl destroys the object referenced by $netconf it will send the
1083 object to the supplied XSUB DESTROY function.  Perl cannot determine, and
1084 does not care, that this object is a C struct and not a Perl object.  In
1085 this sense, there is no difference between the object created by the
1086 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1087
1088 =head2 The Typemap
1089
1090 The typemap is a collection of code fragments which are used by the B<xsubpp>
1091 compiler to map C function parameters and values to Perl values.  The
1092 typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
1093 C<OUTPUT>.  The INPUT section tells the compiler how to translate Perl values
1094 into variables of certain C types.  The OUTPUT section tells the compiler
1095 how to translate the values from certain C types into values Perl can
1096 understand.  The TYPEMAP section tells the compiler which of the INPUT and
1097 OUTPUT code fragments should be used to map a given C type to a Perl value.
1098 Each of the sections of the typemap must be preceded by one of the TYPEMAP,
1099 INPUT, or OUTPUT keywords.
1100
1101 The default typemap in the C<ext> directory of the Perl source contains many
1102 useful types which can be used by Perl extensions.  Some extensions define
1103 additional typemaps which they keep in their own directory.  These
1104 additional typemaps may reference INPUT and OUTPUT maps in the main
1105 typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
1106 override any mappings which are in the default typemap.
1107
1108 Most extensions which require a custom typemap will need only the TYPEMAP
1109 section of the typemap file.  The custom typemap used in the
1110 getnetconfigent() example shown earlier demonstrates what may be the typical
1111 use of extension typemaps.  That typemap is used to equate a C structure
1112 with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
1113 here.  Note that the C type is separated from the XS type with a tab and
1114 that the C unary operator C<*> is considered to be a part of the C type name.
1115
1116      TYPEMAP
1117      Netconfig *<tab>T_PTROBJ
1118
1119 Here's a more complicated example: suppose that you wanted C<struct
1120 netconfig> to be blessed into the class C<Net::Config>.  One way to do
1121 this is to use underscores (_) to separate package names, as follows:
1122
1123         typedef struct netconfig * Net_Config;
1124
1125 And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1126 double-colons (::), and declare C<Net_Config> to be of that type:
1127
1128
1129         TYPEMAP
1130         Net_Config      T_PTROBJ_SPECIAL
1131
1132         INPUT
1133         T_PTROBJ_SPECIAL
1134                 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1135                         IV tmp = SvIV((SV*)SvRV($arg));
1136                 $var = ($type) tmp;
1137                 }
1138                 else
1139                         croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1140
1141         OUTPUT
1142         T_PTROBJ_SPECIAL
1143                 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1144                 (void*)$var);
1145
1146 The INPUT and OUTPUT sections substitute underscores for double-colons
1147 on the fly, giving the desired effect.  This example demonstrates some
1148 of the power and versatility of the typemap facility.
1149
1150 =head1 EXAMPLES
1151
1152 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1153
1154      #include "EXTERN.h"
1155      #include "perl.h"
1156      #include "XSUB.h"
1157
1158      #include <rpc/rpc.h>
1159
1160      typedef struct netconfig Netconfig;
1161
1162      MODULE = RPC  PACKAGE = RPC
1163
1164      SV *
1165      rpcb_gettime(host="localhost")
1166           char *host
1167           PREINIT:
1168           time_t  timep;
1169           CODE:
1170           ST(0) = sv_newmortal();
1171           if( rpcb_gettime( host, &timep ) )
1172                sv_setnv( ST(0), (double)timep );
1173
1174      Netconfig *
1175      getnetconfigent(netid="udp")
1176           char *netid
1177
1178      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1179
1180      void
1181      rpcb_DESTROY(netconf)
1182           Netconfig *netconf
1183           CODE:
1184           printf("NetconfigPtr::DESTROY\n");
1185           free( netconf );
1186
1187 File C<typemap>: Custom typemap for RPC.xs.
1188
1189      TYPEMAP
1190      Netconfig *  T_PTROBJ
1191
1192 File C<RPC.pm>: Perl module for the RPC extension.
1193
1194      package RPC;
1195
1196      require Exporter;
1197      require DynaLoader;
1198      @ISA = qw(Exporter DynaLoader);
1199      @EXPORT = qw(rpcb_gettime getnetconfigent);
1200
1201      bootstrap RPC;
1202      1;
1203
1204 File C<rpctest.pl>: Perl test program for the RPC extension.
1205
1206      use RPC;
1207
1208      $netconf = getnetconfigent();
1209      $a = rpcb_gettime();
1210      print "time = $a\n";
1211      print "netconf = $netconf\n";
1212
1213      $netconf = getnetconfigent("tcp");
1214      $a = rpcb_gettime("poplar");
1215      print "time = $a\n";
1216      print "netconf = $netconf\n";
1217
1218
1219 =head1 XS VERSION
1220
1221 This document covers features supported by C<xsubpp> 1.935.
1222
1223 =head1 AUTHOR
1224
1225 Dean Roehrich <F<roehrich@cray.com>>
1226 Jul 8, 1996