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