pod/perlapi.pod

   1 =head1 NAME
   2
   3 perlapi - Perl 5 application programming interface for C extensions
   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 Many of the examples which follow will concentrate on creating an
  27 interface between Perl and the ONC+RPC bind library functions.
  28 Specifically, the rpcb_gettime() function will be used to demonstrate many
  29 features of the XS language.  This function has two parameters; the first
  30 is an input parameter and the second is an output parameter.  The function
  31 also returns a status value.
  32
  33         bool_t rpcb_gettime(const char *host, time_t *timep);
  34
  35 From C this function will be called with the following
  36 statements.
  37
  38      #include <rpc/rpc.h>
  39      bool_t status;
  40      time_t timep;
  41      status = rpcb_gettime( "localhost", &timep );
  42
  43 If an XSUB is created to offer a direct translation between this function
  44 and Perl, then this XSUB will be used from Perl with the following code.
  45 The $status and $timep variables will contain the output of the function.
  46
  47      use RPC;
  48      $status = rpcb_gettime( "localhost", $timep );
  49
  50 The following XS file shows an XS subroutine, or XSUB, which
  51 demonstrates one possible interface to the rpcb_gettime()
  52 function.  This XSUB represents a direct translation between
  53 C and Perl and so preserves the interface even from Perl.
  54 This XSUB will be invoked from Perl with the usage shown
  55 above.  Note that the first three #include statements, for
  56 C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
  57 beginning of an XS file.  This approach and others will be
  58 expanded later in this document.
  59
  60      #include "EXTERN.h"
  61      #include "perl.h"
  62      #include "XSUB.h"
  63      #include <rpc/rpc.h>
  64
  65      MODULE = RPC  PACKAGE = RPC
  66
  67      bool_t
  68      rpcb_gettime(host,timep)
  69           char *  host
  70           time_t  &timep
  71           OUTPUT:
  72           timep
  73
  74 Any extension to Perl, including those containing XSUBs,
  75 should have a Perl module to serve as the bootstrap which
  76 pulls the extension into Perl.  This module will export the
  77 extension's functions and variables to the Perl program and
  78 will cause the extension's XSUBs to be linked into Perl.
  79 The following module will be used for most of the examples
  80 in this document and should be used from Perl with the C<use>
  81 command as shown earlier.  Perl modules are explained in
  82 more detail later in this document.
  83
  84      package RPC;
  85
  86      require Exporter;
  87      require DynaLoader;
  88      @ISA = qw(Exporter DynaLoader);
  89      @EXPORT = qw( rpcb_gettime );
  90
  91      bootstrap RPC;
  92      1;
  93
  94 Throughout this document a variety of interfaces to the rpcb_gettime()
  95 XSUB will be explored.  The XSUBs will take their parameters in different
  96 orders or will take different numbers of parameters.  In each case the
  97 XSUB is an abstraction between Perl and the real C rpcb_gettime()
  98 function, and the XSUB must always ensure that the real rpcb_gettime()
  99 function is called with the correct parameters.  This abstraction will
 100 allow the programmer to create a more Perl-like interface to the C
 101 function.
 102
 103 =head2 The Anatomy of an XSUB
 104
 105 The following XSUB allows a Perl program to access a  C  library  function  called  sin().  The XSUB will imitate the C
 106 function which takes a single argument and returns a  single
 107 value.
 108
 109      double
 110      sin(x)
 111        double<tab>x
 112
 113 The compiler expects a tab between the parameter name and its type, and
 114 any or no whitespace before the type.  When using C pointers the
 115 indirection operator C<*> should be considered part of the type and the
 116 address operator C<&> should be considered part of the variable, as is
 117 demonstrated in the rpcb_gettime() function above.  See the section on
 118 typemaps for more about handling qualifiers and unary operators in C
 119 types.
 120
 121 The parameter list of a function must not have whitespace
 122 after the open-parenthesis or before the close-parenthesis.
 123
 124    INCORRECT                      CORRECT
 125
 126    double                         double
 127    sin( x )                       sin(x)
 128      double  x                      double  x
 129
 130 The function name and the return type must be placed on
 131 separate lines.
 132
 133   INCORRECT                        CORRECT
 134
 135   double sin(x)                    double
 136     double  x                      sin(x)
 137                                      double  x
 138
 139 =head2 The Argument Stack
 140
 141 The argument stack is used to store the values which are
 142 sent as parameters to the XSUB and to store the XSUB's
 143 return value.  In reality all Perl functions keep their
 144 values on this stack at the same time, each limited to its
 145 own range of positions on the stack.  In this document the
 146 first position on that stack which belongs to the active
 147 function will be referred to as position 0 for that function.
 148
 149 XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> refers
 150 to a position in this XSUB's part of the stack.  Position 0 for that
 151 function would be known to the XSUB as ST(0).  The XSUB's incoming
 152 parameters and outgoing return values always begin at ST(0).  For many
 153 simple cases the B<xsubpp> compiler will generate the code necessary to
 154 handle the argument stack by embedding code fragments found in the
 155 typemaps.  In more complex cases the programmer must supply the code.
 156
 157 =head2 The RETVAL Variable
 158
 159 The RETVAL variable is a magic variable which always matches
 160 the return type of the C library function.  The B<xsubpp> compiler will
 161 supply this variable in each XSUB and by default will use it to hold the
 162 return value of the C library function being called.  In simple cases the
 163 value of RETVAL will be placed in ST(0) of the argument stack where it can
 164 be received by Perl as the return value of the XSUB.
 165
 166 If the XSUB has a return type of C<void> then the compiler will
 167 not supply a RETVAL variable for that function.  When using
 168 the PPCODE: directive the RETVAL variable may not be needed.
 169
 170 =head2 The MODULE Keyword
 171
 172 The MODULE keyword is used to start the XS code and to
 173 specify the package of the functions which are being
 174 defined.  All text preceding the first MODULE keyword is
 175 considered C code and is passed through to the output
 176 untouched.  Every XS module will have a bootstrap function
 177 which is used to hook the XSUBs into Perl.  The package name
 178 of this bootstrap function will match the value of the last
 179 MODULE statement in the XS source files.  The value of
 180 MODULE should always remain constant within the same XS
 181 file, though this is not required.
 182
 183 The following example will start the XS code and will place
 184 all functions in a package named RPC.
 185
 186      MODULE = RPC
 187
 188 =head2 The PACKAGE Keyword
 189
 190 When functions within an XS source file must be separated into packages
 191 the PACKAGE keyword should be used.  This keyword is used with the MODULE
 192 keyword and must follow immediately after it when used.
 193
 194      MODULE = RPC  PACKAGE = RPC
 195
 196      [ XS code in package RPC ]
 197
 198      MODULE = RPC  PACKAGE = RPCB
 199
 200      [ XS code in package RPCB ]
 201
 202      MODULE = RPC  PACKAGE = RPC
 203
 204      [ XS code in package RPC ]
 205
 206 Although this keyword is optional and in some cases provides redundant
 207 information it should always be used.  This keyword will ensure that the
 208 XSUBs appear in the desired package.
 209
 210 =head2 The PREFIX Keyword
 211
 212 The PREFIX keyword designates prefixes which should be
 213 removed from the Perl function names.  If the C function is
 214 C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
 215 see this function as C<gettime()>.
 216
 217 This keyword should follow the PACKAGE keyword when used.
 218 If PACKAGE is not used then PREFIX should follow the MODULE
 219 keyword.
 220
 221      MODULE = RPC  PREFIX = rpc_
 222
 223      MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
 224
 225 =head2 The OUTPUT: Keyword
 226
 227 The OUTPUT: keyword indicates that certain function parameters should be
 228 updated (new values made visible to Perl) when the XSUB terminates or that
 229 certain values should be returned to the calling Perl function.  For
 230 simple functions, such as the sin() function above, the RETVAL variable is
 231 automatically designated as an output value.  In more complex functions
 232 the B<xsubpp> compiler will need help to determine which variables are output
 233 variables.
 234
 235 This keyword will normally be used to complement the CODE:  keyword.
 236 The RETVAL variable is not recognized as an output variable when the
 237 CODE: keyword is present.  The OUTPUT:  keyword is used in this
 238 situation to tell the compiler that RETVAL really is an output
 239 variable.
 240
 241 The OUTPUT: keyword can also be used to indicate that function parameters
 242 are output variables.  This may be necessary when a parameter has been
 243 modified within the function and the programmer would like the update to
 244 be seen by Perl.  If function parameters are listed under OUTPUT: along
 245 with the RETVAL variable then the RETVAL variable must be the last one
 246 listed.
 247
 248      bool_t
 249      rpcb_gettime(host,timep)
 250           char *  host
 251           time_t  &timep
 252           OUTPUT:
 253           timep
 254
 255 The OUTPUT: keyword will also allow an output parameter to
 256 be mapped to a matching piece of code rather than to a
 257 typemap.
 258
 259      bool_t
 260      rpcb_gettime(host,timep)
 261           char *  host
 262           time_t  &timep
 263           OUTPUT:
 264           timep<tab>sv_setnv(ST(1), (double)timep);
 265
 266 =head2 The CODE: Keyword
 267
 268 This keyword is used in more complicated XSUBs which require
 269 special handling for the C function.  The RETVAL variable is
 270 available but will not be returned unless it is specified
 271 under the OUTPUT: keyword.
 272
 273 The following XSUB is for a C function which requires special handling of
 274 its parameters.  The Perl usage is given first.
 275
 276      $status = rpcb_gettime( "localhost", $timep );
 277
 278 The XSUB follows.
 279
 280     bool_t rpcb_gettime(host,timep)
 281           char *  host
 282           time_t  timep
 283           CODE:
 284                RETVAL = rpcb_gettime( host, &timep );
 285           OUTPUT:
 286           timep
 287           RETVAL
 288
 289 In many of the examples shown here the CODE: block (and
 290 other blocks) will often be contained within braces ( C<{> and
 291 C<}> ).  This protects the CODE: block from complex INPUT
 292 typemaps and ensures the resulting C code is legal.
 293
 294 =head2 The NO_INIT Keyword
 295
 296 The NO_INIT keyword is used to indicate that a function
 297 parameter is being used only as an output value.  The B<xsubpp>
 298 compiler will normally generate code to read the values of
 299 all function parameters from the argument stack and assign
 300 them to C variables upon entry to the function.  NO_INIT
 301 will tell the compiler that some parameters will be used for
 302 output rather than for input and that they will be handled
 303 before the function terminates.
 304
 305 The following example shows a variation of the rpcb_gettime() function.
 306 This function uses the timep variable only as an output variable and does
 307 not care about its initial contents.
 308
 309      bool_t
 310      rpcb_gettime(host,timep)
 311           char *  host
 312           time_t  &timep = NO_INIT
 313           OUTPUT:
 314           timep
 315
 316 =head2 Initializing Function Parameters
 317
 318 Function parameters are normally initialized with their
 319 values from the argument stack.  The typemaps contain the
 320 code segments which are used to transfer the Perl values to
 321 the C parameters.  The programmer, however, is allowed to
 322 override the typemaps and supply alternate initialization
 323 code.
 324
 325 The following code demonstrates how to supply initialization code for
 326 function parameters.  The initialization code is eval'd by the compiler
 327 before it is added to the output so anything which should be interpreted
 328 literally, such as double quotes, must be protected with backslashes.
 329
 330      bool_t
 331      rpcb_gettime(host,timep)
 332           char *  host = (char *)SvPV(ST(0),na);
 333           time_t  &timep = 0;
 334           OUTPUT:
 335           timep
 336
 337 This should not be used to supply default values for parameters.  One
 338 would normally use this when a function parameter must be processed by
 339 another library function before it can be used.  Default parameters are
 340 covered in the next section.
 341
 342 =head2 Default Parameter Values
 343
 344 Default values can be specified for function parameters by
 345 placing an assignment statement in the parameter list.  The
 346 default value may be a number or a string.  Defaults should
 347 always be used on the right-most parameters only.
 348
 349 To allow the XSUB for rpcb_gettime() to have a default host
 350 value the parameters to the XSUB could be rearranged.  The
 351 XSUB will then call the real rpcb_gettime() function with
 352 the parameters in the correct order.  Perl will call this
 353 XSUB with either of the following statements.
 354
 355      $status = rpcb_gettime( $timep, $host );
 356
 357      $status = rpcb_gettime( $timep );
 358
 359 The XSUB will look like the code  which  follows.   A  CODE:
 360 block  is used to call the real rpcb_gettime() function with
 361 the parameters in the correct order for that function.
 362
 363      bool_t
 364      rpcb_gettime(timep,host="localhost")
 365           char *  host
 366           time_t  timep = NO_INIT
 367           CODE:
 368                RETVAL = rpcb_gettime( host, &timep );
 369           OUTPUT:
 370           timep
 371           RETVAL
 372
 373 =head2 Variable-length Parameter Lists
 374
 375 XSUBs can have variable-length parameter lists by specifying an ellipsis
 376 C<(...)> in the parameter list.  This use of the ellipsis is similar to that
 377 found in ANSI C.  The programmer is able to determine the number of
 378 arguments passed to the XSUB by examining the C<items> variable which the
 379 B<xsubpp> compiler supplies for all XSUBs.  By using this mechanism one can
 380 create an XSUB which accepts a list of parameters of unknown length.
 381
 382 The I<host> parameter for the rpcb_gettime() XSUB can be
 383 optional so the ellipsis can be used to indicate that the
 384 XSUB will take a variable number of parameters.  Perl should
 385 be able to call this XSUB with either of the following statments.
 386
 387      $status = rpcb_gettime( $timep, $host );
 388
 389      $status = rpcb_gettime( $timep );
 390
 391 The XS code, with ellipsis, follows.
 392
 393      bool_t
 394      rpcb_gettime(timep, ...)
 395           time_t  timep = NO_INIT
 396           CODE:
 397           {
 398           char *host = "localhost";
 399
 400           if( items > 1 )
 401                host = (char *)SvPV(ST(1), na);
 402           RETVAL = rpcb_gettime( host, &timep );
 403           }
 404           OUTPUT:
 405           timep
 406           RETVAL
 407
 408 =head2 The PPCODE: Keyword
 409
 410 The PPCODE: keyword is an alternate form of the CODE: keyword and is used
 411 to tell the B<xsubpp> compiler that the programmer is supplying the code to
 412 control the argument stack for the XSUBs return values.  Occassionally one
 413 will want an XSUB to return a list of values rather than a single value.
 414 In these cases one must use PPCODE: and then explicitly push the list of
 415 values on the stack.  The PPCODE: and CODE:  keywords are not used
 416 together within the same XSUB.
 417
 418 The following XSUB will call the C rpcb_gettime() function
 419 and will return its two output values, timep and status, to
 420 Perl as a single list.
 421
 422     void rpcb_gettime(host)
 423           char *  host
 424           PPCODE:
 425           {
 426           time_t  timep;
 427           bool_t  status;
 428           status = rpcb_gettime( host, &timep );
 429           EXTEND(sp, 2);
 430           PUSHs(sv_2mortal(newSVnv(status)));
 431           PUSHs(sv_2mortal(newSVnv(timep)));
 432           }
 433
 434 Notice that the programmer must supply the C code necessary
 435 to have the real rpcb_gettime() function called and to have
 436 the return values properly placed on the argument stack.
 437
 438 The C<void> return type for this function tells the B<xsubpp> compiler that
 439 the RETVAL variable is not needed or used and that it should not be created.
 440 In most scenarios the void return type should be used with the PPCODE:
 441 directive.
 442
 443 The EXTEND() macro is used to make room on the argument
 444 stack for 2 return values.  The PPCODE: directive causes the
 445 B<xsubpp> compiler to create a stack pointer called C<sp>, and it
 446 is this pointer which is being used in the EXTEND() macro.
 447 The values are then pushed onto the stack with the PUSHs()
 448 macro.
 449
 450 Now the rpcb_gettime() function can be used from Perl with
 451 the following statement.
 452
 453      ($status, $timep) = rpcb_gettime("localhost");
 454
 455 =head2 Returning Undef And Empty Lists
 456
 457 Occassionally the programmer will want to simply return
 458 C<undef> or an empty list if a function fails rather than a
 459 separate status value.  The rpcb_gettime() function offers
 460 just this situation.  If the function succeeds we would like
 461 to have it return the time and if it fails we would like to
 462 have undef returned.  In the following Perl code the value
 463 of $timep will either be undef or it will be a valid time.
 464
 465      $timep = rpcb_gettime( "localhost" );
 466
 467 The following XSUB uses the C<void> return type to disable the generation of
 468 the RETVAL variable and uses a CODE: block to indicate to the compiler
 469 that the programmer has supplied all the necessary code.  The
 470 sv_newmortal() call will initialize the return value to undef, making that
 471 the default return value.
 472
 473      void
 474      rpcb_gettime(host)
 475           char *  host
 476           CODE:
 477           {
 478           time_t  timep;
 479           bool_t x;
 480           ST(0) = sv_newmortal();
 481           if( rpcb_gettime( host, &timep ) )
 482                sv_setnv( ST(0), (double)timep);
 483           }
 484
 485 The next example demonstrates how one would place an explicit undef in the
 486 return value, should the need arise.
 487
 488      void
 489      rpcb_gettime(host)
 490           char *  host
 491           CODE:
 492           {
 493           time_t  timep;
 494           bool_t x;
 495           ST(0) = sv_newmortal();
 496           if( rpcb_gettime( host, &timep ) ){
 497                sv_setnv( ST(0), (double)timep);
 498           }
 499           else{
 500                ST(0) = &sv_undef;
 501           }
 502           }
 503
 504 To return an empty list one must use a PPCODE: block and
 505 then not push return values on the stack.
 506
 507      void
 508      rpcb_gettime(host)
 509           char *  host
 510           PPCODE:
 511           {
 512           time_t  timep;
 513           if( rpcb_gettime( host, &timep ) )
 514                PUSHs(sv_2mortal(newSVnv(timep)));
 515           else{
 516           /* Nothing pushed on stack, so an empty */
 517           /* list is implicitly returned. */
 518           }
 519           }
 520
 521 =head2 The CLEANUP: Keyword
 522
 523 This keyword can be used when an XSUB requires special cleanup procedures
 524 before it terminates.  When the CLEANUP:  keyword is used it must follow
 525 any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB.  The
 526 code specified for the cleanup block will be added as the last statements
 527 in the XSUB.
 528
 529 =head2 The BOOT: Keyword
 530
 531 The BOOT: keyword is used to add code to the extension's bootstrap
 532 function.  The bootstrap function is generated by the B<xsubpp> compiler and
 533 normally holds the statements necessary to register any XSUBs with Perl.
 534 With the BOOT: keyword the programmer can tell the compiler to add extra
 535 statements to the bootstrap function.
 536
 537 This keyword may be used any time after the first MODULE keyword and should
 538 appear on a line by itself.  The first blank line after the keyword will
 539 terminate the code block.
 540
 541      BOOT:
 542      # The following message will be printed when the
 543      # bootstrap function executes.
 544      printf("Hello from the bootstrap!\n");
 545
 546 =head2 Inserting Comments and C Preprocessor Directives
 547
 548 Comments and C preprocessor directives are allowed within
 549 CODE:, PPCODE:, BOOT:, and CLEANUP: blocks.  The compiler
 550 will pass the preprocessor directives through untouched and
 551 will remove the commented lines.  Comments can be added to
 552 XSUBs by placing a C<#> at the beginning of the line.  Care
 553 should be taken to avoid making the comment look like a C
 554 preprocessor directive, lest it be interpreted as such.
 555
 556 =head2 Using XS With C++
 557
 558 If a function is defined as a C++ method then it will assume
 559 its first argument is an object pointer.  The object pointer
 560 will be stored in a variable called THIS.  The object should
 561 have been created by C++ with the new() function and should
 562 be blessed by Perl with the sv_setptrobj() macro.  The
 563 blessing of the object by Perl can be handled by the
 564 T_PTROBJ typemap.
 565
 566 If the method is defined as static it will call the C++
 567 function using the class::method() syntax.  If the method is not static
 568 the function will be called using the THIS->method() syntax.
 569
 570 =head2 Perl Variables
 571
 572 The following demonstrates how the Perl variable $host can
 573 be accessed from an XSUB.  The function B<perl_get_sv()> is
 574 used to obtain a pointer to the variable, known as an B<SV>
 575 (Scalar Variable) internally.  The package name C<RPC> will be
 576 added to the name of the variable so perl_get_sv() will know
 577 in which package $host can be found.  If the package name is
 578 not supplied then perl_get_sv() will search package C<main> for
 579 the variable.  The macro B<SvPVX()> is then used to dereference
 580 the SV to obtain a C<char*> pointer to its contents.
 581
 582      void
 583      rpcb_gettime()
 584           PPCODE:
 585           {
 586           char *host;
 587           SV *hostsv;
 588           time_t timep;
 589
 590           hostsv = perl_get_sv( "RPC::host", FALSE );
 591           if( hostsv != NULL ){
 592                host = SvPVX( hostsv );
 593                if( rpcb_gettime( host, &timep ) )
 594                     PUSHs(sv_2mortal(newSVnv(timep)));
 595           }
 596           }
 597
 598 This Perl code can be used to call that XSUB.
 599
 600      $RPC::host = "localhost";
 601      $timep = rpcb_gettime();
 602
 603 In the above example the SV contained a C C<char*> but a Perl
 604 scalar variable may also contain numbers and references.  If
 605 the SV is expected to have a C C<int> then the macro B<SvIVX()>
 606 should be used to dereference the SV.  When the SV contains
 607 a C double then B<SvNVX()> should be used.
 608
 609 The macro B<SvRV()> can be used to dereference an SV when it is a Perl
 610 reference.  The result will be another SV which points to the actual Perl
 611 variable.  This can then be dereferenced with SvPVX(), SvNVX(), or
 612 SvIVX().  The following XSUB will use SvRV().
 613
 614     void rpcb_gettime()
 615           PPCODE:
 616           {
 617           char *host;
 618           SV *rv;
 619           SV *hostsv;
 620           time_t timep;
 621
 622           rv = perl_get_sv( "RPC::host", FALSE );
 623           if( rv != NULL ){
 624                hostsv = SvRV( rv );
 625                host = SvPVX( hostsv );
 626                if( rpcb_gettime( host, &timep ) )
 627                     PUSHs(sv_2mortal(newSVnv(timep)));
 628           }
 629           }
 630
 631 This Perl code will create a variable $RPC::host which is a
 632 reference to $MY::host.  The variable $MY::host contains the
 633 hostname which will be used.
 634
 635      $MY::host = "localhost";
 636      $RPC::host = \$MY::host;
 637      $timep = rpcb_gettime();
 638
 639 The second argument to perl_get_sv() will normally be B<FALSE>
 640 as shown in the above examples.  An argument of B<TRUE> will
 641 cause variables to be created if they do not already exist.
 642 One should not use TRUE unless steps are taken to deal with
 643 a possibly empty SV.
 644
 645 XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to
 646 access Perl arrays, hashes, and code values.
 647
 648 =head2 Interface Stategy
 649
 650 When designing an interface between Perl and a C library a straight
 651 translation from C to XS is often sufficient.  The interface will often be
 652 very C-like and occasionally nonintuitive, especially when the C function
 653 modifies one of its parameters.  In cases where the programmer wishes to
 654 create a more Perl-like interface the following strategy may help to
 655 identify the more critical parts of the interface.
 656
 657 Identify the C functions which modify their parameters.  The XSUBs for
 658 these functions may be able to return lists to Perl, or may be
 659 candidates to return undef or an empty list in case of failure.
 660
 661 Identify which values are used only by the C and XSUB functions
 662 themselves.  If Perl does not need to access the contents of the value
 663 then it may not be necessary to provide a translation for that value
 664 from C to Perl.
 665
 666 Identify the pointers in the C function parameter lists and return
 667 values.  Some pointers can be handled in XS with the & unary operator on
 668 the variable name while others will require the use of the * operator on
 669 the type name.  In general it is easier to work with the & operator.
 670
 671 Identify the structures used by the C functions.  In many
 672 cases it may be helpful to use the T_PTROBJ typemap for
 673 these structures so they can be manipulated by Perl as
 674 blessed objects.
 675
 676 =head2 The Perl Module
 677
 678 The Perl module is the link between the extension library,
 679 which was generated from XS code, and the Perl interpreter.
 680 The module is used to tell Perl what the extension library
 681 contains.  The name and package of the module should match
 682 the name of the library.
 683
 684 The following is a Perl module for an extension containing
 685 some ONC+ RPC bind library functions.
 686
 687      package RPC;
 688
 689      require Exporter;
 690      require DynaLoader;
 691      @ISA = qw(Exporter DynaLoader);
 692      @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr
 693                      rpcb_rmtcall rpcb_set rpcb_unset );
 694
 695      bootstrap RPC;
 696      1;
 697
 698 The RPC extension contains the functions found in the
 699 @EXPORT list.  By using the C<Exporter> module the RPC module
 700 can make these function names visible to the rest of the
 701 Perl program.  The C<DynaLoader> module will allow the RPC
 702 module to bootstrap the extension library.  To load this
 703 extension and make the functions available, the following
 704 Perl statement should be used.
 705
 706      use RPC;
 707
 708 For more information about the DynaLoader consult its documentation in the
 709 ext/DynaLoader directory in the Perl source.
 710
 711 =head2 Perl Objects And C Structures
 712
 713 When dealing with C structures one should select either
 714 B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
 715 designed to handle pointers to complex objects.  The
 716 T_PTRREF type will allow the Perl object to be unblessed
 717 while the T_PTROBJ type requires that the object be blessed.
 718 By using T_PTROBJ one can achieve a form of type-checking
 719 since the XSUB will attempt to verify that the Perl object
 720 is of the expected type.
 721
 722 The following XS code shows the getnetconfigent() function which is used
 723 with ONC TIRPC.  The getnetconfigent() function will return a pointer to a
 724 C structure and has the C prototype shown below.  The example will
 725 demonstrate how the C pointer will become a Perl reference.  Perl will
 726 consider this reference to be a pointer to a blessed object and will
 727 attempt to call a destructor for the object.  A destructor will be
 728 provided in the XS source to free the memory used by getnetconfigent().
 729 Destructors in XS can be created by specifying an XSUB function whose name
 730 ends with the word B<DESTROY>.  XS destructors can be used to free memory
 731 which may have been malloc'd by another XSUB.
 732
 733      struct netconfig *getnetconfigent(const char *netid);
 734
 735 A C<typedef> will be created for C<struct netconfig>.  The Perl
 736 object will be blessed in a class matching the name of the C
 737 type, with the tag C<Ptr> appended, and the name should not
 738 have embedded spaces if it will be a Perl package name.  The
 739 destructor will be placed in a class corresponding to the
 740 class of the object and the PREFIX keyword will be used to
 741 trim the name to the word DESTROY as Perl will expect.
 742
 743      typedef struct netconfig Netconfig;
 744
 745      MODULE = RPC  PACKAGE = RPC
 746
 747      Netconfig *
 748      getnetconfigent(netid)
 749           char *  netid
 750
 751      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
 752
 753      void
 754      rpcb_DESTROY(netconf)
 755           Netconfig *  netconf
 756           CODE:
 757           printf("Now in NetconfigPtr::DESTROY\n");
 758           free( netconf );
 759
 760 This example requires the following typemap entry.  Consult the typemap
 761 section for more information about adding new typemaps for an extension.
 762
 763      TYPEMAP
 764      Netconfig *  T_PTROBJ
 765
 766 This example will be used with the following Perl statements.
 767
 768      use RPC;
 769      $netconf = getnetconfigent("udp");
 770
 771 When Perl destroys the object referenced by $netconf it will send the
 772 object to the supplied XSUB DESTROY function.  Perl cannot determine, and
 773 does not care, that this object is a C struct and not a Perl object.  In
 774 this sense, there is no difference between the object created by the
 775 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
 776
 777 =head2 C Headers and Perl
 778
 779 The B<h2xs> compiler is designed to convert C header files in
 780 /usr/include into Perl extensions.  This compiler will
 781 create a directory under the C<ext> directory of the Perl
 782 source and will populate it with a Makefile, a Perl Module,
 783 an XS source file, and a MANIFEST file.
 784
 785 The following command will create an extension called C<Rusers>
 786 from the <rpcsvc/rusers.h> header.
 787
 788      h2xs rpcsvc/rusers
 789
 790 When the Rusers extension has been compiled and installed
 791 Perl can use it to retrieve any C<#define> statements which
 792 were in the C header.
 793
 794      use Rusers;
 795      print "RPC program number for rusers service: ";
 796      print &RUSERSPROG, "\n";
 797
 798 =head2 Creating A New Extension
 799
 800 The B<h2xs> compiler can generate template source files and
 801 Makefiles.  These templates offer a suitable starting point
 802 for most extensions.  The following example demonstrates how
 803 one might use B<h2xs> to create an extension containing the RPC
 804 functions in this document.
 805
 806 The extension will not use autoloaded functions and will not define
 807 constants, so the B<-A> option will be given to B<h2xs>.  When run from the
 808 Perl source directory, the B<h2xs> compiler will create the directory
 809 ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL,
 810 and MANIFEST.  The XS code for the RPC functions should be added to the
 811 RPC.xs file.  The @EXPORT list in RPC.pm should be updated to include the
 812 functions from RPC.xs.
 813
 814      h2xs -An RPC
 815
 816 To compile the extension for dynamic loading the following
 817 command should be executed from the ext/RPC directory.
 818
 819      make dynamic
 820
 821 If the extension will be statically linked into the Perl
 822 binary then the makefile (use C<makefile>, not C<Makefile>) in the
 823 Perl source directory should be edited to add C<ext/RPC/RPC.a>
 824 to the C<static_ext> variable.  Before making this change Perl
 825 should have already been built.  After the makefile has been
 826 updated the following command should be executed from the
 827 Perl source directory.
 828
 829      make
 830
 831 Perl's B<Configure> script can also be used to add extensions.  The extension
 832 should be placed in the C<ext> directory under the Perl source before Perl
 833 has been built and prior to running Configure.  When Configure is run it
 834 will find the extension along with the other extensions in the C<ext>
 835 directory and will add it to the list of extensions to be built.  When make
 836 is run the extension will be built along with the other extensions.
 837
 838 Configure recognizes extensions if they have an XS source
 839 file which matches the name of the extension directory.  If
 840 the extension directory includes a MANIFEST file Configure
 841 will search that file for any B<.SH> files and extract them
 842 after it extracts all the other .SH files listed in the main
 843 MANIFEST.  The main Perl Makefile will then run B<make> in the
 844 extension's directory if it finds an XS file matching the
 845 name of the extension's directory.
 846
 847 =head2 The Typemap
 848
 849 The typemap is a collection of code fragments which are used by the B<xsubpp>
 850 compiler to map C function parameters and values to Perl values.  The
 851 typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
 852 C<OUTPUT>.  The INPUT section tells the compiler how to translate Perl values
 853 into variables of certain C types.  The OUTPUT section tells the compiler
 854 how to translate the values from certain C types into values Perl can
 855 understand.  The TYPEMAP section tells the compiler which of the INPUT and
 856 OUTPUT code fragments should be used to map a given C type to a Perl value.
 857 Each of the sections of the typemap must be preceded by one of the TYPEMAP,
 858 INPUT, or OUTPUT keywords.
 859
 860 The default typemap in the C<ext> directory of the Perl source contains many
 861 useful types which can be used by Perl extensions.  Some extensions define
 862 additional typemaps which they keep in their own directory.  These
 863 additional typemaps may reference INPUT and OUTPUT maps in the main
 864 typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
 865 override any mappings which are in the default typemap.
 866
 867 Most extensions which require a custom typemap will need only the TYPEMAP
 868 section of the typemap file.  The custom typemap used in the
 869 getnetconfigent() example shown earlier demonstrates what may be the typical
 870 use of extension typemaps.  That typemap is used to equate a C structure
 871 with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
 872 here.  Note that the C type is separated from the XS type with a tab and
 873 that the C unary operator C<*> is considered to be a part of the C type name.
 874
 875      TYPEMAP
 876      Netconfig *<tab>T_PTROBJ
 877
 878 =head1 EXAMPLES
 879
 880 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
 881
 882      #include "EXTERN.h"
 883      #include "perl.h"
 884      #include "XSUB.h"
 885
 886      #include <rpc/rpc.h>
 887
 888      typedef struct netconfig Netconfig;
 889
 890      MODULE = RPC  PACKAGE = RPC
 891
 892      void
 893      rpcb_gettime(host="localhost")
 894           char *  host
 895           CODE:
 896           {
 897           time_t  timep;
 898           ST(0) = sv_newmortal();
 899           if( rpcb_gettime( host, &timep ) )
 900                sv_setnv( ST(0), (double)timep );
 901           }
 902
 903      Netconfig *
 904      getnetconfigent(netid="udp")
 905           char *  netid
 906
 907      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
 908
 909      void
 910      rpcb_DESTROY(netconf)
 911           Netconfig *  netconf
 912           CODE:
 913           printf("NetconfigPtr::DESTROY\n");
 914           free( netconf );
 915
 916 File C<typemap>: Custom typemap for RPC.xs.
 917
 918      TYPEMAP
 919      Netconfig *  T_PTROBJ
 920
 921 File C<RPC.pm>: Perl module for the RPC extension.
 922
 923      package RPC;
 924
 925      require Exporter;
 926      require DynaLoader;
 927      @ISA = qw(Exporter DynaLoader);
 928      @EXPORT = qw(rpcb_gettime getnetconfigent);
 929
 930      bootstrap RPC;
 931      1;
 932
 933 File C<rpctest.pl>: Perl test program for the RPC extension.
 934
 935      use RPC;
 936
 937      $netconf = getnetconfigent();
 938      $a = rpcb_gettime();
 939      print "time = $a\n";
 940      print "netconf = $netconf\n";
 941
 942      $netconf = getnetconfigent("tcp");
 943      $a = rpcb_gettime("poplar");
 944      print "time = $a\n";
 945      print "netconf = $netconf\n";
 946
 947
 948 =head1 AUTHOR
 949
 950 Dean Roehrich <roehrich@cray.com>
 951 September 27, 1994