1898184e3Ssthen=head1 NAME 2898184e3Ssthen 3898184e3Ssthenperlxs - XS language reference manual 4898184e3Ssthen 5898184e3Ssthen=head1 DESCRIPTION 6898184e3Ssthen 7898184e3Ssthen=head2 Introduction 8898184e3Ssthen 9898184e3SsthenXS is an interface description file format used to create an extension 10898184e3Sstheninterface between Perl and C code (or a C library) which one wishes 11898184e3Ssthento use with Perl. The XS interface is combined with the library to 12898184e3Ssthencreate a new library which can then be either dynamically loaded 13898184e3Ssthenor statically linked into perl. The XS interface description is 14898184e3Ssthenwritten in the XS language and is the core component of the Perl 15898184e3Ssthenextension interface. 16898184e3Ssthen 176fb12b70Safresh1Before writing XS, read the L</CAVEATS> section below. 186fb12b70Safresh1 19898184e3SsthenAn B<XSUB> forms the basic unit of the XS interface. After compilation 20898184e3Ssthenby the B<xsubpp> compiler, each XSUB amounts to a C function definition 21898184e3Ssthenwhich will provide the glue between Perl calling conventions and C 22898184e3Ssthencalling conventions. 23898184e3Ssthen 24898184e3SsthenThe glue code pulls the arguments from the Perl stack, converts these 25eac174f2Safresh1Perl values to the formats expected by a C function, calls this C function, 26eac174f2Safresh1and then transfers the return values of the C function back to Perl. 27898184e3SsthenReturn values here may be a conventional C return value or any C 28898184e3Ssthenfunction arguments that may serve as output parameters. These return 29898184e3Ssthenvalues may be passed back to Perl either by putting them on the 30898184e3SsthenPerl stack, or by modifying the arguments supplied from the Perl side. 31898184e3Ssthen 32898184e3SsthenThe above is a somewhat simplified view of what really happens. Since 33898184e3SsthenPerl allows more flexible calling conventions than C, XSUBs may do much 34898184e3Ssthenmore in practice, such as checking input parameters for validity, 35898184e3Ssthenthrowing exceptions (or returning undef/empty list) if the return value 36898184e3Ssthenfrom the C function indicates failure, calling different C functions 37898184e3Ssthenbased on numbers and types of the arguments, providing an object-oriented 38898184e3Sstheninterface, etc. 39898184e3Ssthen 40898184e3SsthenOf course, one could write such glue code directly in C. However, this 41898184e3Ssthenwould be a tedious task, especially if one needs to write glue for 42898184e3Ssthenmultiple C functions, and/or one is not familiar enough with the Perl 43898184e3Ssthenstack discipline and other such arcana. XS comes to the rescue here: 44898184e3Sstheninstead of writing this glue C code in long-hand, one can write 45898184e3Ssthena more concise short-hand I<description> of what should be done by 46898184e3Ssthenthe glue, and let the XS compiler B<xsubpp> handle the rest. 47898184e3Ssthen 48898184e3SsthenThe XS language allows one to describe the mapping between how the C 49898184e3Ssthenroutine is used, and how the corresponding Perl routine is used. It 50898184e3Ssthenalso allows creation of Perl routines which are directly translated to 51898184e3SsthenC code and which are not related to a pre-existing C function. In cases 52898184e3Ssthenwhen the C interface coincides with the Perl interface, the XSUB 53898184e3Ssthendeclaration is almost identical to a declaration of a C function (in K&R 54898184e3Ssthenstyle). In such circumstances, there is another tool called C<h2xs> 55898184e3Ssthenthat is able to translate an entire C header file into a corresponding 56898184e3SsthenXS file that will provide glue to the functions/macros described in 57898184e3Ssthenthe header file. 58898184e3Ssthen 59898184e3SsthenThe XS compiler is called B<xsubpp>. This compiler creates 60898184e3Ssthenthe constructs necessary to let an XSUB manipulate Perl values, and 61898184e3Ssthencreates the glue necessary to let Perl call the XSUB. The compiler 62898184e3Ssthenuses B<typemaps> to determine how to map C function parameters 63898184e3Ssthenand output values to Perl values and back. The default typemap 64898184e3Ssthen(which comes with Perl) handles many common C types. A supplementary 65898184e3Ssthentypemap may also be needed to handle any special structures and types 66898184e3Ssthenfor the library being linked. For more information on typemaps, 67898184e3Ssthensee L<perlxstypemap>. 68898184e3Ssthen 69898184e3SsthenA file in XS format starts with a C language section which goes until the 70898184e3Ssthenfirst C<MODULE =Z<>> directive. Other XS directives and XSUB definitions 71898184e3Ssthenmay follow this line. The "language" used in this part of the file 72898184e3Ssthenis usually referred to as the XS language. B<xsubpp> recognizes and 73898184e3Ssthenskips POD (see L<perlpod>) in both the C and XS language sections, which 74898184e3Ssthenallows the XS file to contain embedded documentation. 75898184e3Ssthen 76898184e3SsthenSee L<perlxstut> for a tutorial on the whole extension creation process. 77898184e3Ssthen 78898184e3SsthenNote: For some extensions, Dave Beazley's SWIG system may provide a 79898184e3Ssthensignificantly more convenient mechanism for creating the extension 80898184e3Ssthenglue code. See L<http://www.swig.org/> for more information. 81898184e3Ssthen 8256d68f1eSafresh1For simple bindings to C libraries as well as other machine code libraries, 8356d68f1eSafresh1consider instead using the much simpler 8456d68f1eSafresh1L<libffi|http://sourceware.org/libffi/> interface via CPAN modules like 8556d68f1eSafresh1L<FFI::Platypus> or L<FFI::Raw>. 8656d68f1eSafresh1 87898184e3Ssthen=head2 On The Road 88898184e3Ssthen 89898184e3SsthenMany of the examples which follow will concentrate on creating an interface 90898184e3Ssthenbetween Perl and the ONC+ RPC bind library functions. The rpcb_gettime() 91898184e3Ssthenfunction is used to demonstrate many features of the XS language. This 92898184e3Ssthenfunction has two parameters; the first is an input parameter and the second 93898184e3Ssthenis an output parameter. The function also returns a status value. 94898184e3Ssthen 95898184e3Ssthen bool_t rpcb_gettime(const char *host, time_t *timep); 96898184e3Ssthen 97898184e3SsthenFrom C this function will be called with the following 98898184e3Ssthenstatements. 99898184e3Ssthen 100898184e3Ssthen #include <rpc/rpc.h> 101898184e3Ssthen bool_t status; 102898184e3Ssthen time_t timep; 103898184e3Ssthen status = rpcb_gettime( "localhost", &timep ); 104898184e3Ssthen 105898184e3SsthenIf an XSUB is created to offer a direct translation between this function 106898184e3Ssthenand Perl, then this XSUB will be used from Perl with the following code. 107898184e3SsthenThe $status and $timep variables will contain the output of the function. 108898184e3Ssthen 109898184e3Ssthen use RPC; 110898184e3Ssthen $status = rpcb_gettime( "localhost", $timep ); 111898184e3Ssthen 112898184e3SsthenThe following XS file shows an XS subroutine, or XSUB, which 113898184e3Ssthendemonstrates one possible interface to the rpcb_gettime() 114898184e3Ssthenfunction. This XSUB represents a direct translation between 115898184e3SsthenC and Perl and so preserves the interface even from Perl. 116898184e3SsthenThis XSUB will be invoked from Perl with the usage shown 117898184e3Ssthenabove. Note that the first three #include statements, for 118898184e3SsthenC<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the 119898184e3Ssthenbeginning of an XS file. This approach and others will be 1206fb12b70Safresh1expanded later in this document. A #define for C<PERL_NO_GET_CONTEXT> 1216fb12b70Safresh1should be present to fetch the interpreter context more efficiently, 1226fb12b70Safresh1see L<perlguts|perlguts/How multiple interpreters and concurrency are 1236fb12b70Safresh1supported> for details. 124898184e3Ssthen 1256fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 126898184e3Ssthen #include "EXTERN.h" 127898184e3Ssthen #include "perl.h" 128898184e3Ssthen #include "XSUB.h" 129898184e3Ssthen #include <rpc/rpc.h> 130898184e3Ssthen 131898184e3Ssthen MODULE = RPC PACKAGE = RPC 132898184e3Ssthen 133898184e3Ssthen bool_t 134898184e3Ssthen rpcb_gettime(host,timep) 135898184e3Ssthen char *host 136898184e3Ssthen time_t &timep 137898184e3Ssthen OUTPUT: 138898184e3Ssthen timep 139898184e3Ssthen 140898184e3SsthenAny extension to Perl, including those containing XSUBs, 141898184e3Ssthenshould have a Perl module to serve as the bootstrap which 142898184e3Ssthenpulls the extension into Perl. This module will export the 143898184e3Ssthenextension's functions and variables to the Perl program and 144898184e3Ssthenwill cause the extension's XSUBs to be linked into Perl. 145898184e3SsthenThe following module will be used for most of the examples 146898184e3Ssthenin this document and should be used from Perl with the C<use> 147898184e3Ssthencommand as shown earlier. Perl modules are explained in 148898184e3Ssthenmore detail later in this document. 149898184e3Ssthen 150898184e3Ssthen package RPC; 151898184e3Ssthen 152898184e3Ssthen require Exporter; 153898184e3Ssthen require DynaLoader; 154898184e3Ssthen @ISA = qw(Exporter DynaLoader); 155898184e3Ssthen @EXPORT = qw( rpcb_gettime ); 156898184e3Ssthen 157898184e3Ssthen bootstrap RPC; 158898184e3Ssthen 1; 159898184e3Ssthen 160898184e3SsthenThroughout this document a variety of interfaces to the rpcb_gettime() 161898184e3SsthenXSUB will be explored. The XSUBs will take their parameters in different 162898184e3Ssthenorders or will take different numbers of parameters. In each case the 163898184e3SsthenXSUB is an abstraction between Perl and the real C rpcb_gettime() 164898184e3Ssthenfunction, and the XSUB must always ensure that the real rpcb_gettime() 165898184e3Ssthenfunction is called with the correct parameters. This abstraction will 166898184e3Ssthenallow the programmer to create a more Perl-like interface to the C 167898184e3Ssthenfunction. 168898184e3Ssthen 169898184e3Ssthen=head2 The Anatomy of an XSUB 170898184e3Ssthen 171898184e3SsthenThe simplest XSUBs consist of 3 parts: a description of the return 172898184e3Ssthenvalue, the name of the XSUB routine and the names of its arguments, 173898184e3Ssthenand a description of types or formats of the arguments. 174898184e3Ssthen 175898184e3SsthenThe following XSUB allows a Perl program to access a C library function 176898184e3Ssthencalled sin(). The XSUB will imitate the C function which takes a single 177898184e3Ssthenargument and returns a single value. 178898184e3Ssthen 179898184e3Ssthen double 180898184e3Ssthen sin(x) 181898184e3Ssthen double x 182898184e3Ssthen 183898184e3SsthenOptionally, one can merge the description of types and the list of 184898184e3Ssthenargument names, rewriting this as 185898184e3Ssthen 186898184e3Ssthen double 187898184e3Ssthen sin(double x) 188898184e3Ssthen 189898184e3SsthenThis makes this XSUB look similar to an ANSI C declaration. An optional 190898184e3Ssthensemicolon is allowed after the argument list, as in 191898184e3Ssthen 192898184e3Ssthen double 193898184e3Ssthen sin(double x); 194898184e3Ssthen 195898184e3SsthenParameters with C pointer types can have different semantic: C functions 196898184e3Ssthenwith similar declarations 197898184e3Ssthen 198898184e3Ssthen bool string_looks_as_a_number(char *s); 199898184e3Ssthen bool make_char_uppercase(char *c); 200898184e3Ssthen 201898184e3Ssthenare used in absolutely incompatible manner. Parameters to these functions 202eac174f2Safresh1could be described to B<xsubpp> like this: 203898184e3Ssthen 204898184e3Ssthen char * s 205898184e3Ssthen char &c 206898184e3Ssthen 207898184e3SsthenBoth these XS declarations correspond to the C<char*> C type, but they have 208898184e3Ssthendifferent semantics, see L<"The & Unary Operator">. 209898184e3Ssthen 210898184e3SsthenIt is convenient to think that the indirection operator 211898184e3SsthenC<*> should be considered as a part of the type and the address operator C<&> 212898184e3Ssthenshould be considered part of the variable. See L<perlxstypemap> 213898184e3Ssthenfor more info about handling qualifiers and unary operators in C types. 214898184e3Ssthen 215898184e3SsthenThe function name and the return type must be placed on 216898184e3Ssthenseparate lines and should be flush left-adjusted. 217898184e3Ssthen 218898184e3Ssthen INCORRECT CORRECT 219898184e3Ssthen 220898184e3Ssthen double sin(x) double 221898184e3Ssthen double x sin(x) 222898184e3Ssthen double x 223898184e3Ssthen 224898184e3SsthenThe rest of the function description may be indented or left-adjusted. The 225898184e3Ssthenfollowing example shows a function with its body left-adjusted. Most 226898184e3Ssthenexamples in this document will indent the body for better readability. 227898184e3Ssthen 228898184e3Ssthen CORRECT 229898184e3Ssthen 230898184e3Ssthen double 231898184e3Ssthen sin(x) 232898184e3Ssthen double x 233898184e3Ssthen 234898184e3SsthenMore complicated XSUBs may contain many other sections. Each section of 235898184e3Ssthenan XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:. 236898184e3SsthenHowever, the first two lines of an XSUB always contain the same data: 237898184e3Ssthendescriptions of the return type and the names of the function and its 238898184e3Ssthenparameters. Whatever immediately follows these is considered to be 239898184e3Ssthenan INPUT: section unless explicitly marked with another keyword. 240898184e3Ssthen(See L<The INPUT: Keyword>.) 241898184e3Ssthen 242898184e3SsthenAn XSUB section continues until another section-start keyword is found. 243898184e3Ssthen 244898184e3Ssthen=head2 The Argument Stack 245898184e3Ssthen 246898184e3SsthenThe Perl argument stack is used to store the values which are 247898184e3Ssthensent as parameters to the XSUB and to store the XSUB's 248898184e3Ssthenreturn value(s). In reality all Perl functions (including non-XSUB 249898184e3Ssthenones) keep their values on this stack all the same time, each limited 250898184e3Ssthento its own range of positions on the stack. In this document the 251898184e3Ssthenfirst position on that stack which belongs to the active 252898184e3Ssthenfunction will be referred to as position 0 for that function. 253898184e3Ssthen 254898184e3SsthenXSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> 255898184e3Ssthenrefers to a position in this XSUB's part of the stack. Position 0 for that 256898184e3Ssthenfunction would be known to the XSUB as ST(0). The XSUB's incoming 257898184e3Ssthenparameters and outgoing return values always begin at ST(0). For many 258898184e3Ssthensimple cases the B<xsubpp> compiler will generate the code necessary to 259898184e3Ssthenhandle the argument stack by embedding code fragments found in the 260898184e3Ssthentypemaps. In more complex cases the programmer must supply the code. 261898184e3Ssthen 262898184e3Ssthen=head2 The RETVAL Variable 263898184e3Ssthen 264898184e3SsthenThe RETVAL variable is a special C variable that is declared automatically 265898184e3Ssthenfor you. The C type of RETVAL matches the return type of the C library 266898184e3Ssthenfunction. The B<xsubpp> compiler will declare this variable in each XSUB 267898184e3Ssthenwith non-C<void> return type. By default the generated C function 268898184e3Ssthenwill use RETVAL to hold the return value of the C library function being 269898184e3Ssthencalled. In simple cases the value of RETVAL will be placed in ST(0) of 270898184e3Ssthenthe argument stack where it can be received by Perl as the return value 271898184e3Ssthenof the XSUB. 272898184e3Ssthen 273898184e3SsthenIf the XSUB has a return type of C<void> then the compiler will 274898184e3Ssthennot declare a RETVAL variable for that function. When using 275898184e3Ssthena PPCODE: section no manipulation of the RETVAL variable is required, the 276898184e3Ssthensection may use direct stack manipulation to place output values on the stack. 277898184e3Ssthen 278898184e3SsthenIf PPCODE: directive is not used, C<void> return value should be used 279898184e3Ssthenonly for subroutines which do not return a value, I<even if> CODE: 280898184e3Ssthendirective is used which sets ST(0) explicitly. 281898184e3Ssthen 282898184e3SsthenOlder versions of this document recommended to use C<void> return 283898184e3Ssthenvalue in such cases. It was discovered that this could lead to 284898184e3Ssthensegfaults in cases when XSUB was I<truly> C<void>. This practice is 285898184e3Ssthennow deprecated, and may be not supported at some future version. Use 286898184e3Ssthenthe return value C<SV *> in such cases. (Currently C<xsubpp> contains 287898184e3Ssthensome heuristic code which tries to disambiguate between "truly-void" 288898184e3Ssthenand "old-practice-declared-as-void" functions. Hence your code is at 289898184e3Ssthenmercy of this heuristics unless you use C<SV *> as return value.) 290898184e3Ssthen 291898184e3Ssthen=head2 Returning SVs, AVs and HVs through RETVAL 292898184e3Ssthen 293898184e3SsthenWhen you're using RETVAL to return an C<SV *>, there's some magic 294898184e3Ssthengoing on behind the scenes that should be mentioned. When you're 295898184e3Ssthenmanipulating the argument stack using the ST(x) macro, for example, 296898184e3Ssthenyou usually have to pay special attention to reference counts. (For 297898184e3Ssthenmore about reference counts, see L<perlguts>.) To make your life 298898184e3Sstheneasier, the typemap file automatically makes C<RETVAL> mortal when 299898184e3Ssthenyou're returning an C<SV *>. Thus, the following two XSUBs are more 300898184e3Ssthenor less equivalent: 301898184e3Ssthen 302898184e3Ssthen void 303898184e3Ssthen alpha() 304898184e3Ssthen PPCODE: 305898184e3Ssthen ST(0) = newSVpv("Hello World",0); 306898184e3Ssthen sv_2mortal(ST(0)); 307898184e3Ssthen XSRETURN(1); 308898184e3Ssthen 309898184e3Ssthen SV * 310898184e3Ssthen beta() 311898184e3Ssthen CODE: 312898184e3Ssthen RETVAL = newSVpv("Hello World",0); 313898184e3Ssthen OUTPUT: 314898184e3Ssthen RETVAL 315898184e3Ssthen 316898184e3SsthenThis is quite useful as it usually improves readability. While 317898184e3Ssthenthis works fine for an C<SV *>, it's unfortunately not as easy 318898184e3Ssthento have C<AV *> or C<HV *> as a return value. You I<should> be 319898184e3Ssthenable to write: 320898184e3Ssthen 321898184e3Ssthen AV * 322898184e3Ssthen array() 323898184e3Ssthen CODE: 324898184e3Ssthen RETVAL = newAV(); 325898184e3Ssthen /* do something with RETVAL */ 326898184e3Ssthen OUTPUT: 327898184e3Ssthen RETVAL 328898184e3Ssthen 329898184e3SsthenBut due to an unfixable bug (fixing it would break lots of existing 330898184e3SsthenCPAN modules) in the typemap file, the reference count of the C<AV *> 331898184e3Ssthenis not properly decremented. Thus, the above XSUB would leak memory 332898184e3Ssthenwhenever it is being called. The same problem exists for C<HV *>, 333898184e3SsthenC<CV *>, and C<SVREF> (which indicates a scalar reference, not 334898184e3Ssthena general C<SV *>). 335898184e3SsthenIn XS code on perls starting with perl 5.16, you can override the 336898184e3Ssthentypemaps for any of these types with a version that has proper 337898184e3Ssthenhandling of refcounts. In your C<TYPEMAP> section, do 338898184e3Ssthen 339898184e3Ssthen AV* T_AVREF_REFCOUNT_FIXED 340898184e3Ssthen 341898184e3Ssthento get the repaired variant. For backward compatibility with older 342898184e3Ssthenversions of perl, you can instead decrement the reference count 343898184e3Ssthenmanually when you're returning one of the aforementioned 344898184e3Ssthentypes using C<sv_2mortal>: 345898184e3Ssthen 346898184e3Ssthen AV * 347898184e3Ssthen array() 348898184e3Ssthen CODE: 349898184e3Ssthen RETVAL = newAV(); 350898184e3Ssthen sv_2mortal((SV*)RETVAL); 351898184e3Ssthen /* do something with RETVAL */ 352898184e3Ssthen OUTPUT: 353898184e3Ssthen RETVAL 354898184e3Ssthen 355898184e3SsthenRemember that you don't have to do this for an C<SV *>. The reference 356898184e3Ssthendocumentation for all core typemaps can be found in L<perlxstypemap>. 357898184e3Ssthen 358898184e3Ssthen=head2 The MODULE Keyword 359898184e3Ssthen 360898184e3SsthenThe MODULE keyword is used to start the XS code and to specify the package 361898184e3Ssthenof the functions which are being defined. All text preceding the first 362898184e3SsthenMODULE keyword is considered C code and is passed through to the output with 363898184e3SsthenPOD stripped, but otherwise untouched. Every XS module will have a 364898184e3Ssthenbootstrap function which is used to hook the XSUBs into Perl. The package 365898184e3Ssthenname of this bootstrap function will match the value of the last MODULE 366898184e3Ssthenstatement in the XS source files. The value of MODULE should always remain 367898184e3Ssthenconstant within the same XS file, though this is not required. 368898184e3Ssthen 369898184e3SsthenThe following example will start the XS code and will place 370898184e3Ssthenall functions in a package named RPC. 371898184e3Ssthen 372898184e3Ssthen MODULE = RPC 373898184e3Ssthen 374898184e3Ssthen=head2 The PACKAGE Keyword 375898184e3Ssthen 376898184e3SsthenWhen functions within an XS source file must be separated into packages 377898184e3Ssthenthe PACKAGE keyword should be used. This keyword is used with the MODULE 378898184e3Ssthenkeyword and must follow immediately after it when used. 379898184e3Ssthen 380898184e3Ssthen MODULE = RPC PACKAGE = RPC 381898184e3Ssthen 382898184e3Ssthen [ XS code in package RPC ] 383898184e3Ssthen 384898184e3Ssthen MODULE = RPC PACKAGE = RPCB 385898184e3Ssthen 386898184e3Ssthen [ XS code in package RPCB ] 387898184e3Ssthen 388898184e3Ssthen MODULE = RPC PACKAGE = RPC 389898184e3Ssthen 390898184e3Ssthen [ XS code in package RPC ] 391898184e3Ssthen 392898184e3SsthenThe same package name can be used more than once, allowing for 393898184e3Ssthennon-contiguous code. This is useful if you have a stronger ordering 394898184e3Ssthenprinciple than package names. 395898184e3Ssthen 396898184e3SsthenAlthough this keyword is optional and in some cases provides redundant 397898184e3Sstheninformation it should always be used. This keyword will ensure that the 398898184e3SsthenXSUBs appear in the desired package. 399898184e3Ssthen 400898184e3Ssthen=head2 The PREFIX Keyword 401898184e3Ssthen 402898184e3SsthenThe PREFIX keyword designates prefixes which should be 403898184e3Ssthenremoved from the Perl function names. If the C function is 404898184e3SsthenC<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will 405898184e3Ssthensee this function as C<gettime()>. 406898184e3Ssthen 407898184e3SsthenThis keyword should follow the PACKAGE keyword when used. 408898184e3SsthenIf PACKAGE is not used then PREFIX should follow the MODULE 409898184e3Ssthenkeyword. 410898184e3Ssthen 411898184e3Ssthen MODULE = RPC PREFIX = rpc_ 412898184e3Ssthen 413898184e3Ssthen MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_ 414898184e3Ssthen 415898184e3Ssthen=head2 The OUTPUT: Keyword 416898184e3Ssthen 417898184e3SsthenThe OUTPUT: keyword indicates that certain function parameters should be 418898184e3Ssthenupdated (new values made visible to Perl) when the XSUB terminates or that 419898184e3Ssthencertain values should be returned to the calling Perl function. For 420898184e3Ssthensimple functions which have no CODE: or PPCODE: section, 421898184e3Ssthensuch as the sin() function above, the RETVAL variable is 422898184e3Ssthenautomatically designated as an output value. For more complex functions 423898184e3Ssthenthe B<xsubpp> compiler will need help to determine which variables are output 424898184e3Ssthenvariables. 425898184e3Ssthen 426898184e3SsthenThis keyword will normally be used to complement the CODE: keyword. 427898184e3SsthenThe RETVAL variable is not recognized as an output variable when the 428898184e3SsthenCODE: keyword is present. The OUTPUT: keyword is used in this 429898184e3Ssthensituation to tell the compiler that RETVAL really is an output 430898184e3Ssthenvariable. 431898184e3Ssthen 432898184e3SsthenThe OUTPUT: keyword can also be used to indicate that function parameters 433898184e3Ssthenare output variables. This may be necessary when a parameter has been 434898184e3Ssthenmodified within the function and the programmer would like the update to 435898184e3Ssthenbe seen by Perl. 436898184e3Ssthen 437898184e3Ssthen bool_t 438898184e3Ssthen rpcb_gettime(host,timep) 439898184e3Ssthen char *host 440898184e3Ssthen time_t &timep 441898184e3Ssthen OUTPUT: 442898184e3Ssthen timep 443898184e3Ssthen 444898184e3SsthenThe OUTPUT: keyword will also allow an output parameter to 445898184e3Ssthenbe mapped to a matching piece of code rather than to a 446898184e3Ssthentypemap. 447898184e3Ssthen 448898184e3Ssthen bool_t 449898184e3Ssthen rpcb_gettime(host,timep) 450898184e3Ssthen char *host 451898184e3Ssthen time_t &timep 452898184e3Ssthen OUTPUT: 453898184e3Ssthen timep sv_setnv(ST(1), (double)timep); 454898184e3Ssthen 455898184e3SsthenB<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the 456898184e3SsthenOUTPUT section of the XSUB, except RETVAL. This is the usually desired 457898184e3Ssthenbehavior, as it takes care of properly invoking 'set' magic on output 458898184e3Ssthenparameters (needed for hash or array element parameters that must be 459898184e3Ssthencreated if they didn't exist). If for some reason, this behavior is 460898184e3Ssthennot desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line 461898184e3Ssthento disable it for the remainder of the parameters in the OUTPUT section. 462898184e3SsthenLikewise, C<SETMAGIC: ENABLE> can be used to reenable it for the 463898184e3Ssthenremainder of the OUTPUT section. See L<perlguts> for more details 464898184e3Ssthenabout 'set' magic. 465898184e3Ssthen 466898184e3Ssthen=head2 The NO_OUTPUT Keyword 467898184e3Ssthen 468898184e3SsthenThe NO_OUTPUT can be placed as the first token of the XSUB. This keyword 469898184e3Ssthenindicates that while the C subroutine we provide an interface to has 470898184e3Ssthena non-C<void> return type, the return value of this C subroutine should not 471898184e3Ssthenbe returned from the generated Perl subroutine. 472898184e3Ssthen 473898184e3SsthenWith this keyword present L<The RETVAL Variable> is created, and in the 474898184e3Ssthengenerated call to the subroutine this variable is assigned to, but the value 475898184e3Ssthenof this variable is not going to be used in the auto-generated code. 476898184e3Ssthen 477898184e3SsthenThis keyword makes sense only if C<RETVAL> is going to be accessed by the 478898184e3Ssthenuser-supplied code. It is especially useful to make a function interface 479898184e3Ssthenmore Perl-like, especially when the C return value is just an error condition 480898184e3Ssthenindicator. For example, 481898184e3Ssthen 482898184e3Ssthen NO_OUTPUT int 483898184e3Ssthen delete_file(char *name) 484898184e3Ssthen POSTCALL: 485898184e3Ssthen if (RETVAL != 0) 486898184e3Ssthen croak("Error %d while deleting file '%s'", RETVAL, name); 487898184e3Ssthen 488898184e3SsthenHere the generated XS function returns nothing on success, and will die() 489898184e3Ssthenwith a meaningful error message on error. 490898184e3Ssthen 491898184e3Ssthen=head2 The CODE: Keyword 492898184e3Ssthen 493898184e3SsthenThis keyword is used in more complicated XSUBs which require 494898184e3Ssthenspecial handling for the C function. The RETVAL variable is 495898184e3Ssthenstill declared, but it will not be returned unless it is specified 496898184e3Ssthenin the OUTPUT: section. 497898184e3Ssthen 498898184e3SsthenThe following XSUB is for a C function which requires special handling of 499898184e3Ssthenits parameters. The Perl usage is given first. 500898184e3Ssthen 501898184e3Ssthen $status = rpcb_gettime( "localhost", $timep ); 502898184e3Ssthen 503898184e3SsthenThe XSUB follows. 504898184e3Ssthen 505898184e3Ssthen bool_t 506898184e3Ssthen rpcb_gettime(host,timep) 507898184e3Ssthen char *host 508898184e3Ssthen time_t timep 509898184e3Ssthen CODE: 510898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 511898184e3Ssthen OUTPUT: 512898184e3Ssthen timep 513898184e3Ssthen RETVAL 514898184e3Ssthen 515898184e3Ssthen=head2 The INIT: Keyword 516898184e3Ssthen 517898184e3SsthenThe INIT: keyword allows initialization to be inserted into the XSUB before 518898184e3Ssthenthe compiler generates the call to the C function. Unlike the CODE: keyword 519898184e3Ssthenabove, this keyword does not affect the way the compiler handles RETVAL. 520898184e3Ssthen 521898184e3Ssthen bool_t 522898184e3Ssthen rpcb_gettime(host,timep) 523898184e3Ssthen char *host 524898184e3Ssthen time_t &timep 525898184e3Ssthen INIT: 526898184e3Ssthen printf("# Host is %s\n", host ); 527898184e3Ssthen OUTPUT: 528898184e3Ssthen timep 529898184e3Ssthen 530898184e3SsthenAnother use for the INIT: section is to check for preconditions before 531898184e3Ssthenmaking a call to the C function: 532898184e3Ssthen 533898184e3Ssthen long long 534898184e3Ssthen lldiv(a,b) 535898184e3Ssthen long long a 536898184e3Ssthen long long b 537898184e3Ssthen INIT: 538898184e3Ssthen if (a == 0 && b == 0) 539898184e3Ssthen XSRETURN_UNDEF; 540898184e3Ssthen if (b == 0) 541898184e3Ssthen croak("lldiv: cannot divide by 0"); 542898184e3Ssthen 543898184e3Ssthen=head2 The NO_INIT Keyword 544898184e3Ssthen 545898184e3SsthenThe NO_INIT keyword is used to indicate that a function 546898184e3Ssthenparameter is being used only as an output value. The B<xsubpp> 547898184e3Ssthencompiler will normally generate code to read the values of 548898184e3Ssthenall function parameters from the argument stack and assign 549898184e3Ssthenthem to C variables upon entry to the function. NO_INIT 550898184e3Ssthenwill tell the compiler that some parameters will be used for 551898184e3Ssthenoutput rather than for input and that they will be handled 552898184e3Ssthenbefore the function terminates. 553898184e3Ssthen 554898184e3SsthenThe following example shows a variation of the rpcb_gettime() function. 555898184e3SsthenThis function uses the timep variable only as an output variable and does 556898184e3Ssthennot care about its initial contents. 557898184e3Ssthen 558898184e3Ssthen bool_t 559898184e3Ssthen rpcb_gettime(host,timep) 560898184e3Ssthen char *host 561898184e3Ssthen time_t &timep = NO_INIT 562898184e3Ssthen OUTPUT: 563898184e3Ssthen timep 564898184e3Ssthen 565898184e3Ssthen=head2 The TYPEMAP: Keyword 566898184e3Ssthen 567898184e3SsthenStarting with Perl 5.16, you can embed typemaps into your XS code 568898184e3Sstheninstead of or in addition to typemaps in a separate file. Multiple 569898184e3Ssthensuch embedded typemaps will be processed in order of appearance in 5706fb12b70Safresh1the XS code and like local typemap files take precedence over the 571898184e3Ssthendefault typemap, the embedded typemaps may overwrite previous 572898184e3Ssthendefinitions of TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for 573898184e3Ssthenembedded typemaps is 574898184e3Ssthen 575898184e3Ssthen TYPEMAP: <<HERE 576898184e3Ssthen ... your typemap code here ... 577898184e3Ssthen HERE 578898184e3Ssthen 579898184e3Ssthenwhere the C<TYPEMAP> keyword must appear in the first column of a 580898184e3Ssthennew line. 581898184e3Ssthen 582898184e3SsthenRefer to L<perlxstypemap> for details on writing typemaps. 583898184e3Ssthen 584898184e3Ssthen=head2 Initializing Function Parameters 585898184e3Ssthen 586898184e3SsthenC function parameters are normally initialized with their values from 587898184e3Ssthenthe argument stack (which in turn contains the parameters that were 588898184e3Ssthenpassed to the XSUB from Perl). The typemaps contain the 589898184e3Ssthencode segments which are used to translate the Perl values to 590898184e3Ssthenthe C parameters. The programmer, however, is allowed to 591898184e3Ssthenoverride the typemaps and supply alternate (or additional) 592898184e3Sstheninitialization code. Initialization code starts with the first 593898184e3SsthenC<=>, C<;> or C<+> on a line in the INPUT: section. The only 594898184e3Ssthenexception happens if this C<;> terminates the line, then this C<;> 595898184e3Ssthenis quietly ignored. 596898184e3Ssthen 597898184e3SsthenThe following code demonstrates how to supply initialization code for 598898184e3Ssthenfunction parameters. The initialization code is eval'ed within double 599898184e3Ssthenquotes by the compiler before it is added to the output so anything 600898184e3Ssthenwhich should be interpreted literally [mainly C<$>, C<@>, or C<\\>] 601898184e3Ssthenmust be protected with backslashes. The variables C<$var>, C<$arg>, 602898184e3Ssthenand C<$type> can be used as in typemaps. 603898184e3Ssthen 604898184e3Ssthen bool_t 605898184e3Ssthen rpcb_gettime(host,timep) 606eac174f2Safresh1 char *host = (char *)SvPVbyte_nolen($arg); 607898184e3Ssthen time_t &timep = 0; 608898184e3Ssthen OUTPUT: 609898184e3Ssthen timep 610898184e3Ssthen 611898184e3SsthenThis should not be used to supply default values for parameters. One 612898184e3Ssthenwould normally use this when a function parameter must be processed by 613898184e3Ssthenanother library function before it can be used. Default parameters are 614898184e3Ssthencovered in the next section. 615898184e3Ssthen 616898184e3SsthenIf the initialization begins with C<=>, then it is output in 617898184e3Ssthenthe declaration for the input variable, replacing the initialization 618898184e3Ssthensupplied by the typemap. If the initialization 619898184e3Ssthenbegins with C<;> or C<+>, then it is performed after 620898184e3Ssthenall of the input variables have been declared. In the C<;> 621898184e3Ssthencase the initialization normally supplied by the typemap is not performed. 622898184e3SsthenFor the C<+> case, the declaration for the variable will include the 623898184e3Sstheninitialization from the typemap. A global 624898184e3Ssthenvariable, C<%v>, is available for the truly rare case where 625898184e3Sstheninformation from one initialization is needed in another 626898184e3Sstheninitialization. 627898184e3Ssthen 628898184e3SsthenHere's a truly obscure example: 629898184e3Ssthen 630898184e3Ssthen bool_t 631898184e3Ssthen rpcb_gettime(host,timep) 632898184e3Ssthen time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */ 633eac174f2Safresh1 char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL; 634898184e3Ssthen OUTPUT: 635898184e3Ssthen timep 636898184e3Ssthen 637898184e3SsthenThe construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above 638898184e3Ssthenexample has a two-fold purpose: first, when this line is processed by 639898184e3SsthenB<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second, 640898184e3Ssthenthe text of the evaluated snippet is output into the generated C file 641898184e3Ssthen(inside a C comment)! During the processing of C<char *host> line, 642898184e3SsthenC<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to 643898184e3SsthenC<ST(1)>. 644898184e3Ssthen 645898184e3Ssthen=head2 Default Parameter Values 646898184e3Ssthen 647898184e3SsthenDefault values for XSUB arguments can be specified by placing an 648898184e3Ssthenassignment statement in the parameter list. The default value may 649898184e3Ssthenbe a number, a string or the special string C<NO_INIT>. Defaults should 650898184e3Ssthenalways be used on the right-most parameters only. 651898184e3Ssthen 652898184e3SsthenTo allow the XSUB for rpcb_gettime() to have a default host 653898184e3Ssthenvalue the parameters to the XSUB could be rearranged. The 654898184e3SsthenXSUB will then call the real rpcb_gettime() function with 655898184e3Ssthenthe parameters in the correct order. This XSUB can be called 656898184e3Ssthenfrom Perl with either of the following statements: 657898184e3Ssthen 658898184e3Ssthen $status = rpcb_gettime( $timep, $host ); 659898184e3Ssthen 660898184e3Ssthen $status = rpcb_gettime( $timep ); 661898184e3Ssthen 662898184e3SsthenThe XSUB will look like the code which follows. A CODE: 663898184e3Ssthenblock is used to call the real rpcb_gettime() function with 664898184e3Ssthenthe parameters in the correct order for that function. 665898184e3Ssthen 666898184e3Ssthen bool_t 667898184e3Ssthen rpcb_gettime(timep,host="localhost") 668898184e3Ssthen char *host 669898184e3Ssthen time_t timep = NO_INIT 670898184e3Ssthen CODE: 671898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 672898184e3Ssthen OUTPUT: 673898184e3Ssthen timep 674898184e3Ssthen RETVAL 675898184e3Ssthen 676898184e3Ssthen=head2 The PREINIT: Keyword 677898184e3Ssthen 678898184e3SsthenThe PREINIT: keyword allows extra variables to be declared immediately 679898184e3Ssthenbefore or after the declarations of the parameters from the INPUT: section 680898184e3Ssthenare emitted. 681898184e3Ssthen 682898184e3SsthenIf a variable is declared inside a CODE: section it will follow any typemap 683898184e3Ssthencode that is emitted for the input parameters. This may result in the 684898184e3Ssthendeclaration ending up after C code, which is C syntax error. Similar 685898184e3Ssthenerrors may happen with an explicit C<;>-type or C<+>-type initialization of 686898184e3Ssthenparameters is used (see L<"Initializing Function Parameters">). Declaring 687898184e3Ssthenthese variables in an INIT: section will not help. 688898184e3Ssthen 689898184e3SsthenIn such cases, to force an additional variable to be declared together 690898184e3Ssthenwith declarations of other variables, place the declaration into a 691898184e3SsthenPREINIT: section. The PREINIT: keyword may be used one or more times 692898184e3Ssthenwithin an XSUB. 693898184e3Ssthen 694898184e3SsthenThe following examples are equivalent, but if the code is using complex 695898184e3Ssthentypemaps then the first example is safer. 696898184e3Ssthen 697898184e3Ssthen bool_t 698898184e3Ssthen rpcb_gettime(timep) 699898184e3Ssthen time_t timep = NO_INIT 700898184e3Ssthen PREINIT: 701898184e3Ssthen char *host = "localhost"; 702898184e3Ssthen CODE: 703898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 704898184e3Ssthen OUTPUT: 705898184e3Ssthen timep 706898184e3Ssthen RETVAL 707898184e3Ssthen 708898184e3SsthenFor this particular case an INIT: keyword would generate the 709898184e3Ssthensame C code as the PREINIT: keyword. Another correct, but error-prone example: 710898184e3Ssthen 711898184e3Ssthen bool_t 712898184e3Ssthen rpcb_gettime(timep) 713898184e3Ssthen time_t timep = NO_INIT 714898184e3Ssthen CODE: 715898184e3Ssthen char *host = "localhost"; 716898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 717898184e3Ssthen OUTPUT: 718898184e3Ssthen timep 719898184e3Ssthen RETVAL 720898184e3Ssthen 721898184e3SsthenAnother way to declare C<host> is to use a C block in the CODE: section: 722898184e3Ssthen 723898184e3Ssthen bool_t 724898184e3Ssthen rpcb_gettime(timep) 725898184e3Ssthen time_t timep = NO_INIT 726898184e3Ssthen CODE: 727898184e3Ssthen { 728898184e3Ssthen char *host = "localhost"; 729898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 730898184e3Ssthen } 731898184e3Ssthen OUTPUT: 732898184e3Ssthen timep 733898184e3Ssthen RETVAL 734898184e3Ssthen 735898184e3SsthenThe ability to put additional declarations before the typemap entries are 736898184e3Ssthenprocessed is very handy in the cases when typemap conversions manipulate 737898184e3Ssthensome global state: 738898184e3Ssthen 739898184e3Ssthen MyObject 740898184e3Ssthen mutate(o) 741898184e3Ssthen PREINIT: 742898184e3Ssthen MyState st = global_state; 743898184e3Ssthen INPUT: 744898184e3Ssthen MyObject o; 745898184e3Ssthen CLEANUP: 746898184e3Ssthen reset_to(global_state, st); 747898184e3Ssthen 748898184e3SsthenHere we suppose that conversion to C<MyObject> in the INPUT: section and from 749898184e3SsthenMyObject when processing RETVAL will modify a global variable C<global_state>. 750898184e3SsthenAfter these conversions are performed, we restore the old value of 751898184e3SsthenC<global_state> (to avoid memory leaks, for example). 752898184e3Ssthen 753898184e3SsthenThere is another way to trade clarity for compactness: INPUT sections allow 754898184e3Ssthendeclaration of C variables which do not appear in the parameter list of 755898184e3Ssthena subroutine. Thus the above code for mutate() can be rewritten as 756898184e3Ssthen 757898184e3Ssthen MyObject 758898184e3Ssthen mutate(o) 759898184e3Ssthen MyState st = global_state; 760898184e3Ssthen MyObject o; 761898184e3Ssthen CLEANUP: 762898184e3Ssthen reset_to(global_state, st); 763898184e3Ssthen 764898184e3Ssthenand the code for rpcb_gettime() can be rewritten as 765898184e3Ssthen 766898184e3Ssthen bool_t 767898184e3Ssthen rpcb_gettime(timep) 768898184e3Ssthen time_t timep = NO_INIT 769898184e3Ssthen char *host = "localhost"; 770898184e3Ssthen C_ARGS: 771898184e3Ssthen host, &timep 772898184e3Ssthen OUTPUT: 773898184e3Ssthen timep 774898184e3Ssthen RETVAL 775898184e3Ssthen 776898184e3Ssthen=head2 The SCOPE: Keyword 777898184e3Ssthen 778898184e3SsthenThe SCOPE: keyword allows scoping to be enabled for a particular XSUB. If 779898184e3Ssthenenabled, the XSUB will invoke ENTER and LEAVE automatically. 780898184e3Ssthen 781898184e3SsthenTo support potentially complex type mappings, if a typemap entry used 782898184e3Ssthenby an XSUB contains a comment like C</*scope*/> then scoping will 783898184e3Ssthenbe automatically enabled for that XSUB. 784898184e3Ssthen 785898184e3SsthenTo enable scoping: 786898184e3Ssthen 787898184e3Ssthen SCOPE: ENABLE 788898184e3Ssthen 789898184e3SsthenTo disable scoping: 790898184e3Ssthen 791898184e3Ssthen SCOPE: DISABLE 792898184e3Ssthen 793898184e3Ssthen=head2 The INPUT: Keyword 794898184e3Ssthen 795898184e3SsthenThe XSUB's parameters are usually evaluated immediately after entering the 796898184e3SsthenXSUB. The INPUT: keyword can be used to force those parameters to be 797898184e3Ssthenevaluated a little later. The INPUT: keyword can be used multiple times 798898184e3Ssthenwithin an XSUB and can be used to list one or more input variables. This 799898184e3Ssthenkeyword is used with the PREINIT: keyword. 800898184e3Ssthen 801898184e3SsthenThe following example shows how the input parameter C<timep> can be 802898184e3Ssthenevaluated late, after a PREINIT. 803898184e3Ssthen 804898184e3Ssthen bool_t 805898184e3Ssthen rpcb_gettime(host,timep) 806898184e3Ssthen char *host 807898184e3Ssthen PREINIT: 808898184e3Ssthen time_t tt; 809898184e3Ssthen INPUT: 810898184e3Ssthen time_t timep 811898184e3Ssthen CODE: 812898184e3Ssthen RETVAL = rpcb_gettime( host, &tt ); 813898184e3Ssthen timep = tt; 814898184e3Ssthen OUTPUT: 815898184e3Ssthen timep 816898184e3Ssthen RETVAL 817898184e3Ssthen 818898184e3SsthenThe next example shows each input parameter evaluated late. 819898184e3Ssthen 820898184e3Ssthen bool_t 821898184e3Ssthen rpcb_gettime(host,timep) 822898184e3Ssthen PREINIT: 823898184e3Ssthen time_t tt; 824898184e3Ssthen INPUT: 825898184e3Ssthen char *host 826898184e3Ssthen PREINIT: 827898184e3Ssthen char *h; 828898184e3Ssthen INPUT: 829898184e3Ssthen time_t timep 830898184e3Ssthen CODE: 831898184e3Ssthen h = host; 832898184e3Ssthen RETVAL = rpcb_gettime( h, &tt ); 833898184e3Ssthen timep = tt; 834898184e3Ssthen OUTPUT: 835898184e3Ssthen timep 836898184e3Ssthen RETVAL 837898184e3Ssthen 838898184e3SsthenSince INPUT sections allow declaration of C variables which do not appear 839898184e3Ssthenin the parameter list of a subroutine, this may be shortened to: 840898184e3Ssthen 841898184e3Ssthen bool_t 842898184e3Ssthen rpcb_gettime(host,timep) 843898184e3Ssthen time_t tt; 844898184e3Ssthen char *host; 845898184e3Ssthen char *h = host; 846898184e3Ssthen time_t timep; 847898184e3Ssthen CODE: 848898184e3Ssthen RETVAL = rpcb_gettime( h, &tt ); 849898184e3Ssthen timep = tt; 850898184e3Ssthen OUTPUT: 851898184e3Ssthen timep 852898184e3Ssthen RETVAL 853898184e3Ssthen 854898184e3Ssthen(We used our knowledge that input conversion for C<char *> is a "simple" one, 855898184e3Ssthenthus C<host> is initialized on the declaration line, and our assignment 856898184e3SsthenC<h = host> is not performed too early. Otherwise one would need to have the 857898184e3Ssthenassignment C<h = host> in a CODE: or INIT: section.) 858898184e3Ssthen 859898184e3Ssthen=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords 860898184e3Ssthen 861898184e3SsthenIn the list of parameters for an XSUB, one can precede parameter names 862898184e3Ssthenby the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords. 863898184e3SsthenC<IN> keyword is the default, the other keywords indicate how the Perl 864898184e3Sstheninterface should differ from the C interface. 865898184e3Ssthen 866898184e3SsthenParameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> 867898184e3Ssthenkeywords are considered to be used by the C subroutine I<via 868898184e3Ssthenpointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine 869898184e3Ssthendoes not inspect the memory pointed by this parameter, but will write 870898184e3Ssthenthrough this pointer to provide additional return values. 871898184e3Ssthen 872898184e3SsthenParameters preceded by C<OUTLIST> keyword do not appear in the usage 873898184e3Ssthensignature of the generated Perl function. 874898184e3Ssthen 875898184e3SsthenParameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as 876898184e3Ssthenparameters to the Perl function. With the exception of 877898184e3SsthenC<OUT>-parameters, these parameters are converted to the corresponding 878898184e3SsthenC type, then pointers to these data are given as arguments to the C 879898184e3Ssthenfunction. It is expected that the C function will write through these 880898184e3Ssthenpointers. 881898184e3Ssthen 882898184e3SsthenThe return list of the generated Perl function consists of the C return value 883898184e3Ssthenfrom the function (unless the XSUB is of C<void> return type or 884898184e3SsthenC<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST> 885898184e3Ssthenand C<IN_OUTLIST> parameters (in the order of appearance). On the 886898184e3Ssthenreturn from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be 887898184e3Ssthenmodified to have the values written by the C function. 888898184e3Ssthen 889898184e3SsthenFor example, an XSUB 890898184e3Ssthen 891898184e3Ssthen void 892898184e3Ssthen day_month(OUTLIST day, IN unix_time, OUTLIST month) 893898184e3Ssthen int day 894898184e3Ssthen int unix_time 895898184e3Ssthen int month 896898184e3Ssthen 897898184e3Ssthenshould be used from Perl as 898898184e3Ssthen 899898184e3Ssthen my ($day, $month) = day_month(time); 900898184e3Ssthen 901898184e3SsthenThe C signature of the corresponding function should be 902898184e3Ssthen 903898184e3Ssthen void day_month(int *day, int unix_time, int *month); 904898184e3Ssthen 905898184e3SsthenThe C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be 906898184e3Ssthenmixed with ANSI-style declarations, as in 907898184e3Ssthen 908898184e3Ssthen void 909898184e3Ssthen day_month(OUTLIST int day, int unix_time, OUTLIST int month) 910898184e3Ssthen 911898184e3Ssthen(here the optional C<IN> keyword is omitted). 912898184e3Ssthen 913898184e3SsthenThe C<IN_OUT> parameters are identical with parameters introduced with 914898184e3SsthenL<The & Unary Operator> and put into the C<OUTPUT:> section (see 915898184e3SsthenL<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar, 916898184e3Ssthenthe only difference being that the value C function writes through the 917898184e3Ssthenpointer would not modify the Perl parameter, but is put in the output 918898184e3Ssthenlist. 919898184e3Ssthen 920898184e3SsthenThe C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT> 921898184e3Ssthenparameters only by the initial value of the Perl parameter not 922898184e3Ssthenbeing read (and not being given to the C function - which gets some 923898184e3Ssthengarbage instead). For example, the same C function as above can be 924898184e3Sstheninterfaced with as 925898184e3Ssthen 926898184e3Ssthen void day_month(OUT int day, int unix_time, OUT int month); 927898184e3Ssthen 928898184e3Ssthenor 929898184e3Ssthen 930898184e3Ssthen void 931898184e3Ssthen day_month(day, unix_time, month) 932898184e3Ssthen int &day = NO_INIT 933898184e3Ssthen int unix_time 934898184e3Ssthen int &month = NO_INIT 935898184e3Ssthen OUTPUT: 936898184e3Ssthen day 937898184e3Ssthen month 938898184e3Ssthen 939898184e3SsthenHowever, the generated Perl function is called in very C-ish style: 940898184e3Ssthen 941898184e3Ssthen my ($day, $month); 942898184e3Ssthen day_month($day, time, $month); 943898184e3Ssthen 944898184e3Ssthen=head2 The C<length(NAME)> Keyword 945898184e3Ssthen 946898184e3SsthenIf one of the input arguments to the C function is the length of a string 947898184e3Ssthenargument C<NAME>, one can substitute the name of the length-argument by 948898184e3SsthenC<length(NAME)> in the XSUB declaration. This argument must be omitted when 949898184e3Ssthenthe generated Perl function is called. E.g., 950898184e3Ssthen 951898184e3Ssthen void 952898184e3Ssthen dump_chars(char *s, short l) 953898184e3Ssthen { 954898184e3Ssthen short n = 0; 955898184e3Ssthen while (n < l) { 956898184e3Ssthen printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]); 957898184e3Ssthen n++; 958898184e3Ssthen } 959898184e3Ssthen } 960898184e3Ssthen 961898184e3Ssthen MODULE = x PACKAGE = x 962898184e3Ssthen 963898184e3Ssthen void dump_chars(char *s, short length(s)) 964898184e3Ssthen 965898184e3Ssthenshould be called as C<dump_chars($string)>. 966898184e3Ssthen 967898184e3SsthenThis directive is supported with ANSI-type function declarations only. 968898184e3Ssthen 969898184e3Ssthen=head2 Variable-length Parameter Lists 970898184e3Ssthen 971898184e3SsthenXSUBs can have variable-length parameter lists by specifying an ellipsis 972898184e3SsthenC<(...)> in the parameter list. This use of the ellipsis is similar to that 973898184e3Ssthenfound in ANSI C. The programmer is able to determine the number of 974898184e3Ssthenarguments passed to the XSUB by examining the C<items> variable which the 975898184e3SsthenB<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can 976898184e3Ssthencreate an XSUB which accepts a list of parameters of unknown length. 977898184e3Ssthen 978898184e3SsthenThe I<host> parameter for the rpcb_gettime() XSUB can be 979898184e3Ssthenoptional so the ellipsis can be used to indicate that the 980898184e3SsthenXSUB will take a variable number of parameters. Perl should 981898184e3Ssthenbe able to call this XSUB with either of the following statements. 982898184e3Ssthen 983898184e3Ssthen $status = rpcb_gettime( $timep, $host ); 984898184e3Ssthen 985898184e3Ssthen $status = rpcb_gettime( $timep ); 986898184e3Ssthen 987898184e3SsthenThe XS code, with ellipsis, follows. 988898184e3Ssthen 989898184e3Ssthen bool_t 990898184e3Ssthen rpcb_gettime(timep, ...) 991898184e3Ssthen time_t timep = NO_INIT 992898184e3Ssthen PREINIT: 993898184e3Ssthen char *host = "localhost"; 994898184e3Ssthen CODE: 995898184e3Ssthen if( items > 1 ) 996eac174f2Safresh1 host = (char *)SvPVbyte_nolen(ST(1)); 997898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 998898184e3Ssthen OUTPUT: 999898184e3Ssthen timep 1000898184e3Ssthen RETVAL 1001898184e3Ssthen 1002898184e3Ssthen=head2 The C_ARGS: Keyword 1003898184e3Ssthen 1004898184e3SsthenThe C_ARGS: keyword allows creating of XSUBS which have different 1005898184e3Ssthencalling sequence from Perl than from C, without a need to write 1006898184e3SsthenCODE: or PPCODE: section. The contents of the C_ARGS: paragraph is 1007898184e3Ssthenput as the argument to the called C function without any change. 1008898184e3Ssthen 1009898184e3SsthenFor example, suppose that a C function is declared as 1010898184e3Ssthen 1011898184e3Ssthen symbolic nth_derivative(int n, symbolic function, int flags); 1012898184e3Ssthen 1013898184e3Ssthenand that the default flags are kept in a global C variable 1014898184e3SsthenC<default_flags>. Suppose that you want to create an interface which 1015898184e3Ssthenis called as 1016898184e3Ssthen 1017898184e3Ssthen $second_deriv = $function->nth_derivative(2); 1018898184e3Ssthen 1019898184e3SsthenTo do this, declare the XSUB as 1020898184e3Ssthen 1021898184e3Ssthen symbolic 1022898184e3Ssthen nth_derivative(function, n) 1023898184e3Ssthen symbolic function 1024898184e3Ssthen int n 1025898184e3Ssthen C_ARGS: 1026898184e3Ssthen n, function, default_flags 1027898184e3Ssthen 1028898184e3Ssthen=head2 The PPCODE: Keyword 1029898184e3Ssthen 1030898184e3SsthenThe PPCODE: keyword is an alternate form of the CODE: keyword and is used 1031898184e3Ssthento tell the B<xsubpp> compiler that the programmer is supplying the code to 1032898184e3Ssthencontrol the argument stack for the XSUBs return values. Occasionally one 1033898184e3Ssthenwill want an XSUB to return a list of values rather than a single value. 1034898184e3SsthenIn these cases one must use PPCODE: and then explicitly push the list of 1035898184e3Ssthenvalues on the stack. The PPCODE: and CODE: keywords should not be used 1036898184e3Ssthentogether within the same XSUB. 1037898184e3Ssthen 1038898184e3SsthenThe actual difference between PPCODE: and CODE: sections is in the 1039898184e3Sstheninitialization of C<SP> macro (which stands for the I<current> Perl 1040898184e3Ssthenstack pointer), and in the handling of data on the stack when returning 1041898184e3Ssthenfrom an XSUB. In CODE: sections SP preserves the value which was on 1042898184e3Ssthenentry to the XSUB: SP is on the function pointer (which follows the 1043898184e3Ssthenlast parameter). In PPCODE: sections SP is moved backward to the 1044898184e3Ssthenbeginning of the parameter list, which allows C<PUSH*()> macros 1045898184e3Ssthento place output values in the place Perl expects them to be when 1046898184e3Ssthenthe XSUB returns back to Perl. 1047898184e3Ssthen 1048898184e3SsthenThe generated trailer for a CODE: section ensures that the number of return 1049898184e3Ssthenvalues Perl will see is either 0 or 1 (depending on the C<void>ness of the 1050898184e3Ssthenreturn value of the C function, and heuristics mentioned in 1051898184e3SsthenL<"The RETVAL Variable">). The trailer generated for a PPCODE: section 1052898184e3Ssthenis based on the number of return values and on the number of times 1053898184e3SsthenC<SP> was updated by C<[X]PUSH*()> macros. 1054898184e3Ssthen 1055898184e3SsthenNote that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally 1056898184e3Ssthenwell in CODE: sections and PPCODE: sections. 1057898184e3Ssthen 1058898184e3SsthenThe following XSUB will call the C rpcb_gettime() function 1059898184e3Ssthenand will return its two output values, timep and status, to 1060898184e3SsthenPerl as a single list. 1061898184e3Ssthen 1062898184e3Ssthen void 1063898184e3Ssthen rpcb_gettime(host) 1064898184e3Ssthen char *host 1065898184e3Ssthen PREINIT: 1066898184e3Ssthen time_t timep; 1067898184e3Ssthen bool_t status; 1068898184e3Ssthen PPCODE: 1069898184e3Ssthen status = rpcb_gettime( host, &timep ); 1070898184e3Ssthen EXTEND(SP, 2); 1071898184e3Ssthen PUSHs(sv_2mortal(newSViv(status))); 1072898184e3Ssthen PUSHs(sv_2mortal(newSViv(timep))); 1073898184e3Ssthen 1074898184e3SsthenNotice that the programmer must supply the C code necessary 1075898184e3Ssthento have the real rpcb_gettime() function called and to have 1076898184e3Ssthenthe return values properly placed on the argument stack. 1077898184e3Ssthen 1078898184e3SsthenThe C<void> return type for this function tells the B<xsubpp> compiler that 1079898184e3Ssthenthe RETVAL variable is not needed or used and that it should not be created. 1080898184e3SsthenIn most scenarios the void return type should be used with the PPCODE: 1081898184e3Ssthendirective. 1082898184e3Ssthen 1083898184e3SsthenThe EXTEND() macro is used to make room on the argument 1084898184e3Ssthenstack for 2 return values. The PPCODE: directive causes the 1085898184e3SsthenB<xsubpp> compiler to create a stack pointer available as C<SP>, and it 1086898184e3Ssthenis this pointer which is being used in the EXTEND() macro. 1087898184e3SsthenThe values are then pushed onto the stack with the PUSHs() 1088898184e3Ssthenmacro. 1089898184e3Ssthen 1090898184e3SsthenNow the rpcb_gettime() function can be used from Perl with 1091898184e3Ssthenthe following statement. 1092898184e3Ssthen 1093898184e3Ssthen ($status, $timep) = rpcb_gettime("localhost"); 1094898184e3Ssthen 1095898184e3SsthenWhen handling output parameters with a PPCODE section, be sure to handle 1096898184e3Ssthen'set' magic properly. See L<perlguts> for details about 'set' magic. 1097898184e3Ssthen 1098898184e3Ssthen=head2 Returning Undef And Empty Lists 1099898184e3Ssthen 1100898184e3SsthenOccasionally the programmer will want to return simply 1101898184e3SsthenC<undef> or an empty list if a function fails rather than a 1102898184e3Ssthenseparate status value. The rpcb_gettime() function offers 1103898184e3Ssthenjust this situation. If the function succeeds we would like 1104898184e3Ssthento have it return the time and if it fails we would like to 1105898184e3Ssthenhave undef returned. In the following Perl code the value 1106898184e3Ssthenof $timep will either be undef or it will be a valid time. 1107898184e3Ssthen 1108898184e3Ssthen $timep = rpcb_gettime( "localhost" ); 1109898184e3Ssthen 1110898184e3SsthenThe following XSUB uses the C<SV *> return type as a mnemonic only, 1111898184e3Ssthenand uses a CODE: block to indicate to the compiler 1112898184e3Ssthenthat the programmer has supplied all the necessary code. The 1113898184e3Ssthensv_newmortal() call will initialize the return value to undef, making that 1114898184e3Ssthenthe default return value. 1115898184e3Ssthen 1116898184e3Ssthen SV * 1117898184e3Ssthen rpcb_gettime(host) 1118898184e3Ssthen char * host 1119898184e3Ssthen PREINIT: 1120898184e3Ssthen time_t timep; 1121898184e3Ssthen bool_t x; 1122898184e3Ssthen CODE: 1123898184e3Ssthen ST(0) = sv_newmortal(); 1124898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 1125898184e3Ssthen sv_setnv( ST(0), (double)timep); 1126898184e3Ssthen 1127898184e3SsthenThe next example demonstrates how one would place an explicit undef in the 1128898184e3Ssthenreturn value, should the need arise. 1129898184e3Ssthen 1130898184e3Ssthen SV * 1131898184e3Ssthen rpcb_gettime(host) 1132898184e3Ssthen char * host 1133898184e3Ssthen PREINIT: 1134898184e3Ssthen time_t timep; 1135898184e3Ssthen bool_t x; 1136898184e3Ssthen CODE: 1137898184e3Ssthen if( rpcb_gettime( host, &timep ) ){ 1138898184e3Ssthen ST(0) = sv_newmortal(); 1139898184e3Ssthen sv_setnv( ST(0), (double)timep); 1140898184e3Ssthen } 1141898184e3Ssthen else{ 1142898184e3Ssthen ST(0) = &PL_sv_undef; 1143898184e3Ssthen } 1144898184e3Ssthen 1145898184e3SsthenTo return an empty list one must use a PPCODE: block and 1146898184e3Ssthenthen not push return values on the stack. 1147898184e3Ssthen 1148898184e3Ssthen void 1149898184e3Ssthen rpcb_gettime(host) 1150898184e3Ssthen char *host 1151898184e3Ssthen PREINIT: 1152898184e3Ssthen time_t timep; 1153898184e3Ssthen PPCODE: 1154898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 1155898184e3Ssthen PUSHs(sv_2mortal(newSViv(timep))); 1156898184e3Ssthen else{ 1157898184e3Ssthen /* Nothing pushed on stack, so an empty 1158898184e3Ssthen * list is implicitly returned. */ 1159898184e3Ssthen } 1160898184e3Ssthen 1161898184e3SsthenSome people may be inclined to include an explicit C<return> in the above 1162898184e3SsthenXSUB, rather than letting control fall through to the end. In those 1163898184e3Ssthensituations C<XSRETURN_EMPTY> should be used, instead. This will ensure that 1164898184e3Ssthenthe XSUB stack is properly adjusted. Consult L<perlapi> for other 1165898184e3SsthenC<XSRETURN> macros. 1166898184e3Ssthen 1167898184e3SsthenSince C<XSRETURN_*> macros can be used with CODE blocks as well, one can 1168898184e3Ssthenrewrite this example as: 1169898184e3Ssthen 1170898184e3Ssthen int 1171898184e3Ssthen rpcb_gettime(host) 1172898184e3Ssthen char *host 1173898184e3Ssthen PREINIT: 1174898184e3Ssthen time_t timep; 1175898184e3Ssthen CODE: 1176898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 1177898184e3Ssthen if (RETVAL == 0) 1178898184e3Ssthen XSRETURN_UNDEF; 1179898184e3Ssthen OUTPUT: 1180898184e3Ssthen RETVAL 1181898184e3Ssthen 1182898184e3SsthenIn fact, one can put this check into a POSTCALL: section as well. Together 1183898184e3Ssthenwith PREINIT: simplifications, this leads to: 1184898184e3Ssthen 1185898184e3Ssthen int 1186898184e3Ssthen rpcb_gettime(host) 1187898184e3Ssthen char *host 1188898184e3Ssthen time_t timep; 1189898184e3Ssthen POSTCALL: 1190898184e3Ssthen if (RETVAL == 0) 1191898184e3Ssthen XSRETURN_UNDEF; 1192898184e3Ssthen 1193898184e3Ssthen=head2 The REQUIRE: Keyword 1194898184e3Ssthen 1195898184e3SsthenThe REQUIRE: keyword is used to indicate the minimum version of the 1196898184e3SsthenB<xsubpp> compiler needed to compile the XS module. An XS module which 1197898184e3Ssthencontains the following statement will compile with only B<xsubpp> version 1198898184e3Ssthen1.922 or greater: 1199898184e3Ssthen 1200898184e3Ssthen REQUIRE: 1.922 1201898184e3Ssthen 1202898184e3Ssthen=head2 The CLEANUP: Keyword 1203898184e3Ssthen 1204898184e3SsthenThis keyword can be used when an XSUB requires special cleanup procedures 1205898184e3Ssthenbefore it terminates. When the CLEANUP: keyword is used it must follow 1206b8851fccSafresh1any CODE:, or OUTPUT: blocks which are present in the XSUB. The code 1207b8851fccSafresh1specified for the cleanup block will be added as the last statements in 1208b8851fccSafresh1the XSUB. 1209898184e3Ssthen 1210898184e3Ssthen=head2 The POSTCALL: Keyword 1211898184e3Ssthen 1212898184e3SsthenThis keyword can be used when an XSUB requires special procedures 1213898184e3Ssthenexecuted after the C subroutine call is performed. When the POSTCALL: 1214898184e3Ssthenkeyword is used it must precede OUTPUT: and CLEANUP: blocks which are 1215898184e3Ssthenpresent in the XSUB. 1216898184e3Ssthen 1217898184e3SsthenSee examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">. 1218898184e3Ssthen 1219898184e3SsthenThe POSTCALL: block does not make a lot of sense when the C subroutine 1220898184e3Ssthencall is supplied by user by providing either CODE: or PPCODE: section. 1221898184e3Ssthen 1222898184e3Ssthen=head2 The BOOT: Keyword 1223898184e3Ssthen 1224898184e3SsthenThe BOOT: keyword is used to add code to the extension's bootstrap 1225898184e3Ssthenfunction. The bootstrap function is generated by the B<xsubpp> compiler and 1226898184e3Ssthennormally holds the statements necessary to register any XSUBs with Perl. 1227898184e3SsthenWith the BOOT: keyword the programmer can tell the compiler to add extra 1228898184e3Ssthenstatements to the bootstrap function. 1229898184e3Ssthen 1230898184e3SsthenThis keyword may be used any time after the first MODULE keyword and should 1231898184e3Ssthenappear on a line by itself. The first blank line after the keyword will 1232898184e3Ssthenterminate the code block. 1233898184e3Ssthen 1234898184e3Ssthen BOOT: 1235898184e3Ssthen # The following message will be printed when the 1236898184e3Ssthen # bootstrap function executes. 1237898184e3Ssthen printf("Hello from the bootstrap!\n"); 1238898184e3Ssthen 1239898184e3Ssthen=head2 The VERSIONCHECK: Keyword 1240898184e3Ssthen 1241898184e3SsthenThe VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and 1242898184e3SsthenC<-noversioncheck> options. This keyword overrides the command line 1243898184e3Ssthenoptions. Version checking is enabled by default. When version checking is 1244898184e3Ssthenenabled the XS module will attempt to verify that its version matches the 1245898184e3Ssthenversion of the PM module. 1246898184e3Ssthen 1247898184e3SsthenTo enable version checking: 1248898184e3Ssthen 1249898184e3Ssthen VERSIONCHECK: ENABLE 1250898184e3Ssthen 1251898184e3SsthenTo disable version checking: 1252898184e3Ssthen 1253898184e3Ssthen VERSIONCHECK: DISABLE 1254898184e3Ssthen 1255898184e3SsthenNote that if the version of the PM module is an NV (a floating point 1256898184e3Ssthennumber), it will be stringified with a possible loss of precision 1257898184e3Ssthen(currently chopping to nine decimal places) so that it may not match 1258898184e3Ssthenthe version of the XS module anymore. Quoting the $VERSION declaration 1259898184e3Ssthento make it a string is recommended if long version numbers are used. 1260898184e3Ssthen 1261898184e3Ssthen=head2 The PROTOTYPES: Keyword 1262898184e3Ssthen 1263898184e3SsthenThe PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and 1264898184e3SsthenC<-noprototypes> options. This keyword overrides the command line options. 1265b8851fccSafresh1Prototypes are disabled by default. When prototypes are enabled, XSUBs will 1266898184e3Ssthenbe given Perl prototypes. This keyword may be used multiple times in an XS 1267898184e3Ssthenmodule to enable and disable prototypes for different parts of the module. 1268b8851fccSafresh1Note that B<xsubpp> will nag you if you don't explicitly enable or disable 1269b8851fccSafresh1prototypes, with: 1270b8851fccSafresh1 1271b8851fccSafresh1 Please specify prototyping behavior for Foo.xs (see perlxs manual) 1272898184e3Ssthen 1273898184e3SsthenTo enable prototypes: 1274898184e3Ssthen 1275898184e3Ssthen PROTOTYPES: ENABLE 1276898184e3Ssthen 1277898184e3SsthenTo disable prototypes: 1278898184e3Ssthen 1279898184e3Ssthen PROTOTYPES: DISABLE 1280898184e3Ssthen 1281898184e3Ssthen=head2 The PROTOTYPE: Keyword 1282898184e3Ssthen 1283898184e3SsthenThis keyword is similar to the PROTOTYPES: keyword above but can be used to 1284898184e3Ssthenforce B<xsubpp> to use a specific prototype for the XSUB. This keyword 1285898184e3Ssthenoverrides all other prototype options and keywords but affects only the 1286898184e3Ssthencurrent XSUB. Consult L<perlsub/Prototypes> for information about Perl 1287898184e3Ssthenprototypes. 1288898184e3Ssthen 1289898184e3Ssthen bool_t 1290898184e3Ssthen rpcb_gettime(timep, ...) 1291898184e3Ssthen time_t timep = NO_INIT 1292898184e3Ssthen PROTOTYPE: $;$ 1293898184e3Ssthen PREINIT: 1294898184e3Ssthen char *host = "localhost"; 1295898184e3Ssthen CODE: 1296898184e3Ssthen if( items > 1 ) 1297eac174f2Safresh1 host = (char *)SvPVbyte_nolen(ST(1)); 1298898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 1299898184e3Ssthen OUTPUT: 1300898184e3Ssthen timep 1301898184e3Ssthen RETVAL 1302898184e3Ssthen 1303898184e3SsthenIf the prototypes are enabled, you can disable it locally for a given 1304898184e3SsthenXSUB as in the following example: 1305898184e3Ssthen 1306898184e3Ssthen void 1307898184e3Ssthen rpcb_gettime_noproto() 1308898184e3Ssthen PROTOTYPE: DISABLE 1309898184e3Ssthen ... 1310898184e3Ssthen 1311898184e3Ssthen=head2 The ALIAS: Keyword 1312898184e3Ssthen 1313898184e3SsthenThe ALIAS: keyword allows an XSUB to have two or more unique Perl names 1314898184e3Ssthenand to know which of those names was used when it was invoked. The Perl 1315898184e3Ssthennames may be fully-qualified with package names. Each alias is given an 1316898184e3Ssthenindex. The compiler will setup a variable called C<ix> which contain the 1317898184e3Ssthenindex of the alias which was used. When the XSUB is called with its 1318898184e3Ssthendeclared name C<ix> will be 0. 1319898184e3Ssthen 1320898184e3SsthenThe following example will create aliases C<FOO::gettime()> and 1321898184e3SsthenC<BAR::getit()> for this function. 1322898184e3Ssthen 1323898184e3Ssthen bool_t 1324898184e3Ssthen rpcb_gettime(host,timep) 1325898184e3Ssthen char *host 1326898184e3Ssthen time_t &timep 1327898184e3Ssthen ALIAS: 1328898184e3Ssthen FOO::gettime = 1 1329898184e3Ssthen BAR::getit = 2 1330898184e3Ssthen INIT: 1331898184e3Ssthen printf("# ix = %d\n", ix ); 1332898184e3Ssthen OUTPUT: 1333898184e3Ssthen timep 1334898184e3Ssthen 1335*e0680481Safresh1A warning will be produced when you create more than one alias to the same 1336*e0680481Safresh1value. This may be worked around in a backwards compatible way by creating 1337*e0680481Safresh1multiple defines which resolve to the same value, or with a modern version 1338*e0680481Safresh1of ExtUtils::ParseXS you can use a symbolic alias, which are denoted with 1339*e0680481Safresh1a C<< => >> instead of a C<< = >>. For instance you could change the above 1340*e0680481Safresh1so that the alias section looked like this: 1341*e0680481Safresh1 1342*e0680481Safresh1 ALIAS: 1343*e0680481Safresh1 FOO::gettime = 1 1344*e0680481Safresh1 BAR::getit = 2 1345*e0680481Safresh1 BAZ::gettime => FOO::gettime 1346*e0680481Safresh1 1347*e0680481Safresh1this would have the same effect as this: 1348*e0680481Safresh1 1349*e0680481Safresh1 ALIAS: 1350*e0680481Safresh1 FOO::gettime = 1 1351*e0680481Safresh1 BAR::getit = 2 1352*e0680481Safresh1 BAZ::gettime = 1 1353*e0680481Safresh1 1354*e0680481Safresh1except that the latter will produce warnings during the build process. A 1355*e0680481Safresh1mechanism that would work in a backwards compatible way with older 1356*e0680481Safresh1versions of our tool chain would be to do this: 1357*e0680481Safresh1 1358*e0680481Safresh1 #define FOO_GETTIME 1 1359*e0680481Safresh1 #define BAR_GETIT 2 1360*e0680481Safresh1 #define BAZ_GETTIME 1 1361*e0680481Safresh1 1362*e0680481Safresh1 bool_t 1363*e0680481Safresh1 rpcb_gettime(host,timep) 1364*e0680481Safresh1 char *host 1365*e0680481Safresh1 time_t &timep 1366*e0680481Safresh1 ALIAS: 1367*e0680481Safresh1 FOO::gettime = FOO_GETTIME 1368*e0680481Safresh1 BAR::getit = BAR_GETIT 1369*e0680481Safresh1 BAZ::gettime = BAZ_GETTIME 1370*e0680481Safresh1 INIT: 1371*e0680481Safresh1 printf("# ix = %d\n", ix ); 1372*e0680481Safresh1 OUTPUT: 1373*e0680481Safresh1 timep 1374*e0680481Safresh1 1375898184e3Ssthen=head2 The OVERLOAD: Keyword 1376898184e3Ssthen 1377898184e3SsthenInstead of writing an overloaded interface using pure Perl, you 1378898184e3Ssthencan also use the OVERLOAD keyword to define additional Perl names 1379898184e3Ssthenfor your functions (like the ALIAS: keyword above). However, the 13809f11ffb7Safresh1overloaded functions must be defined in such a way as to accept the number 13819f11ffb7Safresh1of parameters supplied by perl's overload system. For most overload 13829f11ffb7Safresh1methods, it will be three parameters; for the C<nomethod> function it will 13839f11ffb7Safresh1be four. However, the bitwise operators C<&>, C<|>, C<^>, and C<~> may be 13849f11ffb7Safresh1called with three I<or> five arguments (see L<overload>). 13859f11ffb7Safresh1 13869f11ffb7Safresh1If any 1387898184e3Ssthenfunction has the OVERLOAD: keyword, several additional lines 1388898184e3Ssthenwill be defined in the c file generated by xsubpp in order to 1389898184e3Ssthenregister with the overload magic. 1390898184e3Ssthen 1391898184e3SsthenSince blessed objects are actually stored as RV's, it is useful 1392898184e3Ssthento use the typemap features to preprocess parameters and extract 1393898184e3Ssthenthe actual SV stored within the blessed RV. See the sample for 1394898184e3SsthenT_PTROBJ_SPECIAL below. 1395898184e3Ssthen 1396898184e3SsthenTo use the OVERLOAD: keyword, create an XS function which takes 13979f11ffb7Safresh1three input parameters (or use the C-style '...' definition) like 1398898184e3Ssthenthis: 1399898184e3Ssthen 1400898184e3Ssthen SV * 1401898184e3Ssthen cmp (lobj, robj, swap) 1402898184e3Ssthen My_Module_obj lobj 1403898184e3Ssthen My_Module_obj robj 1404898184e3Ssthen IV swap 1405898184e3Ssthen OVERLOAD: cmp <=> 1406898184e3Ssthen { /* function defined here */} 1407898184e3Ssthen 1408898184e3SsthenIn this case, the function will overload both of the three way 1409898184e3Ssthencomparison operators. For all overload operations using non-alpha 1410898184e3Ssthencharacters, you must type the parameter without quoting, separating 1411898184e3Ssthenmultiple overloads with whitespace. Note that "" (the stringify 1412898184e3Ssthenoverload) should be entered as \"\" (i.e. escaped). 1413898184e3Ssthen 14149f11ffb7Safresh1Since, as mentioned above, bitwise operators may take extra arguments, you 14159f11ffb7Safresh1may want to use something like C<(lobj, robj, swap, ...)> (with 14169f11ffb7Safresh1literal C<...>) as your parameter list. 14179f11ffb7Safresh1 1418898184e3Ssthen=head2 The FALLBACK: Keyword 1419898184e3Ssthen 1420898184e3SsthenIn addition to the OVERLOAD keyword, if you need to control how 1421898184e3SsthenPerl autogenerates missing overloaded operators, you can set the 1422898184e3SsthenFALLBACK keyword in the module header section, like this: 1423898184e3Ssthen 1424898184e3Ssthen MODULE = RPC PACKAGE = RPC 1425898184e3Ssthen 1426898184e3Ssthen FALLBACK: TRUE 1427898184e3Ssthen ... 1428898184e3Ssthen 1429898184e3Ssthenwhere FALLBACK can take any of the three values TRUE, FALSE, or 1430898184e3SsthenUNDEF. If you do not set any FALLBACK value when using OVERLOAD, 1431898184e3Ssthenit defaults to UNDEF. FALLBACK is not used except when one or 1432898184e3Ssthenmore functions using OVERLOAD have been defined. Please see 1433898184e3SsthenL<overload/fallback> for more details. 1434898184e3Ssthen 1435898184e3Ssthen=head2 The INTERFACE: Keyword 1436898184e3Ssthen 1437898184e3SsthenThis keyword declares the current XSUB as a keeper of the given 1438898184e3Ssthencalling signature. If some text follows this keyword, it is 1439898184e3Ssthenconsidered as a list of functions which have this signature, and 1440898184e3Ssthenshould be attached to the current XSUB. 1441898184e3Ssthen 1442898184e3SsthenFor example, if you have 4 C functions multiply(), divide(), add(), 1443898184e3Ssthensubtract() all having the signature: 1444898184e3Ssthen 1445898184e3Ssthen symbolic f(symbolic, symbolic); 1446898184e3Ssthen 1447898184e3Ssthenyou can make them all to use the same XSUB using this: 1448898184e3Ssthen 1449898184e3Ssthen symbolic 1450898184e3Ssthen interface_s_ss(arg1, arg2) 1451898184e3Ssthen symbolic arg1 1452898184e3Ssthen symbolic arg2 1453898184e3Ssthen INTERFACE: 1454898184e3Ssthen multiply divide 1455898184e3Ssthen add subtract 1456898184e3Ssthen 1457898184e3Ssthen(This is the complete XSUB code for 4 Perl functions!) Four generated 1458898184e3SsthenPerl function share names with corresponding C functions. 1459898184e3Ssthen 1460898184e3SsthenThe advantage of this approach comparing to ALIAS: keyword is that there 1461898184e3Ssthenis no need to code a switch statement, each Perl function (which shares 1462898184e3Ssthenthe same XSUB) knows which C function it should call. Additionally, one 1463898184e3Ssthencan attach an extra function remainder() at runtime by using 1464898184e3Ssthen 1465898184e3Ssthen CV *mycv = newXSproto("Symbolic::remainder", 1466898184e3Ssthen XS_Symbolic_interface_s_ss, __FILE__, "$$"); 1467898184e3Ssthen XSINTERFACE_FUNC_SET(mycv, remainder); 1468898184e3Ssthen 1469898184e3Ssthensay, from another XSUB. (This example supposes that there was no 1470898184e3SsthenINTERFACE_MACRO: section, otherwise one needs to use something else instead of 1471898184e3SsthenC<XSINTERFACE_FUNC_SET>, see the next section.) 1472898184e3Ssthen 1473898184e3Ssthen=head2 The INTERFACE_MACRO: Keyword 1474898184e3Ssthen 1475898184e3SsthenThis keyword allows one to define an INTERFACE using a different way 1476898184e3Ssthento extract a function pointer from an XSUB. The text which follows 1477898184e3Ssthenthis keyword should give the name of macros which would extract/set a 1478898184e3Ssthenfunction pointer. The extractor macro is given return type, C<CV*>, 1479898184e3Ssthenand C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv, 1480898184e3Ssthenand the function pointer. 1481898184e3Ssthen 1482898184e3SsthenThe default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>. 1483898184e3SsthenAn INTERFACE keyword with an empty list of functions can be omitted if 1484898184e3SsthenINTERFACE_MACRO keyword is used. 1485898184e3Ssthen 1486898184e3SsthenSuppose that in the previous example functions pointers for 1487898184e3Ssthenmultiply(), divide(), add(), subtract() are kept in a global C array 1488898184e3SsthenC<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>, 1489898184e3SsthenC<subtract_off>. Then one can use 1490898184e3Ssthen 1491898184e3Ssthen #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \ 1492898184e3Ssthen ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32]) 1493898184e3Ssthen #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \ 1494898184e3Ssthen CvXSUBANY(cv).any_i32 = CAT2( f, _off ) 1495898184e3Ssthen 1496898184e3Ssthenin C section, 1497898184e3Ssthen 1498898184e3Ssthen symbolic 1499898184e3Ssthen interface_s_ss(arg1, arg2) 1500898184e3Ssthen symbolic arg1 1501898184e3Ssthen symbolic arg2 1502898184e3Ssthen INTERFACE_MACRO: 1503898184e3Ssthen XSINTERFACE_FUNC_BYOFFSET 1504898184e3Ssthen XSINTERFACE_FUNC_BYOFFSET_set 1505898184e3Ssthen INTERFACE: 1506898184e3Ssthen multiply divide 1507898184e3Ssthen add subtract 1508898184e3Ssthen 1509898184e3Ssthenin XSUB section. 1510898184e3Ssthen 1511898184e3Ssthen=head2 The INCLUDE: Keyword 1512898184e3Ssthen 1513898184e3SsthenThis keyword can be used to pull other files into the XS module. The other 1514898184e3Ssthenfiles may have XS code. INCLUDE: can also be used to run a command to 1515898184e3Ssthengenerate the XS code to be pulled into the module. 1516898184e3Ssthen 1517898184e3SsthenThe file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function: 1518898184e3Ssthen 1519898184e3Ssthen bool_t 1520898184e3Ssthen rpcb_gettime(host,timep) 1521898184e3Ssthen char *host 1522898184e3Ssthen time_t &timep 1523898184e3Ssthen OUTPUT: 1524898184e3Ssthen timep 1525898184e3Ssthen 1526898184e3SsthenThe XS module can use INCLUDE: to pull that file into it. 1527898184e3Ssthen 1528898184e3Ssthen INCLUDE: Rpcb1.xsh 1529898184e3Ssthen 1530898184e3SsthenIf the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then 1531898184e3Ssthenthe compiler will interpret the parameters as a command. This feature is 1532898184e3Ssthenmildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented 1533898184e3Ssthenbelow. 1534898184e3Ssthen 1535898184e3Ssthen INCLUDE: cat Rpcb1.xsh | 1536898184e3Ssthen 1537898184e3SsthenDo not use this to run perl: C<INCLUDE: perl |> will run the perl that 1538898184e3Ssthenhappens to be the first in your path and not necessarily the same perl that is 1539898184e3Ssthenused to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">. 1540898184e3Ssthen 1541898184e3Ssthen=head2 The INCLUDE_COMMAND: Keyword 1542898184e3Ssthen 1543898184e3SsthenRuns the supplied command and includes its output into the current XS 1544898184e3Ssthendocument. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token 1545898184e3Ssthenin that it runs the same perl interpreter that is running C<xsubpp>: 1546898184e3Ssthen 1547898184e3Ssthen INCLUDE_COMMAND: cat Rpcb1.xsh 1548898184e3Ssthen 1549898184e3Ssthen INCLUDE_COMMAND: $^X -e ... 1550898184e3Ssthen 1551898184e3Ssthen=head2 The CASE: Keyword 1552898184e3Ssthen 1553898184e3SsthenThe CASE: keyword allows an XSUB to have multiple distinct parts with each 1554898184e3Ssthenpart acting as a virtual XSUB. CASE: is greedy and if it is used then all 1555898184e3Ssthenother XS keywords must be contained within a CASE:. This means nothing may 1556898184e3Ssthenprecede the first CASE: in the XSUB and anything following the last CASE: is 1557898184e3Ssthenincluded in that case. 1558898184e3Ssthen 1559898184e3SsthenA CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS: 1560898184e3Ssthenvariable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable 1561898184e3Ssthen(see L<"Variable-length Parameter Lists">). The last CASE: becomes the 1562898184e3SsthenB<default> case if it is not associated with a conditional. The following 1563898184e3Ssthenexample shows CASE switched via C<ix> with a function C<rpcb_gettime()> 1564898184e3Ssthenhaving an alias C<x_gettime()>. When the function is called as 1565898184e3SsthenC<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>, 1566898184e3Ssthenbut when the function is called as C<x_gettime()> its parameters are 1567898184e3Ssthenreversed, C<(time_t *timep, char *host)>. 1568898184e3Ssthen 1569898184e3Ssthen long 1570898184e3Ssthen rpcb_gettime(a,b) 1571898184e3Ssthen CASE: ix == 1 1572898184e3Ssthen ALIAS: 1573898184e3Ssthen x_gettime = 1 1574898184e3Ssthen INPUT: 1575898184e3Ssthen # 'a' is timep, 'b' is host 1576898184e3Ssthen char *b 1577898184e3Ssthen time_t a = NO_INIT 1578898184e3Ssthen CODE: 1579898184e3Ssthen RETVAL = rpcb_gettime( b, &a ); 1580898184e3Ssthen OUTPUT: 1581898184e3Ssthen a 1582898184e3Ssthen RETVAL 1583898184e3Ssthen CASE: 1584898184e3Ssthen # 'a' is host, 'b' is timep 1585898184e3Ssthen char *a 1586898184e3Ssthen time_t &b = NO_INIT 1587898184e3Ssthen OUTPUT: 1588898184e3Ssthen b 1589898184e3Ssthen RETVAL 1590898184e3Ssthen 1591898184e3SsthenThat function can be called with either of the following statements. Note 1592898184e3Ssthenthe different argument lists. 1593898184e3Ssthen 1594898184e3Ssthen $status = rpcb_gettime( $host, $timep ); 1595898184e3Ssthen 1596898184e3Ssthen $status = x_gettime( $timep, $host ); 1597898184e3Ssthen 1598898184e3Ssthen=head2 The EXPORT_XSUB_SYMBOLS: Keyword 1599898184e3Ssthen 1600898184e3SsthenThe EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need. 1601898184e3SsthenIn perl versions earlier than 5.16.0, this keyword does nothing. Starting 1602898184e3Ssthenwith 5.16, XSUB symbols are no longer exported by default. That is, they 1603898184e3Ssthenare C<static> functions. If you include 1604898184e3Ssthen 1605898184e3Ssthen EXPORT_XSUB_SYMBOLS: ENABLE 1606898184e3Ssthen 1607898184e3Ssthenin your XS code, the XSUBs following this line will not be declared C<static>. 1608898184e3SsthenYou can later disable this with 1609898184e3Ssthen 1610898184e3Ssthen EXPORT_XSUB_SYMBOLS: DISABLE 1611898184e3Ssthen 1612898184e3Ssthenwhich, again, is the default that you should probably never change. 1613898184e3SsthenYou cannot use this keyword on versions of perl before 5.16 to make 1614898184e3SsthenXSUBs C<static>. 1615898184e3Ssthen 1616898184e3Ssthen=head2 The & Unary Operator 1617898184e3Ssthen 1618898184e3SsthenThe C<&> unary operator in the INPUT: section is used to tell B<xsubpp> 1619898184e3Ssthenthat it should convert a Perl value to/from C using the C type to the left 1620898184e3Ssthenof C<&>, but provide a pointer to this value when the C function is called. 1621898184e3Ssthen 1622898184e3SsthenThis is useful to avoid a CODE: block for a C function which takes a parameter 1623898184e3Ssthenby reference. Typically, the parameter should be not a pointer type (an 1624898184e3SsthenC<int> or C<long> but not an C<int*> or C<long*>). 1625898184e3Ssthen 1626898184e3SsthenThe following XSUB will generate incorrect C code. The B<xsubpp> compiler will 1627898184e3Ssthenturn this into code which calls C<rpcb_gettime()> with parameters C<(char 1628898184e3Ssthen*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep> 1629898184e3Ssthenparameter to be of type C<time_t*> rather than C<time_t>. 1630898184e3Ssthen 1631898184e3Ssthen bool_t 1632898184e3Ssthen rpcb_gettime(host,timep) 1633898184e3Ssthen char *host 1634898184e3Ssthen time_t timep 1635898184e3Ssthen OUTPUT: 1636898184e3Ssthen timep 1637898184e3Ssthen 1638898184e3SsthenThat problem is corrected by using the C<&> operator. The B<xsubpp> compiler 1639898184e3Ssthenwill now turn this into code which calls C<rpcb_gettime()> correctly with 1640898184e3Ssthenparameters C<(char *host, time_t *timep)>. It does this by carrying the 1641898184e3SsthenC<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>. 1642898184e3Ssthen 1643898184e3Ssthen bool_t 1644898184e3Ssthen rpcb_gettime(host,timep) 1645898184e3Ssthen char *host 1646898184e3Ssthen time_t &timep 1647898184e3Ssthen OUTPUT: 1648898184e3Ssthen timep 1649898184e3Ssthen 1650898184e3Ssthen=head2 Inserting POD, Comments and C Preprocessor Directives 1651898184e3Ssthen 1652898184e3SsthenC preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, 1653898184e3SsthenPPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions. 1654898184e3SsthenComments are allowed anywhere after the MODULE keyword. The compiler will 1655898184e3Ssthenpass the preprocessor directives through untouched and will remove the 1656898184e3Ssthencommented lines. POD documentation is allowed at any point, both in the 1657898184e3SsthenC and XS language sections. POD must be terminated with a C<=cut> command; 1658898184e3SsthenC<xsubpp> will exit with an error if it does not. It is very unlikely that 1659898184e3Ssthenhuman generated C code will be mistaken for POD, as most indenting styles 1660898184e3Ssthenresult in whitespace in front of any line starting with C<=>. Machine 1661898184e3Ssthengenerated XS files may fall into this trap unless care is taken to 1662898184e3Ssthenensure that a space breaks the sequence "\n=". 1663898184e3Ssthen 1664898184e3SsthenComments can be added to XSUBs by placing a C<#> as the first 1665898184e3Ssthennon-whitespace of a line. Care should be taken to avoid making the 1666898184e3Ssthencomment look like a C preprocessor directive, lest it be interpreted as 1667898184e3Ssthensuch. The simplest way to prevent this is to put whitespace in front of 1668898184e3Ssthenthe C<#>. 1669898184e3Ssthen 1670898184e3SsthenIf you use preprocessor directives to choose one of two 1671898184e3Ssthenversions of a function, use 1672898184e3Ssthen 1673898184e3Ssthen #if ... version1 1674898184e3Ssthen #else /* ... version2 */ 1675898184e3Ssthen #endif 1676898184e3Ssthen 1677898184e3Ssthenand not 1678898184e3Ssthen 1679898184e3Ssthen #if ... version1 1680898184e3Ssthen #endif 1681898184e3Ssthen #if ... version2 1682898184e3Ssthen #endif 1683898184e3Ssthen 1684898184e3Ssthenbecause otherwise B<xsubpp> will believe that you made a duplicate 1685898184e3Ssthendefinition of the function. Also, put a blank line before the 1686898184e3Ssthen#else/#endif so it will not be seen as part of the function body. 1687898184e3Ssthen 1688898184e3Ssthen=head2 Using XS With C++ 1689898184e3Ssthen 1690898184e3SsthenIf an XSUB name contains C<::>, it is considered to be a C++ method. 1691898184e3SsthenThe generated Perl function will assume that 1692898184e3Ssthenits first argument is an object pointer. The object pointer 1693898184e3Ssthenwill be stored in a variable called THIS. The object should 1694898184e3Ssthenhave been created by C++ with the new() function and should 1695898184e3Ssthenbe blessed by Perl with the sv_setref_pv() macro. The 1696898184e3Ssthenblessing of the object by Perl can be handled by a typemap. An example 1697898184e3Ssthentypemap is shown at the end of this section. 1698898184e3Ssthen 1699898184e3SsthenIf the return type of the XSUB includes C<static>, the method is considered 1700898184e3Ssthento be a static method. It will call the C++ 1701898184e3Ssthenfunction using the class::method() syntax. If the method is not static 1702898184e3Ssthenthe function will be called using the THIS-E<gt>method() syntax. 1703898184e3Ssthen 1704898184e3SsthenThe next examples will use the following C++ class. 1705898184e3Ssthen 1706898184e3Ssthen class color { 1707898184e3Ssthen public: 1708898184e3Ssthen color(); 1709898184e3Ssthen ~color(); 1710898184e3Ssthen int blue(); 1711898184e3Ssthen void set_blue( int ); 1712898184e3Ssthen 1713898184e3Ssthen private: 1714898184e3Ssthen int c_blue; 1715898184e3Ssthen }; 1716898184e3Ssthen 1717898184e3SsthenThe XSUBs for the blue() and set_blue() methods are defined with the class 1718898184e3Ssthenname but the parameter for the object (THIS, or "self") is implicit and is 1719898184e3Ssthennot listed. 1720898184e3Ssthen 1721898184e3Ssthen int 1722898184e3Ssthen color::blue() 1723898184e3Ssthen 1724898184e3Ssthen void 1725898184e3Ssthen color::set_blue( val ) 1726898184e3Ssthen int val 1727898184e3Ssthen 1728898184e3SsthenBoth Perl functions will expect an object as the first parameter. In the 1729898184e3Ssthengenerated C++ code the object is called C<THIS>, and the method call will 1730898184e3Ssthenbe performed on this object. So in the C++ code the blue() and set_blue() 1731898184e3Ssthenmethods will be called as this: 1732898184e3Ssthen 1733898184e3Ssthen RETVAL = THIS->blue(); 1734898184e3Ssthen 1735898184e3Ssthen THIS->set_blue( val ); 1736898184e3Ssthen 1737898184e3SsthenYou could also write a single get/set method using an optional argument: 1738898184e3Ssthen 1739898184e3Ssthen int 1740898184e3Ssthen color::blue( val = NO_INIT ) 1741898184e3Ssthen int val 1742898184e3Ssthen PROTOTYPE $;$ 1743898184e3Ssthen CODE: 1744898184e3Ssthen if (items > 1) 1745898184e3Ssthen THIS->set_blue( val ); 1746898184e3Ssthen RETVAL = THIS->blue(); 1747898184e3Ssthen OUTPUT: 1748898184e3Ssthen RETVAL 1749898184e3Ssthen 1750898184e3SsthenIf the function's name is B<DESTROY> then the C++ C<delete> function will be 1751898184e3Ssthencalled and C<THIS> will be given as its parameter. The generated C++ code for 1752898184e3Ssthen 1753898184e3Ssthen void 1754898184e3Ssthen color::DESTROY() 1755898184e3Ssthen 1756898184e3Ssthenwill look like this: 1757898184e3Ssthen 1758898184e3Ssthen color *THIS = ...; // Initialized as in typemap 1759898184e3Ssthen 1760898184e3Ssthen delete THIS; 1761898184e3Ssthen 1762898184e3SsthenIf the function's name is B<new> then the C++ C<new> function will be called 1763898184e3Ssthento create a dynamic C++ object. The XSUB will expect the class name, which 1764898184e3Ssthenwill be kept in a variable called C<CLASS>, to be given as the first 1765898184e3Ssthenargument. 1766898184e3Ssthen 1767898184e3Ssthen color * 1768898184e3Ssthen color::new() 1769898184e3Ssthen 1770898184e3SsthenThe generated C++ code will call C<new>. 1771898184e3Ssthen 1772898184e3Ssthen RETVAL = new color(); 1773898184e3Ssthen 1774898184e3SsthenThe following is an example of a typemap that could be used for this C++ 1775898184e3Ssthenexample. 1776898184e3Ssthen 1777898184e3Ssthen TYPEMAP 1778898184e3Ssthen color * O_OBJECT 1779898184e3Ssthen 1780898184e3Ssthen OUTPUT 1781898184e3Ssthen # The Perl object is blessed into 'CLASS', which should be a 1782898184e3Ssthen # char* having the name of the package for the blessing. 1783898184e3Ssthen O_OBJECT 1784898184e3Ssthen sv_setref_pv( $arg, CLASS, (void*)$var ); 1785898184e3Ssthen 1786898184e3Ssthen INPUT 1787898184e3Ssthen O_OBJECT 1788898184e3Ssthen if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) ) 1789898184e3Ssthen $var = ($type)SvIV((SV*)SvRV( $arg )); 1790898184e3Ssthen else{ 179156d68f1eSafresh1 warn(\"${Package}::$func_name() -- \" 179256d68f1eSafresh1 \"$var is not a blessed SV reference\"); 1793898184e3Ssthen XSRETURN_UNDEF; 1794898184e3Ssthen } 1795898184e3Ssthen 1796898184e3Ssthen=head2 Interface Strategy 1797898184e3Ssthen 1798898184e3SsthenWhen designing an interface between Perl and a C library a straight 1799898184e3Ssthentranslation from C to XS (such as created by C<h2xs -x>) is often sufficient. 1800898184e3SsthenHowever, sometimes the interface will look 1801898184e3Ssthenvery C-like and occasionally nonintuitive, especially when the C function 1802898184e3Ssthenmodifies one of its parameters, or returns failure inband (as in "negative 1803898184e3Ssthenreturn values mean failure"). In cases where the programmer wishes to 1804898184e3Ssthencreate a more Perl-like interface the following strategy may help to 1805898184e3Ssthenidentify the more critical parts of the interface. 1806898184e3Ssthen 1807898184e3SsthenIdentify the C functions with input/output or output parameters. The XSUBs for 1808898184e3Ssthenthese functions may be able to return lists to Perl. 1809898184e3Ssthen 1810898184e3SsthenIdentify the C functions which use some inband info as an indication 1811898184e3Ssthenof failure. They may be 1812898184e3Ssthencandidates to return undef or an empty list in case of failure. If the 1813898184e3Ssthenfailure may be detected without a call to the C function, you may want to use 1814898184e3Ssthenan INIT: section to report the failure. For failures detectable after the C 1815898184e3Ssthenfunction returns one may want to use a POSTCALL: section to process the 1816898184e3Ssthenfailure. In more complicated cases use CODE: or PPCODE: sections. 1817898184e3Ssthen 1818898184e3SsthenIf many functions use the same failure indication based on the return value, 1819898184e3Ssthenyou may want to create a special typedef to handle this situation. Put 1820898184e3Ssthen 1821898184e3Ssthen typedef int negative_is_failure; 1822898184e3Ssthen 1823898184e3Ssthennear the beginning of XS file, and create an OUTPUT typemap entry 1824898184e3Ssthenfor C<negative_is_failure> which converts negative values to C<undef>, or 1825898184e3Ssthenmaybe croak()s. After this the return value of type C<negative_is_failure> 1826898184e3Ssthenwill create more Perl-like interface. 1827898184e3Ssthen 1828898184e3SsthenIdentify which values are used by only the C and XSUB functions 1829898184e3Ssthenthemselves, say, when a parameter to a function should be a contents of a 1830898184e3Ssthenglobal variable. If Perl does not need to access the contents of the value 1831898184e3Ssthenthen it may not be necessary to provide a translation for that value 1832898184e3Ssthenfrom C to Perl. 1833898184e3Ssthen 1834898184e3SsthenIdentify the pointers in the C function parameter lists and return 1835898184e3Ssthenvalues. Some pointers may be used to implement input/output or 1836898184e3Ssthenoutput parameters, they can be handled in XS with the C<&> unary operator, 1837898184e3Ssthenand, possibly, using the NO_INIT keyword. 1838898184e3SsthenSome others will require handling of types like C<int *>, and one needs 1839898184e3Ssthento decide what a useful Perl translation will do in such a case. When 1840898184e3Ssthenthe semantic is clear, it is advisable to put the translation into a typemap 1841898184e3Ssthenfile. 1842898184e3Ssthen 1843898184e3SsthenIdentify the structures used by the C functions. In many 1844898184e3Ssthencases it may be helpful to use the T_PTROBJ typemap for 1845898184e3Ssthenthese structures so they can be manipulated by Perl as 1846898184e3Ssthenblessed objects. (This is handled automatically by C<h2xs -x>.) 1847898184e3Ssthen 1848898184e3SsthenIf the same C type is used in several different contexts which require 1849898184e3Ssthendifferent translations, C<typedef> several new types mapped to this C type, 1850898184e3Ssthenand create separate F<typemap> entries for these new types. Use these 1851898184e3Ssthentypes in declarations of return type and parameters to XSUBs. 1852898184e3Ssthen 1853898184e3Ssthen=head2 Perl Objects And C Structures 1854898184e3Ssthen 1855898184e3SsthenWhen dealing with C structures one should select either 1856898184e3SsthenB<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are 1857898184e3Ssthendesigned to handle pointers to complex objects. The 1858898184e3SsthenT_PTRREF type will allow the Perl object to be unblessed 1859898184e3Ssthenwhile the T_PTROBJ type requires that the object be blessed. 1860898184e3SsthenBy using T_PTROBJ one can achieve a form of type-checking 1861898184e3Ssthenbecause the XSUB will attempt to verify that the Perl object 1862898184e3Ssthenis of the expected type. 1863898184e3Ssthen 1864898184e3SsthenThe following XS code shows the getnetconfigent() function which is used 1865898184e3Ssthenwith ONC+ TIRPC. The getnetconfigent() function will return a pointer to a 1866898184e3SsthenC structure and has the C prototype shown below. The example will 1867898184e3Ssthendemonstrate how the C pointer will become a Perl reference. Perl will 1868898184e3Ssthenconsider this reference to be a pointer to a blessed object and will 1869898184e3Ssthenattempt to call a destructor for the object. A destructor will be 1870898184e3Ssthenprovided in the XS source to free the memory used by getnetconfigent(). 1871898184e3SsthenDestructors in XS can be created by specifying an XSUB function whose name 1872898184e3Ssthenends with the word B<DESTROY>. XS destructors can be used to free memory 1873898184e3Ssthenwhich may have been malloc'd by another XSUB. 1874898184e3Ssthen 1875898184e3Ssthen struct netconfig *getnetconfigent(const char *netid); 1876898184e3Ssthen 1877898184e3SsthenA C<typedef> will be created for C<struct netconfig>. The Perl 1878898184e3Ssthenobject will be blessed in a class matching the name of the C 1879898184e3Ssthentype, with the tag C<Ptr> appended, and the name should not 1880898184e3Ssthenhave embedded spaces if it will be a Perl package name. The 1881898184e3Ssthendestructor will be placed in a class corresponding to the 1882898184e3Ssthenclass of the object and the PREFIX keyword will be used to 1883898184e3Ssthentrim the name to the word DESTROY as Perl will expect. 1884898184e3Ssthen 1885898184e3Ssthen typedef struct netconfig Netconfig; 1886898184e3Ssthen 1887898184e3Ssthen MODULE = RPC PACKAGE = RPC 1888898184e3Ssthen 1889898184e3Ssthen Netconfig * 1890898184e3Ssthen getnetconfigent(netid) 1891898184e3Ssthen char *netid 1892898184e3Ssthen 1893898184e3Ssthen MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ 1894898184e3Ssthen 1895898184e3Ssthen void 1896898184e3Ssthen rpcb_DESTROY(netconf) 1897898184e3Ssthen Netconfig *netconf 1898898184e3Ssthen CODE: 1899898184e3Ssthen printf("Now in NetconfigPtr::DESTROY\n"); 1900898184e3Ssthen free( netconf ); 1901898184e3Ssthen 1902898184e3SsthenThis example requires the following typemap entry. Consult 1903898184e3SsthenL<perlxstypemap> for more information about adding new typemaps 1904898184e3Ssthenfor an extension. 1905898184e3Ssthen 1906898184e3Ssthen TYPEMAP 1907898184e3Ssthen Netconfig * T_PTROBJ 1908898184e3Ssthen 1909898184e3SsthenThis example will be used with the following Perl statements. 1910898184e3Ssthen 1911898184e3Ssthen use RPC; 1912898184e3Ssthen $netconf = getnetconfigent("udp"); 1913898184e3Ssthen 1914898184e3SsthenWhen Perl destroys the object referenced by $netconf it will send the 1915898184e3Ssthenobject to the supplied XSUB DESTROY function. Perl cannot determine, and 1916898184e3Ssthendoes not care, that this object is a C struct and not a Perl object. In 1917898184e3Ssthenthis sense, there is no difference between the object created by the 1918898184e3Ssthengetnetconfigent() XSUB and an object created by a normal Perl subroutine. 1919898184e3Ssthen 1920898184e3Ssthen=head2 Safely Storing Static Data in XS 1921898184e3Ssthen 1922898184e3SsthenStarting with Perl 5.8, a macro framework has been defined to allow 1923898184e3Ssthenstatic data to be safely stored in XS modules that will be accessed from 1924898184e3Ssthena multi-threaded Perl. 1925898184e3Ssthen 1926898184e3SsthenAlthough primarily designed for use with multi-threaded Perl, the macros 1927898184e3Ssthenhave been designed so that they will work with non-threaded Perl as well. 1928898184e3Ssthen 1929898184e3SsthenIt is therefore strongly recommended that these macros be used by all 1930898184e3SsthenXS modules that make use of static data. 1931898184e3Ssthen 1932898184e3SsthenThe easiest way to get a template set of macros to use is by specifying 1933898184e3Ssthenthe C<-g> (C<--global>) option with h2xs (see L<h2xs>). 1934898184e3Ssthen 1935898184e3SsthenBelow is an example module that makes use of the macros. 1936898184e3Ssthen 19376fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 1938898184e3Ssthen #include "EXTERN.h" 1939898184e3Ssthen #include "perl.h" 1940898184e3Ssthen #include "XSUB.h" 1941898184e3Ssthen 1942898184e3Ssthen /* Global Data */ 1943898184e3Ssthen 1944898184e3Ssthen #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION 1945898184e3Ssthen 1946898184e3Ssthen typedef struct { 1947898184e3Ssthen int count; 1948898184e3Ssthen char name[3][100]; 1949898184e3Ssthen } my_cxt_t; 1950898184e3Ssthen 1951898184e3Ssthen START_MY_CXT 1952898184e3Ssthen 1953898184e3Ssthen MODULE = BlindMice PACKAGE = BlindMice 1954898184e3Ssthen 1955898184e3Ssthen BOOT: 1956898184e3Ssthen { 1957898184e3Ssthen MY_CXT_INIT; 1958898184e3Ssthen MY_CXT.count = 0; 1959898184e3Ssthen strcpy(MY_CXT.name[0], "None"); 1960898184e3Ssthen strcpy(MY_CXT.name[1], "None"); 1961898184e3Ssthen strcpy(MY_CXT.name[2], "None"); 1962898184e3Ssthen } 1963898184e3Ssthen 1964898184e3Ssthen int 1965898184e3Ssthen newMouse(char * name) 1966898184e3Ssthen PREINIT: 1967898184e3Ssthen dMY_CXT; 1968898184e3Ssthen CODE: 1969898184e3Ssthen if (MY_CXT.count >= 3) { 1970898184e3Ssthen warn("Already have 3 blind mice"); 1971898184e3Ssthen RETVAL = 0; 1972898184e3Ssthen } 1973898184e3Ssthen else { 1974898184e3Ssthen RETVAL = ++ MY_CXT.count; 1975898184e3Ssthen strcpy(MY_CXT.name[MY_CXT.count - 1], name); 1976898184e3Ssthen } 19776fb12b70Safresh1 OUTPUT: 19786fb12b70Safresh1 RETVAL 1979898184e3Ssthen 1980898184e3Ssthen char * 1981898184e3Ssthen get_mouse_name(index) 1982898184e3Ssthen int index 19836fb12b70Safresh1 PREINIT: 1984898184e3Ssthen dMY_CXT; 19856fb12b70Safresh1 CODE: 1986898184e3Ssthen if (index > MY_CXT.count) 1987898184e3Ssthen croak("There are only 3 blind mice."); 1988898184e3Ssthen else 19896fb12b70Safresh1 RETVAL = MY_CXT.name[index - 1]; 19906fb12b70Safresh1 OUTPUT: 19916fb12b70Safresh1 RETVAL 1992898184e3Ssthen 1993898184e3Ssthen void 1994898184e3Ssthen CLONE(...) 1995898184e3Ssthen CODE: 1996898184e3Ssthen MY_CXT_CLONE; 1997898184e3Ssthen 19986fb12b70Safresh1=head3 MY_CXT REFERENCE 1999898184e3Ssthen 2000898184e3Ssthen=over 5 2001898184e3Ssthen 2002898184e3Ssthen=item MY_CXT_KEY 2003898184e3Ssthen 2004898184e3SsthenThis macro is used to define a unique key to refer to the static data 2005898184e3Ssthenfor an XS module. The suggested naming scheme, as used by h2xs, is to 2006898184e3Ssthenuse a string that consists of the module name, the string "::_guts" 2007898184e3Ssthenand the module version number. 2008898184e3Ssthen 2009898184e3Ssthen #define MY_CXT_KEY "MyModule::_guts" XS_VERSION 2010898184e3Ssthen 2011898184e3Ssthen=item typedef my_cxt_t 2012898184e3Ssthen 2013898184e3SsthenThis struct typedef I<must> always be called C<my_cxt_t>. The other 2014898184e3SsthenC<CXT*> macros assume the existence of the C<my_cxt_t> typedef name. 2015898184e3Ssthen 2016898184e3SsthenDeclare a typedef named C<my_cxt_t> that is a structure that contains 2017898184e3Ssthenall the data that needs to be interpreter-local. 2018898184e3Ssthen 2019898184e3Ssthen typedef struct { 2020898184e3Ssthen int some_value; 2021898184e3Ssthen } my_cxt_t; 2022898184e3Ssthen 2023898184e3Ssthen=item START_MY_CXT 2024898184e3Ssthen 2025898184e3SsthenAlways place the START_MY_CXT macro directly after the declaration 2026898184e3Ssthenof C<my_cxt_t>. 2027898184e3Ssthen 202856d68f1eSafresh1=for apidoc Amnh||START_MY_CXT 202956d68f1eSafresh1 2030898184e3Ssthen=item MY_CXT_INIT 2031898184e3Ssthen 20326fb12b70Safresh1The MY_CXT_INIT macro initializes storage for the C<my_cxt_t> struct. 2033898184e3Ssthen 2034898184e3SsthenIt I<must> be called exactly once, typically in a BOOT: section. If you 2035898184e3Ssthenare maintaining multiple interpreters, it should be called once in each 2036898184e3Sstheninterpreter instance, except for interpreters cloned from existing ones. 2037898184e3Ssthen(But see L</MY_CXT_CLONE> below.) 2038898184e3Ssthen 203956d68f1eSafresh1=for apidoc Amnh||MY_CXT_INIT 204056d68f1eSafresh1 2041898184e3Ssthen=item dMY_CXT 2042898184e3Ssthen 2043898184e3SsthenUse the dMY_CXT macro (a declaration) in all the functions that access 2044898184e3SsthenMY_CXT. 2045898184e3Ssthen 204656d68f1eSafresh1=for apidoc Amnh||dMY_CXT 204756d68f1eSafresh1 2048898184e3Ssthen=item MY_CXT 2049898184e3Ssthen 2050898184e3SsthenUse the MY_CXT macro to access members of the C<my_cxt_t> struct. For 2051898184e3Ssthenexample, if C<my_cxt_t> is 2052898184e3Ssthen 2053898184e3Ssthen typedef struct { 2054898184e3Ssthen int index; 2055898184e3Ssthen } my_cxt_t; 2056898184e3Ssthen 2057898184e3Ssthenthen use this to access the C<index> member 2058898184e3Ssthen 2059898184e3Ssthen dMY_CXT; 2060898184e3Ssthen MY_CXT.index = 2; 2061898184e3Ssthen 2062898184e3Ssthen=item aMY_CXT/pMY_CXT 2063898184e3Ssthen 2064898184e3SsthenC<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead 2065898184e3Ssthenof invoking it in each function it is possible to pass the declaration 2066898184e3Ssthenonto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg 2067898184e3Ssthen 206856d68f1eSafresh1=for apidoc Amnh||_aMY_CXT 206956d68f1eSafresh1=for apidoc Amnh||aMY_CXT 207056d68f1eSafresh1=for apidoc Amnh||aMY_CXT_ 207156d68f1eSafresh1=for apidoc Amnh||_pMY_CXT 207256d68f1eSafresh1=for apidoc Amnh||pMY_CXT 207356d68f1eSafresh1=for apidoc Amnh||pMY_CXT_ 207456d68f1eSafresh1=for apidoc Amnh||MY_CXT 207556d68f1eSafresh1 2076898184e3Ssthen void sub1() { 2077898184e3Ssthen dMY_CXT; 2078898184e3Ssthen MY_CXT.index = 1; 2079898184e3Ssthen sub2(aMY_CXT); 2080898184e3Ssthen } 2081898184e3Ssthen 2082898184e3Ssthen void sub2(pMY_CXT) { 2083898184e3Ssthen MY_CXT.index = 2; 2084898184e3Ssthen } 2085898184e3Ssthen 2086898184e3SsthenAnalogously to C<pTHX>, there are equivalent forms for when the macro is the 2087898184e3Ssthenfirst or last in multiple arguments, where an underscore represents a 2088898184e3Ssthencomma, i.e. C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>. 2089898184e3Ssthen 2090898184e3Ssthen=item MY_CXT_CLONE 2091898184e3Ssthen 2092898184e3SsthenBy default, when a new interpreter is created as a copy of an existing one 2093898184e3Ssthen(eg via C<< threads->create() >>), both interpreters share the same physical 2094898184e3Ssthenmy_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's 2095898184e3SsthenC<CLONE()> function), causes a byte-for-byte copy of the structure to be 2096898184e3Ssthentaken, and any future dMY_CXT will cause the copy to be accessed instead. 2097898184e3Ssthen 209856d68f1eSafresh1=for apidoc Amnh||MY_CXT_CLONE 209956d68f1eSafresh1 2100898184e3Ssthen=item MY_CXT_INIT_INTERP(my_perl) 2101898184e3Ssthen 2102898184e3Ssthen=item dMY_CXT_INTERP(my_perl) 2103898184e3Ssthen 2104898184e3SsthenThese are versions of the macros which take an explicit interpreter as an 2105898184e3Ssthenargument. 2106898184e3Ssthen 2107898184e3Ssthen=back 2108898184e3Ssthen 2109898184e3SsthenNote that these macros will only work together within the I<same> source 2110898184e3Ssthenfile; that is, a dMY_CTX in one source file will access a different structure 2111898184e3Ssthenthan a dMY_CTX in another source file. 2112898184e3Ssthen 2113898184e3Ssthen=head2 Thread-aware system interfaces 2114898184e3Ssthen 2115898184e3SsthenStarting from Perl 5.8, in C/C++ level Perl knows how to wrap 2116898184e3Ssthensystem/library interfaces that have thread-aware versions 2117898184e3Ssthen(e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that 2118898184e3Ssthencorrectly handle the multithreaded interaction with the Perl 2119898184e3Sstheninterpreter. This will happen transparently, the only thing 2120898184e3Ssthenyou need to do is to instantiate a Perl interpreter. 2121898184e3Ssthen 2122898184e3SsthenThis wrapping happens always when compiling Perl core source 2123898184e3Ssthen(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is 21249f11ffb7Safresh1defined). When compiling XS code outside of the Perl core, the wrapping 21259f11ffb7Safresh1does not take place before Perl 5.28. Starting in that release you can 21269f11ffb7Safresh1 21279f11ffb7Safresh1 #define PERL_REENTRANT 21289f11ffb7Safresh1 21299f11ffb7Safresh1in your code to enable the wrapping. It is advisable to do so if you 21309f11ffb7Safresh1are using such functions, as intermixing the C<_r>-forms (as Perl compiled 21319f11ffb7Safresh1for multithreaded operation will do) and the C<_r>-less forms is neither 21329f11ffb7Safresh1well-defined (inconsistent results, data corruption, or even crashes 21339f11ffb7Safresh1become more likely), nor is it very portable. Unfortunately, not all 21349f11ffb7Safresh1systems have all the C<_r> forms, but using this C<#define> gives you 21359f11ffb7Safresh1whatever protection that Perl is aware is available on each system. 2136898184e3Ssthen 2137898184e3Ssthen=head1 EXAMPLES 2138898184e3Ssthen 2139898184e3SsthenFile C<RPC.xs>: Interface to some ONC+ RPC bind library functions. 2140898184e3Ssthen 21416fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 2142898184e3Ssthen #include "EXTERN.h" 2143898184e3Ssthen #include "perl.h" 2144898184e3Ssthen #include "XSUB.h" 2145898184e3Ssthen 2146eac174f2Safresh1 /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */ 2147eac174f2Safresh1 #include <tirpc/rpc.h> 2148898184e3Ssthen 2149898184e3Ssthen typedef struct netconfig Netconfig; 2150898184e3Ssthen 2151898184e3Ssthen MODULE = RPC PACKAGE = RPC 2152898184e3Ssthen 2153898184e3Ssthen SV * 2154898184e3Ssthen rpcb_gettime(host="localhost") 2155898184e3Ssthen char *host 2156898184e3Ssthen PREINIT: 2157898184e3Ssthen time_t timep; 2158898184e3Ssthen CODE: 2159898184e3Ssthen ST(0) = sv_newmortal(); 2160898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 2161898184e3Ssthen sv_setnv( ST(0), (double)timep ); 2162898184e3Ssthen 2163898184e3Ssthen Netconfig * 2164898184e3Ssthen getnetconfigent(netid="udp") 2165898184e3Ssthen char *netid 2166898184e3Ssthen 2167898184e3Ssthen MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ 2168898184e3Ssthen 2169898184e3Ssthen void 2170898184e3Ssthen rpcb_DESTROY(netconf) 2171898184e3Ssthen Netconfig *netconf 2172898184e3Ssthen CODE: 2173898184e3Ssthen printf("NetconfigPtr::DESTROY\n"); 2174898184e3Ssthen free( netconf ); 2175898184e3Ssthen 2176898184e3SsthenFile C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>) 2177898184e3Ssthen 2178898184e3Ssthen TYPEMAP 2179898184e3Ssthen Netconfig * T_PTROBJ 2180898184e3Ssthen 2181898184e3SsthenFile C<RPC.pm>: Perl module for the RPC extension. 2182898184e3Ssthen 2183898184e3Ssthen package RPC; 2184898184e3Ssthen 2185898184e3Ssthen require Exporter; 2186898184e3Ssthen require DynaLoader; 2187898184e3Ssthen @ISA = qw(Exporter DynaLoader); 2188898184e3Ssthen @EXPORT = qw(rpcb_gettime getnetconfigent); 2189898184e3Ssthen 2190898184e3Ssthen bootstrap RPC; 2191898184e3Ssthen 1; 2192898184e3Ssthen 2193898184e3SsthenFile C<rpctest.pl>: Perl test program for the RPC extension. 2194898184e3Ssthen 2195898184e3Ssthen use RPC; 2196898184e3Ssthen 2197898184e3Ssthen $netconf = getnetconfigent(); 2198898184e3Ssthen $a = rpcb_gettime(); 2199898184e3Ssthen print "time = $a\n"; 2200898184e3Ssthen print "netconf = $netconf\n"; 2201898184e3Ssthen 2202898184e3Ssthen $netconf = getnetconfigent("tcp"); 2203898184e3Ssthen $a = rpcb_gettime("poplar"); 2204898184e3Ssthen print "time = $a\n"; 2205898184e3Ssthen print "netconf = $netconf\n"; 2206898184e3Ssthen 2207eac174f2Safresh1In Makefile.PL add -ltirpc and -I/usr/include/tirpc. 2208eac174f2Safresh1 22096fb12b70Safresh1=head1 CAVEATS 22106fb12b70Safresh1 22116fb12b70Safresh1XS code has full access to system calls including C library functions. 22126fb12b70Safresh1It thus has the capability of interfering with things that the Perl core 22136fb12b70Safresh1or other modules have set up, such as signal handlers or file handles. 22146fb12b70Safresh1It could mess with the memory, or any number of harmful things. Don't. 22156fb12b70Safresh1 22166fb12b70Safresh1Some modules have an event loop, waiting for user-input. It is highly 22176fb12b70Safresh1unlikely that two such modules would work adequately together in a 22186fb12b70Safresh1single Perl application. 22196fb12b70Safresh1 22206fb12b70Safresh1In general, the perl interpreter views itself as the center of the 22216fb12b70Safresh1universe as far as the Perl program goes. XS code is viewed as a 22226fb12b70Safresh1help-mate, to accomplish things that perl doesn't do, or doesn't do fast 22236fb12b70Safresh1enough, but always subservient to perl. The closer XS code adheres to 22246fb12b70Safresh1this model, the less likely conflicts will occur. 22256fb12b70Safresh1 22266fb12b70Safresh1One area where there has been conflict is in regards to C locales. (See 22276fb12b70Safresh1L<perllocale>.) perl, with one exception and unless told otherwise, 2228b8851fccSafresh1sets up the underlying locale the program is running in to the locale 2229b8851fccSafresh1passed 2230b8851fccSafresh1into it from the environment. This is an important difference from a 2231b8851fccSafresh1generic C language program, where the underlying locale is the "C" 2232b8851fccSafresh1locale unless the program changes it. As of v5.20, this underlying 22339f11ffb7Safresh1locale is completely hidden from pure Perl code outside the lexical 2234b8851fccSafresh1scope of C<S<use locale>> except for a couple of function calls in the 2235b8851fccSafresh1POSIX module which of necessity use it. But the underlying locale, with 2236b8851fccSafresh1that 2237b8851fccSafresh1one exception is exposed to XS code, affecting all C library routines 2238b8851fccSafresh1whose behavior is locale-dependent. Your XS code better not assume that 2239b8851fccSafresh1the underlying locale is "C". The exception is the 22406fb12b70Safresh1L<C<LC_NUMERIC>|perllocale/Category LC_NUMERIC: Numeric Formatting> 22416fb12b70Safresh1locale category, and the reason it is an exception is that experience 22426fb12b70Safresh1has shown that it can be problematic for XS code, whereas we have not 22436fb12b70Safresh1had reports of problems with the 22446fb12b70Safresh1L<other locale categories|perllocale/WHAT IS A LOCALE>. And the reason 22456fb12b70Safresh1for this one category being problematic is that the character used as a 22466fb12b70Safresh1decimal point can vary. Many European languages use a comma, whereas 22476fb12b70Safresh1English, and hence Perl are expecting a dot (U+002E: FULL STOP). Many 22486fb12b70Safresh1modules can handle only the radix character being a dot, and so perl 22496fb12b70Safresh1attempts to make it so. Up through Perl v5.20, the attempt was merely 22506fb12b70Safresh1to set C<LC_NUMERIC> upon startup to the C<"C"> locale. Any 22516fb12b70Safresh1L<setlocale()|perllocale/The setlocale function> otherwise would change 22526fb12b70Safresh1it; this caused some failures. Therefore, starting in v5.22, perl tries 22536fb12b70Safresh1to keep C<LC_NUMERIC> always set to C<"C"> for XS code. 22546fb12b70Safresh1 22556fb12b70Safresh1To summarize, here's what to expect and how to handle locales in XS code: 22566fb12b70Safresh1 22576fb12b70Safresh1=over 22586fb12b70Safresh1 22596fb12b70Safresh1=item Non-locale-aware XS code 22606fb12b70Safresh1 22616fb12b70Safresh1Keep in mind that even if you think your code is not locale-aware, it 22629f11ffb7Safresh1may call a library function that is. Hopefully the man page for such 22636fb12b70Safresh1a function will indicate that dependency, but the documentation is 22646fb12b70Safresh1imperfect. 22656fb12b70Safresh1 2266b8851fccSafresh1The current locale is exposed to XS code except possibly C<LC_NUMERIC> 2267b8851fccSafresh1(explained in the next paragraph). 2268b8851fccSafresh1There have not been reports of problems with the other categories. 2269b8851fccSafresh1Perl initializes things on start-up so that the current locale is the 2270b8851fccSafresh1one which is indicated by the user's environment in effect at that time. 2271b8851fccSafresh1See L<perllocale/ENVIRONMENT>. 22726fb12b70Safresh1 2273b8851fccSafresh1However, up through v5.20, Perl initialized things on start-up so that 2274b8851fccSafresh1C<LC_NUMERIC> was set to the "C" locale. But if any code anywhere 2275b8851fccSafresh1changed it, it would stay changed. This means that your module can't 22766fb12b70Safresh1count on C<LC_NUMERIC> being something in particular, and you can't 22776fb12b70Safresh1expect floating point numbers (including version strings) to have dots 22786fb12b70Safresh1in them. If you don't allow for a non-dot, your code could break if 2279b8851fccSafresh1anyone anywhere changed the locale. For this reason, v5.22 changed 22806fb12b70Safresh1the behavior so that Perl tries to keep C<LC_NUMERIC> in the "C" locale 22816fb12b70Safresh1except around the operations internally where it should be something 22826fb12b70Safresh1else. Misbehaving XS code will always be able to change the locale 22836fb12b70Safresh1anyway, but the most common instance of this is checked for and 22846fb12b70Safresh1handled. 22856fb12b70Safresh1 22866fb12b70Safresh1=item Locale-aware XS code 22876fb12b70Safresh1 22886fb12b70Safresh1If the locale from the user's environment is desired, there should be no 22896fb12b70Safresh1need for XS code to set the locale except for C<LC_NUMERIC>, as perl has 22909f11ffb7Safresh1already set the others up. XS code should avoid changing the locale, as 22919f11ffb7Safresh1it can adversely affect other, unrelated, code and may not be 22929f11ffb7Safresh1thread-safe. To minimize problems, the macros 22939f11ffb7Safresh1L<perlapi/STORE_LC_NUMERIC_SET_TO_NEEDED>, 22949f11ffb7Safresh1L<perlapi/STORE_LC_NUMERIC_FORCE_TO_UNDERLYING>, and 22959f11ffb7Safresh1L<perlapi/RESTORE_LC_NUMERIC> should be used to affect any needed 22969f11ffb7Safresh1change. 22979f11ffb7Safresh1 22989f11ffb7Safresh1But, starting with Perl v5.28, locales are thread-safe on platforms that 22999f11ffb7Safresh1support this functionality. Windows has this starting with Visual 23009f11ffb7Safresh1Studio 2005. Many other modern platforms support the thread-safe POSIX 23019f11ffb7Safresh12008 functions. The C C<#define> C<USE_THREAD_SAFE_LOCALE> will be 23029f11ffb7Safresh1defined iff this build is using these. From Perl-space, the read-only 23039f11ffb7Safresh1variable C<${SAFE_LOCALES}> is 1 if either the build is not threaded, or 23049f11ffb7Safresh1if C<USE_THREAD_SAFE_LOCALE> is defined; otherwise it is 0. 23059f11ffb7Safresh1 23069f11ffb7Safresh1The way this works under-the-hood is that every thread has a choice of 23079f11ffb7Safresh1using a locale specific to it (this is the Windows and POSIX 2008 23089f11ffb7Safresh1functionality), or the global locale that is accessible to all threads 23099f11ffb7Safresh1(this is the functionality that has always been there). The 23109f11ffb7Safresh1implementations for Windows and POSIX are completely different. On 23119f11ffb7Safresh1Windows, the runtime can be set up so that the standard 23129f11ffb7Safresh1L<C<setlocale(3)>> function either only knows about the global locale or 23139f11ffb7Safresh1the locale for this thread. On POSIX, C<setlocale> always deals with 23149f11ffb7Safresh1the global locale, and other functions have been created to handle 23159f11ffb7Safresh1per-thread locales. Perl makes this transparent to perl-space code. It 23169f11ffb7Safresh1continues to use C<POSIX::setlocale()>, and the interpreter translates 23179f11ffb7Safresh1that into the per-thread functions. 23189f11ffb7Safresh1 2319eac174f2Safresh1All other locale-sensitive functions automatically use the per-thread 23209f11ffb7Safresh1locale, if that is turned on, and failing that, the global locale. Thus 23219f11ffb7Safresh1calls to C<setlocale> are ineffective on POSIX systems for the current 23229f11ffb7Safresh1thread if that thread is using a per-thread locale. If perl is compiled 23239f11ffb7Safresh1for single-thread operation, it does not use the per-thread functions, 23249f11ffb7Safresh1so C<setlocale> does work as expected. 23259f11ffb7Safresh1 23269f11ffb7Safresh1If you have loaded the L<C<POSIX>> module you can use the methods given 23279f11ffb7Safresh1in L<perlcall> to call L<C<POSIX::setlocale>|POSIX/setlocale> to safely 23289f11ffb7Safresh1change or query the locale (on systems where it is safe to do so), or 23299f11ffb7Safresh1you can use the new 5.28 function L<perlapi/Perl_setlocale> instead, 23309f11ffb7Safresh1which is a drop-in replacement for the system L<C<setlocale(3)>>, and 23319f11ffb7Safresh1handles single-threaded and multi-threaded applications transparently. 23329f11ffb7Safresh1 23339f11ffb7Safresh1There are some locale-related library calls that still aren't 23349f11ffb7Safresh1thread-safe because they return data in a buffer global to all threads. 23359f11ffb7Safresh1In the past, these didn't matter as locales weren't thread-safe at all. 23369f11ffb7Safresh1But now you have to be aware of them in case your module is called in a 23379f11ffb7Safresh1multi-threaded application. The known ones are 23389f11ffb7Safresh1 23399f11ffb7Safresh1 asctime() 23409f11ffb7Safresh1 ctime() 23419f11ffb7Safresh1 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] 23429f11ffb7Safresh1 getdate() 23439f11ffb7Safresh1 wcrtomb() if its final argument is NULL 23449f11ffb7Safresh1 wcsrtombs() if its final argument is NULL 23459f11ffb7Safresh1 wcstombs() 23469f11ffb7Safresh1 wctomb() 23479f11ffb7Safresh1 23489f11ffb7Safresh1Some of these shouldn't really be called in a Perl application, and for 23499f11ffb7Safresh1others there are thread-safe versions of these already implemented: 23509f11ffb7Safresh1 23519f11ffb7Safresh1 asctime_r() 23529f11ffb7Safresh1 ctime_r() 23539f11ffb7Safresh1 Perl_langinfo() 23549f11ffb7Safresh1 23559f11ffb7Safresh1The C<_r> forms are automatically used, starting in Perl 5.28, if you 23569f11ffb7Safresh1compile your code, with 23579f11ffb7Safresh1 23589f11ffb7Safresh1 #define PERL_REENTRANT 23599f11ffb7Safresh1 23609f11ffb7Safresh1See also L<perlapi/Perl_langinfo>. 23619f11ffb7Safresh1You can use the methods given in L<perlcall>, to get the best available 23629f11ffb7Safresh1locale-safe versions of these 23639f11ffb7Safresh1 23649f11ffb7Safresh1 POSIX::localeconv() 23659f11ffb7Safresh1 POSIX::wcstombs() 23669f11ffb7Safresh1 POSIX::wctomb() 23679f11ffb7Safresh1 23689f11ffb7Safresh1And note, that some items returned by C<Localeconv> are available 23699f11ffb7Safresh1through L<perlapi/Perl_langinfo>. 23709f11ffb7Safresh1 23719f11ffb7Safresh1The others shouldn't be used in a threaded application. 23729f11ffb7Safresh1 23739f11ffb7Safresh1Some modules may call a non-perl library that is locale-aware. This is 23749f11ffb7Safresh1fine as long as it doesn't try to query or change the locale using the 23759f11ffb7Safresh1system C<setlocale>. But if these do call the system C<setlocale>, 23769f11ffb7Safresh1those calls may be ineffective. Instead, 23779f11ffb7Safresh1L<C<Perl_setlocale>|perlapi/Perl_setlocale> works in all circumstances. 23789f11ffb7Safresh1Plain setlocale is ineffective on multi-threaded POSIX 2008 systems. It 23799f11ffb7Safresh1operates only on the global locale, whereas each thread has its own 23809f11ffb7Safresh1locale, paying no attention to the global one. Since converting 23819f11ffb7Safresh1these non-Perl libraries to C<Perl_setlocale> is out of the question, 23829f11ffb7Safresh1there is a new function in v5.28 23839f11ffb7Safresh1L<C<switch_to_global_locale>|perlapi/switch_to_global_locale> that will 23849f11ffb7Safresh1switch the thread it is called from so that any system C<setlocale> 23859f11ffb7Safresh1calls will have their desired effect. The function 23869f11ffb7Safresh1L<C<sync_locale>|perlapi/sync_locale> must be called before returning to 23879f11ffb7Safresh1perl. 23889f11ffb7Safresh1 23899f11ffb7Safresh1This thread can change the locale all it wants and it won't affect any 23909f11ffb7Safresh1other thread, except any that also have been switched to the global 23919f11ffb7Safresh1locale. This means that a multi-threaded application can have a single 23929f11ffb7Safresh1thread using an alien library without a problem; but no more than a 23939f11ffb7Safresh1single thread can be so-occupied. Bad results likely will happen. 23949f11ffb7Safresh1 23959f11ffb7Safresh1In perls without multi-thread locale support, some alien libraries, 23969f11ffb7Safresh1such as C<Gtk> change locales. This can cause problems for the Perl 23979f11ffb7Safresh1core and other modules. For these, before control is returned to 23989f11ffb7Safresh1perl, starting in v5.20.1, calling the function 23996fb12b70Safresh1L<sync_locale()|perlapi/sync_locale> from XS should be sufficient to 24006fb12b70Safresh1avoid most of these problems. Prior to this, you need a pure Perl 2401b8851fccSafresh1statement that does this: 24026fb12b70Safresh1 24036fb12b70Safresh1 POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL)); 24046fb12b70Safresh1 24059f11ffb7Safresh1or use the methods given in L<perlcall>. 24066fb12b70Safresh1 24076fb12b70Safresh1=back 2408898184e3Ssthen 2409898184e3Ssthen=head1 XS VERSION 2410898184e3Ssthen 2411898184e3SsthenThis document covers features supported by C<ExtUtils::ParseXS> 2412*e0680481Safresh1(also known as C<xsubpp>) 3.51 2413*e0680481Safresh1 2414*e0680481Safresh1=head1 AUTHOR DIAGNOSTICS 2415*e0680481Safresh1 2416*e0680481Safresh1As of version 3.49 certain warnings are disabled by default. While developing 2417*e0680481Safresh1you can set C<$ENV{AUTHOR_WARNINGS}> to true in your environment or in your 2418*e0680481Safresh1Makefile.PL, or set C<$ExtUtils::ParseXS::AUTHOR_WARNINGS> to true via code, or 2419*e0680481Safresh1pass C<< author_warnings=>1 >> into process_file() explicitly. Currently this will 2420*e0680481Safresh1enable stricter alias checking but more warnings might be added in the future. 2421*e0680481Safresh1The kind of warnings this will enable are only helpful to the author of the XS 2422*e0680481Safresh1file, and the diagnostics produced will not include installation specific 2423*e0680481Safresh1details so they are only useful to the maintainer of the XS code itself. 2424898184e3Ssthen 2425898184e3Ssthen=head1 AUTHOR 2426898184e3Ssthen 2427898184e3SsthenOriginally written by Dean Roehrich <F<roehrich@cray.com>>. 2428898184e3Ssthen 2429eac174f2Safresh1Maintained since 1996 by The Perl Porters <F<perl5-porters@perl.org>>. 2430