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