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