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 25898184e3SsthenPerl values to the formats expected by a C function, call this C function, 26898184e3Ssthentransfers 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 82898184e3Ssthen=head2 On The Road 83898184e3Ssthen 84898184e3SsthenMany of the examples which follow will concentrate on creating an interface 85898184e3Ssthenbetween Perl and the ONC+ RPC bind library functions. The rpcb_gettime() 86898184e3Ssthenfunction is used to demonstrate many features of the XS language. This 87898184e3Ssthenfunction has two parameters; the first is an input parameter and the second 88898184e3Ssthenis an output parameter. The function also returns a status value. 89898184e3Ssthen 90898184e3Ssthen bool_t rpcb_gettime(const char *host, time_t *timep); 91898184e3Ssthen 92898184e3SsthenFrom C this function will be called with the following 93898184e3Ssthenstatements. 94898184e3Ssthen 95898184e3Ssthen #include <rpc/rpc.h> 96898184e3Ssthen bool_t status; 97898184e3Ssthen time_t timep; 98898184e3Ssthen status = rpcb_gettime( "localhost", &timep ); 99898184e3Ssthen 100898184e3SsthenIf an XSUB is created to offer a direct translation between this function 101898184e3Ssthenand Perl, then this XSUB will be used from Perl with the following code. 102898184e3SsthenThe $status and $timep variables will contain the output of the function. 103898184e3Ssthen 104898184e3Ssthen use RPC; 105898184e3Ssthen $status = rpcb_gettime( "localhost", $timep ); 106898184e3Ssthen 107898184e3SsthenThe following XS file shows an XS subroutine, or XSUB, which 108898184e3Ssthendemonstrates one possible interface to the rpcb_gettime() 109898184e3Ssthenfunction. This XSUB represents a direct translation between 110898184e3SsthenC and Perl and so preserves the interface even from Perl. 111898184e3SsthenThis XSUB will be invoked from Perl with the usage shown 112898184e3Ssthenabove. Note that the first three #include statements, for 113898184e3SsthenC<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the 114898184e3Ssthenbeginning of an XS file. This approach and others will be 1156fb12b70Safresh1expanded later in this document. A #define for C<PERL_NO_GET_CONTEXT> 1166fb12b70Safresh1should be present to fetch the interpreter context more efficiently, 1176fb12b70Safresh1see L<perlguts|perlguts/How multiple interpreters and concurrency are 1186fb12b70Safresh1supported> for details. 119898184e3Ssthen 1206fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 121898184e3Ssthen #include "EXTERN.h" 122898184e3Ssthen #include "perl.h" 123898184e3Ssthen #include "XSUB.h" 124898184e3Ssthen #include <rpc/rpc.h> 125898184e3Ssthen 126898184e3Ssthen MODULE = RPC PACKAGE = RPC 127898184e3Ssthen 128898184e3Ssthen bool_t 129898184e3Ssthen rpcb_gettime(host,timep) 130898184e3Ssthen char *host 131898184e3Ssthen time_t &timep 132898184e3Ssthen OUTPUT: 133898184e3Ssthen timep 134898184e3Ssthen 135898184e3SsthenAny extension to Perl, including those containing XSUBs, 136898184e3Ssthenshould have a Perl module to serve as the bootstrap which 137898184e3Ssthenpulls the extension into Perl. This module will export the 138898184e3Ssthenextension's functions and variables to the Perl program and 139898184e3Ssthenwill cause the extension's XSUBs to be linked into Perl. 140898184e3SsthenThe following module will be used for most of the examples 141898184e3Ssthenin this document and should be used from Perl with the C<use> 142898184e3Ssthencommand as shown earlier. Perl modules are explained in 143898184e3Ssthenmore detail later in this document. 144898184e3Ssthen 145898184e3Ssthen package RPC; 146898184e3Ssthen 147898184e3Ssthen require Exporter; 148898184e3Ssthen require DynaLoader; 149898184e3Ssthen @ISA = qw(Exporter DynaLoader); 150898184e3Ssthen @EXPORT = qw( rpcb_gettime ); 151898184e3Ssthen 152898184e3Ssthen bootstrap RPC; 153898184e3Ssthen 1; 154898184e3Ssthen 155898184e3SsthenThroughout this document a variety of interfaces to the rpcb_gettime() 156898184e3SsthenXSUB will be explored. The XSUBs will take their parameters in different 157898184e3Ssthenorders or will take different numbers of parameters. In each case the 158898184e3SsthenXSUB is an abstraction between Perl and the real C rpcb_gettime() 159898184e3Ssthenfunction, and the XSUB must always ensure that the real rpcb_gettime() 160898184e3Ssthenfunction is called with the correct parameters. This abstraction will 161898184e3Ssthenallow the programmer to create a more Perl-like interface to the C 162898184e3Ssthenfunction. 163898184e3Ssthen 164898184e3Ssthen=head2 The Anatomy of an XSUB 165898184e3Ssthen 166898184e3SsthenThe simplest XSUBs consist of 3 parts: a description of the return 167898184e3Ssthenvalue, the name of the XSUB routine and the names of its arguments, 168898184e3Ssthenand a description of types or formats of the arguments. 169898184e3Ssthen 170898184e3SsthenThe following XSUB allows a Perl program to access a C library function 171898184e3Ssthencalled sin(). The XSUB will imitate the C function which takes a single 172898184e3Ssthenargument and returns a single value. 173898184e3Ssthen 174898184e3Ssthen double 175898184e3Ssthen sin(x) 176898184e3Ssthen double x 177898184e3Ssthen 178898184e3SsthenOptionally, one can merge the description of types and the list of 179898184e3Ssthenargument names, rewriting this as 180898184e3Ssthen 181898184e3Ssthen double 182898184e3Ssthen sin(double x) 183898184e3Ssthen 184898184e3SsthenThis makes this XSUB look similar to an ANSI C declaration. An optional 185898184e3Ssthensemicolon is allowed after the argument list, as in 186898184e3Ssthen 187898184e3Ssthen double 188898184e3Ssthen sin(double x); 189898184e3Ssthen 190898184e3SsthenParameters with C pointer types can have different semantic: C functions 191898184e3Ssthenwith similar declarations 192898184e3Ssthen 193898184e3Ssthen bool string_looks_as_a_number(char *s); 194898184e3Ssthen bool make_char_uppercase(char *c); 195898184e3Ssthen 196898184e3Ssthenare used in absolutely incompatible manner. Parameters to these functions 197898184e3Ssthencould be described B<xsubpp> like this: 198898184e3Ssthen 199898184e3Ssthen char * s 200898184e3Ssthen char &c 201898184e3Ssthen 202898184e3SsthenBoth these XS declarations correspond to the C<char*> C type, but they have 203898184e3Ssthendifferent semantics, see L<"The & Unary Operator">. 204898184e3Ssthen 205898184e3SsthenIt is convenient to think that the indirection operator 206898184e3SsthenC<*> should be considered as a part of the type and the address operator C<&> 207898184e3Ssthenshould be considered part of the variable. See L<perlxstypemap> 208898184e3Ssthenfor more info about handling qualifiers and unary operators in C types. 209898184e3Ssthen 210898184e3SsthenThe function name and the return type must be placed on 211898184e3Ssthenseparate lines and should be flush left-adjusted. 212898184e3Ssthen 213898184e3Ssthen INCORRECT CORRECT 214898184e3Ssthen 215898184e3Ssthen double sin(x) double 216898184e3Ssthen double x sin(x) 217898184e3Ssthen double x 218898184e3Ssthen 219898184e3SsthenThe rest of the function description may be indented or left-adjusted. The 220898184e3Ssthenfollowing example shows a function with its body left-adjusted. Most 221898184e3Ssthenexamples in this document will indent the body for better readability. 222898184e3Ssthen 223898184e3Ssthen CORRECT 224898184e3Ssthen 225898184e3Ssthen double 226898184e3Ssthen sin(x) 227898184e3Ssthen double x 228898184e3Ssthen 229898184e3SsthenMore complicated XSUBs may contain many other sections. Each section of 230898184e3Ssthenan XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:. 231898184e3SsthenHowever, the first two lines of an XSUB always contain the same data: 232898184e3Ssthendescriptions of the return type and the names of the function and its 233898184e3Ssthenparameters. Whatever immediately follows these is considered to be 234898184e3Ssthenan INPUT: section unless explicitly marked with another keyword. 235898184e3Ssthen(See L<The INPUT: Keyword>.) 236898184e3Ssthen 237898184e3SsthenAn XSUB section continues until another section-start keyword is found. 238898184e3Ssthen 239898184e3Ssthen=head2 The Argument Stack 240898184e3Ssthen 241898184e3SsthenThe Perl argument stack is used to store the values which are 242898184e3Ssthensent as parameters to the XSUB and to store the XSUB's 243898184e3Ssthenreturn value(s). In reality all Perl functions (including non-XSUB 244898184e3Ssthenones) keep their values on this stack all the same time, each limited 245898184e3Ssthento its own range of positions on the stack. In this document the 246898184e3Ssthenfirst position on that stack which belongs to the active 247898184e3Ssthenfunction will be referred to as position 0 for that function. 248898184e3Ssthen 249898184e3SsthenXSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> 250898184e3Ssthenrefers to a position in this XSUB's part of the stack. Position 0 for that 251898184e3Ssthenfunction would be known to the XSUB as ST(0). The XSUB's incoming 252898184e3Ssthenparameters and outgoing return values always begin at ST(0). For many 253898184e3Ssthensimple cases the B<xsubpp> compiler will generate the code necessary to 254898184e3Ssthenhandle the argument stack by embedding code fragments found in the 255898184e3Ssthentypemaps. In more complex cases the programmer must supply the code. 256898184e3Ssthen 257898184e3Ssthen=head2 The RETVAL Variable 258898184e3Ssthen 259898184e3SsthenThe RETVAL variable is a special C variable that is declared automatically 260898184e3Ssthenfor you. The C type of RETVAL matches the return type of the C library 261898184e3Ssthenfunction. The B<xsubpp> compiler will declare this variable in each XSUB 262898184e3Ssthenwith non-C<void> return type. By default the generated C function 263898184e3Ssthenwill use RETVAL to hold the return value of the C library function being 264898184e3Ssthencalled. In simple cases the value of RETVAL will be placed in ST(0) of 265898184e3Ssthenthe argument stack where it can be received by Perl as the return value 266898184e3Ssthenof the XSUB. 267898184e3Ssthen 268898184e3SsthenIf the XSUB has a return type of C<void> then the compiler will 269898184e3Ssthennot declare a RETVAL variable for that function. When using 270898184e3Ssthena PPCODE: section no manipulation of the RETVAL variable is required, the 271898184e3Ssthensection may use direct stack manipulation to place output values on the stack. 272898184e3Ssthen 273898184e3SsthenIf PPCODE: directive is not used, C<void> return value should be used 274898184e3Ssthenonly for subroutines which do not return a value, I<even if> CODE: 275898184e3Ssthendirective is used which sets ST(0) explicitly. 276898184e3Ssthen 277898184e3SsthenOlder versions of this document recommended to use C<void> return 278898184e3Ssthenvalue in such cases. It was discovered that this could lead to 279898184e3Ssthensegfaults in cases when XSUB was I<truly> C<void>. This practice is 280898184e3Ssthennow deprecated, and may be not supported at some future version. Use 281898184e3Ssthenthe return value C<SV *> in such cases. (Currently C<xsubpp> contains 282898184e3Ssthensome heuristic code which tries to disambiguate between "truly-void" 283898184e3Ssthenand "old-practice-declared-as-void" functions. Hence your code is at 284898184e3Ssthenmercy of this heuristics unless you use C<SV *> as return value.) 285898184e3Ssthen 286898184e3Ssthen=head2 Returning SVs, AVs and HVs through RETVAL 287898184e3Ssthen 288898184e3SsthenWhen you're using RETVAL to return an C<SV *>, there's some magic 289898184e3Ssthengoing on behind the scenes that should be mentioned. When you're 290898184e3Ssthenmanipulating the argument stack using the ST(x) macro, for example, 291898184e3Ssthenyou usually have to pay special attention to reference counts. (For 292898184e3Ssthenmore about reference counts, see L<perlguts>.) To make your life 293898184e3Sstheneasier, the typemap file automatically makes C<RETVAL> mortal when 294898184e3Ssthenyou're returning an C<SV *>. Thus, the following two XSUBs are more 295898184e3Ssthenor less equivalent: 296898184e3Ssthen 297898184e3Ssthen void 298898184e3Ssthen alpha() 299898184e3Ssthen PPCODE: 300898184e3Ssthen ST(0) = newSVpv("Hello World",0); 301898184e3Ssthen sv_2mortal(ST(0)); 302898184e3Ssthen XSRETURN(1); 303898184e3Ssthen 304898184e3Ssthen SV * 305898184e3Ssthen beta() 306898184e3Ssthen CODE: 307898184e3Ssthen RETVAL = newSVpv("Hello World",0); 308898184e3Ssthen OUTPUT: 309898184e3Ssthen RETVAL 310898184e3Ssthen 311898184e3SsthenThis is quite useful as it usually improves readability. While 312898184e3Ssthenthis works fine for an C<SV *>, it's unfortunately not as easy 313898184e3Ssthento have C<AV *> or C<HV *> as a return value. You I<should> be 314898184e3Ssthenable to write: 315898184e3Ssthen 316898184e3Ssthen AV * 317898184e3Ssthen array() 318898184e3Ssthen CODE: 319898184e3Ssthen RETVAL = newAV(); 320898184e3Ssthen /* do something with RETVAL */ 321898184e3Ssthen OUTPUT: 322898184e3Ssthen RETVAL 323898184e3Ssthen 324898184e3SsthenBut due to an unfixable bug (fixing it would break lots of existing 325898184e3SsthenCPAN modules) in the typemap file, the reference count of the C<AV *> 326898184e3Ssthenis not properly decremented. Thus, the above XSUB would leak memory 327898184e3Ssthenwhenever it is being called. The same problem exists for C<HV *>, 328898184e3SsthenC<CV *>, and C<SVREF> (which indicates a scalar reference, not 329898184e3Ssthena general C<SV *>). 330898184e3SsthenIn XS code on perls starting with perl 5.16, you can override the 331898184e3Ssthentypemaps for any of these types with a version that has proper 332898184e3Ssthenhandling of refcounts. In your C<TYPEMAP> section, do 333898184e3Ssthen 334898184e3Ssthen AV* T_AVREF_REFCOUNT_FIXED 335898184e3Ssthen 336898184e3Ssthento get the repaired variant. For backward compatibility with older 337898184e3Ssthenversions of perl, you can instead decrement the reference count 338898184e3Ssthenmanually when you're returning one of the aforementioned 339898184e3Ssthentypes using C<sv_2mortal>: 340898184e3Ssthen 341898184e3Ssthen AV * 342898184e3Ssthen array() 343898184e3Ssthen CODE: 344898184e3Ssthen RETVAL = newAV(); 345898184e3Ssthen sv_2mortal((SV*)RETVAL); 346898184e3Ssthen /* do something with RETVAL */ 347898184e3Ssthen OUTPUT: 348898184e3Ssthen RETVAL 349898184e3Ssthen 350898184e3SsthenRemember that you don't have to do this for an C<SV *>. The reference 351898184e3Ssthendocumentation for all core typemaps can be found in L<perlxstypemap>. 352898184e3Ssthen 353898184e3Ssthen=head2 The MODULE Keyword 354898184e3Ssthen 355898184e3SsthenThe MODULE keyword is used to start the XS code and to specify the package 356898184e3Ssthenof the functions which are being defined. All text preceding the first 357898184e3SsthenMODULE keyword is considered C code and is passed through to the output with 358898184e3SsthenPOD stripped, but otherwise untouched. Every XS module will have a 359898184e3Ssthenbootstrap function which is used to hook the XSUBs into Perl. The package 360898184e3Ssthenname of this bootstrap function will match the value of the last MODULE 361898184e3Ssthenstatement in the XS source files. The value of MODULE should always remain 362898184e3Ssthenconstant within the same XS file, though this is not required. 363898184e3Ssthen 364898184e3SsthenThe following example will start the XS code and will place 365898184e3Ssthenall functions in a package named RPC. 366898184e3Ssthen 367898184e3Ssthen MODULE = RPC 368898184e3Ssthen 369898184e3Ssthen=head2 The PACKAGE Keyword 370898184e3Ssthen 371898184e3SsthenWhen functions within an XS source file must be separated into packages 372898184e3Ssthenthe PACKAGE keyword should be used. This keyword is used with the MODULE 373898184e3Ssthenkeyword and must follow immediately after it when used. 374898184e3Ssthen 375898184e3Ssthen MODULE = RPC PACKAGE = RPC 376898184e3Ssthen 377898184e3Ssthen [ XS code in package RPC ] 378898184e3Ssthen 379898184e3Ssthen MODULE = RPC PACKAGE = RPCB 380898184e3Ssthen 381898184e3Ssthen [ XS code in package RPCB ] 382898184e3Ssthen 383898184e3Ssthen MODULE = RPC PACKAGE = RPC 384898184e3Ssthen 385898184e3Ssthen [ XS code in package RPC ] 386898184e3Ssthen 387898184e3SsthenThe same package name can be used more than once, allowing for 388898184e3Ssthennon-contiguous code. This is useful if you have a stronger ordering 389898184e3Ssthenprinciple than package names. 390898184e3Ssthen 391898184e3SsthenAlthough this keyword is optional and in some cases provides redundant 392898184e3Sstheninformation it should always be used. This keyword will ensure that the 393898184e3SsthenXSUBs appear in the desired package. 394898184e3Ssthen 395898184e3Ssthen=head2 The PREFIX Keyword 396898184e3Ssthen 397898184e3SsthenThe PREFIX keyword designates prefixes which should be 398898184e3Ssthenremoved from the Perl function names. If the C function is 399898184e3SsthenC<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will 400898184e3Ssthensee this function as C<gettime()>. 401898184e3Ssthen 402898184e3SsthenThis keyword should follow the PACKAGE keyword when used. 403898184e3SsthenIf PACKAGE is not used then PREFIX should follow the MODULE 404898184e3Ssthenkeyword. 405898184e3Ssthen 406898184e3Ssthen MODULE = RPC PREFIX = rpc_ 407898184e3Ssthen 408898184e3Ssthen MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_ 409898184e3Ssthen 410898184e3Ssthen=head2 The OUTPUT: Keyword 411898184e3Ssthen 412898184e3SsthenThe OUTPUT: keyword indicates that certain function parameters should be 413898184e3Ssthenupdated (new values made visible to Perl) when the XSUB terminates or that 414898184e3Ssthencertain values should be returned to the calling Perl function. For 415898184e3Ssthensimple functions which have no CODE: or PPCODE: section, 416898184e3Ssthensuch as the sin() function above, the RETVAL variable is 417898184e3Ssthenautomatically designated as an output value. For more complex functions 418898184e3Ssthenthe B<xsubpp> compiler will need help to determine which variables are output 419898184e3Ssthenvariables. 420898184e3Ssthen 421898184e3SsthenThis keyword will normally be used to complement the CODE: keyword. 422898184e3SsthenThe RETVAL variable is not recognized as an output variable when the 423898184e3SsthenCODE: keyword is present. The OUTPUT: keyword is used in this 424898184e3Ssthensituation to tell the compiler that RETVAL really is an output 425898184e3Ssthenvariable. 426898184e3Ssthen 427898184e3SsthenThe OUTPUT: keyword can also be used to indicate that function parameters 428898184e3Ssthenare output variables. This may be necessary when a parameter has been 429898184e3Ssthenmodified within the function and the programmer would like the update to 430898184e3Ssthenbe seen by Perl. 431898184e3Ssthen 432898184e3Ssthen bool_t 433898184e3Ssthen rpcb_gettime(host,timep) 434898184e3Ssthen char *host 435898184e3Ssthen time_t &timep 436898184e3Ssthen OUTPUT: 437898184e3Ssthen timep 438898184e3Ssthen 439898184e3SsthenThe OUTPUT: keyword will also allow an output parameter to 440898184e3Ssthenbe mapped to a matching piece of code rather than to a 441898184e3Ssthentypemap. 442898184e3Ssthen 443898184e3Ssthen bool_t 444898184e3Ssthen rpcb_gettime(host,timep) 445898184e3Ssthen char *host 446898184e3Ssthen time_t &timep 447898184e3Ssthen OUTPUT: 448898184e3Ssthen timep sv_setnv(ST(1), (double)timep); 449898184e3Ssthen 450898184e3SsthenB<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the 451898184e3SsthenOUTPUT section of the XSUB, except RETVAL. This is the usually desired 452898184e3Ssthenbehavior, as it takes care of properly invoking 'set' magic on output 453898184e3Ssthenparameters (needed for hash or array element parameters that must be 454898184e3Ssthencreated if they didn't exist). If for some reason, this behavior is 455898184e3Ssthennot desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line 456898184e3Ssthento disable it for the remainder of the parameters in the OUTPUT section. 457898184e3SsthenLikewise, C<SETMAGIC: ENABLE> can be used to reenable it for the 458898184e3Ssthenremainder of the OUTPUT section. See L<perlguts> for more details 459898184e3Ssthenabout 'set' magic. 460898184e3Ssthen 461898184e3Ssthen=head2 The NO_OUTPUT Keyword 462898184e3Ssthen 463898184e3SsthenThe NO_OUTPUT can be placed as the first token of the XSUB. This keyword 464898184e3Ssthenindicates that while the C subroutine we provide an interface to has 465898184e3Ssthena non-C<void> return type, the return value of this C subroutine should not 466898184e3Ssthenbe returned from the generated Perl subroutine. 467898184e3Ssthen 468898184e3SsthenWith this keyword present L<The RETVAL Variable> is created, and in the 469898184e3Ssthengenerated call to the subroutine this variable is assigned to, but the value 470898184e3Ssthenof this variable is not going to be used in the auto-generated code. 471898184e3Ssthen 472898184e3SsthenThis keyword makes sense only if C<RETVAL> is going to be accessed by the 473898184e3Ssthenuser-supplied code. It is especially useful to make a function interface 474898184e3Ssthenmore Perl-like, especially when the C return value is just an error condition 475898184e3Ssthenindicator. For example, 476898184e3Ssthen 477898184e3Ssthen NO_OUTPUT int 478898184e3Ssthen delete_file(char *name) 479898184e3Ssthen POSTCALL: 480898184e3Ssthen if (RETVAL != 0) 481898184e3Ssthen croak("Error %d while deleting file '%s'", RETVAL, name); 482898184e3Ssthen 483898184e3SsthenHere the generated XS function returns nothing on success, and will die() 484898184e3Ssthenwith a meaningful error message on error. 485898184e3Ssthen 486898184e3Ssthen=head2 The CODE: Keyword 487898184e3Ssthen 488898184e3SsthenThis keyword is used in more complicated XSUBs which require 489898184e3Ssthenspecial handling for the C function. The RETVAL variable is 490898184e3Ssthenstill declared, but it will not be returned unless it is specified 491898184e3Ssthenin the OUTPUT: section. 492898184e3Ssthen 493898184e3SsthenThe following XSUB is for a C function which requires special handling of 494898184e3Ssthenits parameters. The Perl usage is given first. 495898184e3Ssthen 496898184e3Ssthen $status = rpcb_gettime( "localhost", $timep ); 497898184e3Ssthen 498898184e3SsthenThe XSUB follows. 499898184e3Ssthen 500898184e3Ssthen bool_t 501898184e3Ssthen rpcb_gettime(host,timep) 502898184e3Ssthen char *host 503898184e3Ssthen time_t timep 504898184e3Ssthen CODE: 505898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 506898184e3Ssthen OUTPUT: 507898184e3Ssthen timep 508898184e3Ssthen RETVAL 509898184e3Ssthen 510898184e3Ssthen=head2 The INIT: Keyword 511898184e3Ssthen 512898184e3SsthenThe INIT: keyword allows initialization to be inserted into the XSUB before 513898184e3Ssthenthe compiler generates the call to the C function. Unlike the CODE: keyword 514898184e3Ssthenabove, this keyword does not affect the way the compiler handles RETVAL. 515898184e3Ssthen 516898184e3Ssthen bool_t 517898184e3Ssthen rpcb_gettime(host,timep) 518898184e3Ssthen char *host 519898184e3Ssthen time_t &timep 520898184e3Ssthen INIT: 521898184e3Ssthen printf("# Host is %s\n", host ); 522898184e3Ssthen OUTPUT: 523898184e3Ssthen timep 524898184e3Ssthen 525898184e3SsthenAnother use for the INIT: section is to check for preconditions before 526898184e3Ssthenmaking a call to the C function: 527898184e3Ssthen 528898184e3Ssthen long long 529898184e3Ssthen lldiv(a,b) 530898184e3Ssthen long long a 531898184e3Ssthen long long b 532898184e3Ssthen INIT: 533898184e3Ssthen if (a == 0 && b == 0) 534898184e3Ssthen XSRETURN_UNDEF; 535898184e3Ssthen if (b == 0) 536898184e3Ssthen croak("lldiv: cannot divide by 0"); 537898184e3Ssthen 538898184e3Ssthen=head2 The NO_INIT Keyword 539898184e3Ssthen 540898184e3SsthenThe NO_INIT keyword is used to indicate that a function 541898184e3Ssthenparameter is being used only as an output value. The B<xsubpp> 542898184e3Ssthencompiler will normally generate code to read the values of 543898184e3Ssthenall function parameters from the argument stack and assign 544898184e3Ssthenthem to C variables upon entry to the function. NO_INIT 545898184e3Ssthenwill tell the compiler that some parameters will be used for 546898184e3Ssthenoutput rather than for input and that they will be handled 547898184e3Ssthenbefore the function terminates. 548898184e3Ssthen 549898184e3SsthenThe following example shows a variation of the rpcb_gettime() function. 550898184e3SsthenThis function uses the timep variable only as an output variable and does 551898184e3Ssthennot care about its initial contents. 552898184e3Ssthen 553898184e3Ssthen bool_t 554898184e3Ssthen rpcb_gettime(host,timep) 555898184e3Ssthen char *host 556898184e3Ssthen time_t &timep = NO_INIT 557898184e3Ssthen OUTPUT: 558898184e3Ssthen timep 559898184e3Ssthen 560898184e3Ssthen=head2 The TYPEMAP: Keyword 561898184e3Ssthen 562898184e3SsthenStarting with Perl 5.16, you can embed typemaps into your XS code 563898184e3Sstheninstead of or in addition to typemaps in a separate file. Multiple 564898184e3Ssthensuch embedded typemaps will be processed in order of appearance in 5656fb12b70Safresh1the XS code and like local typemap files take precedence over the 566898184e3Ssthendefault typemap, the embedded typemaps may overwrite previous 567898184e3Ssthendefinitions of TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for 568898184e3Ssthenembedded typemaps is 569898184e3Ssthen 570898184e3Ssthen TYPEMAP: <<HERE 571898184e3Ssthen ... your typemap code here ... 572898184e3Ssthen HERE 573898184e3Ssthen 574898184e3Ssthenwhere the C<TYPEMAP> keyword must appear in the first column of a 575898184e3Ssthennew line. 576898184e3Ssthen 577898184e3SsthenRefer to L<perlxstypemap> for details on writing typemaps. 578898184e3Ssthen 579898184e3Ssthen=head2 Initializing Function Parameters 580898184e3Ssthen 581898184e3SsthenC function parameters are normally initialized with their values from 582898184e3Ssthenthe argument stack (which in turn contains the parameters that were 583898184e3Ssthenpassed to the XSUB from Perl). The typemaps contain the 584898184e3Ssthencode segments which are used to translate the Perl values to 585898184e3Ssthenthe C parameters. The programmer, however, is allowed to 586898184e3Ssthenoverride the typemaps and supply alternate (or additional) 587898184e3Sstheninitialization code. Initialization code starts with the first 588898184e3SsthenC<=>, C<;> or C<+> on a line in the INPUT: section. The only 589898184e3Ssthenexception happens if this C<;> terminates the line, then this C<;> 590898184e3Ssthenis quietly ignored. 591898184e3Ssthen 592898184e3SsthenThe following code demonstrates how to supply initialization code for 593898184e3Ssthenfunction parameters. The initialization code is eval'ed within double 594898184e3Ssthenquotes by the compiler before it is added to the output so anything 595898184e3Ssthenwhich should be interpreted literally [mainly C<$>, C<@>, or C<\\>] 596898184e3Ssthenmust be protected with backslashes. The variables C<$var>, C<$arg>, 597898184e3Ssthenand C<$type> can be used as in typemaps. 598898184e3Ssthen 599898184e3Ssthen bool_t 600898184e3Ssthen rpcb_gettime(host,timep) 601898184e3Ssthen char *host = (char *)SvPV_nolen($arg); 602898184e3Ssthen time_t &timep = 0; 603898184e3Ssthen OUTPUT: 604898184e3Ssthen timep 605898184e3Ssthen 606898184e3SsthenThis should not be used to supply default values for parameters. One 607898184e3Ssthenwould normally use this when a function parameter must be processed by 608898184e3Ssthenanother library function before it can be used. Default parameters are 609898184e3Ssthencovered in the next section. 610898184e3Ssthen 611898184e3SsthenIf the initialization begins with C<=>, then it is output in 612898184e3Ssthenthe declaration for the input variable, replacing the initialization 613898184e3Ssthensupplied by the typemap. If the initialization 614898184e3Ssthenbegins with C<;> or C<+>, then it is performed after 615898184e3Ssthenall of the input variables have been declared. In the C<;> 616898184e3Ssthencase the initialization normally supplied by the typemap is not performed. 617898184e3SsthenFor the C<+> case, the declaration for the variable will include the 618898184e3Sstheninitialization from the typemap. A global 619898184e3Ssthenvariable, C<%v>, is available for the truly rare case where 620898184e3Sstheninformation from one initialization is needed in another 621898184e3Sstheninitialization. 622898184e3Ssthen 623898184e3SsthenHere's a truly obscure example: 624898184e3Ssthen 625898184e3Ssthen bool_t 626898184e3Ssthen rpcb_gettime(host,timep) 627898184e3Ssthen time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */ 628898184e3Ssthen char *host + SvOK($v{timep}) ? SvPV_nolen($arg) : NULL; 629898184e3Ssthen OUTPUT: 630898184e3Ssthen timep 631898184e3Ssthen 632898184e3SsthenThe construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above 633898184e3Ssthenexample has a two-fold purpose: first, when this line is processed by 634898184e3SsthenB<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second, 635898184e3Ssthenthe text of the evaluated snippet is output into the generated C file 636898184e3Ssthen(inside a C comment)! During the processing of C<char *host> line, 637898184e3SsthenC<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to 638898184e3SsthenC<ST(1)>. 639898184e3Ssthen 640898184e3Ssthen=head2 Default Parameter Values 641898184e3Ssthen 642898184e3SsthenDefault values for XSUB arguments can be specified by placing an 643898184e3Ssthenassignment statement in the parameter list. The default value may 644898184e3Ssthenbe a number, a string or the special string C<NO_INIT>. Defaults should 645898184e3Ssthenalways be used on the right-most parameters only. 646898184e3Ssthen 647898184e3SsthenTo allow the XSUB for rpcb_gettime() to have a default host 648898184e3Ssthenvalue the parameters to the XSUB could be rearranged. The 649898184e3SsthenXSUB will then call the real rpcb_gettime() function with 650898184e3Ssthenthe parameters in the correct order. This XSUB can be called 651898184e3Ssthenfrom Perl with either of the following statements: 652898184e3Ssthen 653898184e3Ssthen $status = rpcb_gettime( $timep, $host ); 654898184e3Ssthen 655898184e3Ssthen $status = rpcb_gettime( $timep ); 656898184e3Ssthen 657898184e3SsthenThe XSUB will look like the code which follows. A CODE: 658898184e3Ssthenblock is used to call the real rpcb_gettime() function with 659898184e3Ssthenthe parameters in the correct order for that function. 660898184e3Ssthen 661898184e3Ssthen bool_t 662898184e3Ssthen rpcb_gettime(timep,host="localhost") 663898184e3Ssthen char *host 664898184e3Ssthen time_t timep = NO_INIT 665898184e3Ssthen CODE: 666898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 667898184e3Ssthen OUTPUT: 668898184e3Ssthen timep 669898184e3Ssthen RETVAL 670898184e3Ssthen 671898184e3Ssthen=head2 The PREINIT: Keyword 672898184e3Ssthen 673898184e3SsthenThe PREINIT: keyword allows extra variables to be declared immediately 674898184e3Ssthenbefore or after the declarations of the parameters from the INPUT: section 675898184e3Ssthenare emitted. 676898184e3Ssthen 677898184e3SsthenIf a variable is declared inside a CODE: section it will follow any typemap 678898184e3Ssthencode that is emitted for the input parameters. This may result in the 679898184e3Ssthendeclaration ending up after C code, which is C syntax error. Similar 680898184e3Ssthenerrors may happen with an explicit C<;>-type or C<+>-type initialization of 681898184e3Ssthenparameters is used (see L<"Initializing Function Parameters">). Declaring 682898184e3Ssthenthese variables in an INIT: section will not help. 683898184e3Ssthen 684898184e3SsthenIn such cases, to force an additional variable to be declared together 685898184e3Ssthenwith declarations of other variables, place the declaration into a 686898184e3SsthenPREINIT: section. The PREINIT: keyword may be used one or more times 687898184e3Ssthenwithin an XSUB. 688898184e3Ssthen 689898184e3SsthenThe following examples are equivalent, but if the code is using complex 690898184e3Ssthentypemaps then the first example is safer. 691898184e3Ssthen 692898184e3Ssthen bool_t 693898184e3Ssthen rpcb_gettime(timep) 694898184e3Ssthen time_t timep = NO_INIT 695898184e3Ssthen PREINIT: 696898184e3Ssthen char *host = "localhost"; 697898184e3Ssthen CODE: 698898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 699898184e3Ssthen OUTPUT: 700898184e3Ssthen timep 701898184e3Ssthen RETVAL 702898184e3Ssthen 703898184e3SsthenFor this particular case an INIT: keyword would generate the 704898184e3Ssthensame C code as the PREINIT: keyword. Another correct, but error-prone example: 705898184e3Ssthen 706898184e3Ssthen bool_t 707898184e3Ssthen rpcb_gettime(timep) 708898184e3Ssthen time_t timep = NO_INIT 709898184e3Ssthen CODE: 710898184e3Ssthen char *host = "localhost"; 711898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 712898184e3Ssthen OUTPUT: 713898184e3Ssthen timep 714898184e3Ssthen RETVAL 715898184e3Ssthen 716898184e3SsthenAnother way to declare C<host> is to use a C block in the CODE: section: 717898184e3Ssthen 718898184e3Ssthen bool_t 719898184e3Ssthen rpcb_gettime(timep) 720898184e3Ssthen time_t timep = NO_INIT 721898184e3Ssthen CODE: 722898184e3Ssthen { 723898184e3Ssthen char *host = "localhost"; 724898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 725898184e3Ssthen } 726898184e3Ssthen OUTPUT: 727898184e3Ssthen timep 728898184e3Ssthen RETVAL 729898184e3Ssthen 730898184e3SsthenThe ability to put additional declarations before the typemap entries are 731898184e3Ssthenprocessed is very handy in the cases when typemap conversions manipulate 732898184e3Ssthensome global state: 733898184e3Ssthen 734898184e3Ssthen MyObject 735898184e3Ssthen mutate(o) 736898184e3Ssthen PREINIT: 737898184e3Ssthen MyState st = global_state; 738898184e3Ssthen INPUT: 739898184e3Ssthen MyObject o; 740898184e3Ssthen CLEANUP: 741898184e3Ssthen reset_to(global_state, st); 742898184e3Ssthen 743898184e3SsthenHere we suppose that conversion to C<MyObject> in the INPUT: section and from 744898184e3SsthenMyObject when processing RETVAL will modify a global variable C<global_state>. 745898184e3SsthenAfter these conversions are performed, we restore the old value of 746898184e3SsthenC<global_state> (to avoid memory leaks, for example). 747898184e3Ssthen 748898184e3SsthenThere is another way to trade clarity for compactness: INPUT sections allow 749898184e3Ssthendeclaration of C variables which do not appear in the parameter list of 750898184e3Ssthena subroutine. Thus the above code for mutate() can be rewritten as 751898184e3Ssthen 752898184e3Ssthen MyObject 753898184e3Ssthen mutate(o) 754898184e3Ssthen MyState st = global_state; 755898184e3Ssthen MyObject o; 756898184e3Ssthen CLEANUP: 757898184e3Ssthen reset_to(global_state, st); 758898184e3Ssthen 759898184e3Ssthenand the code for rpcb_gettime() can be rewritten as 760898184e3Ssthen 761898184e3Ssthen bool_t 762898184e3Ssthen rpcb_gettime(timep) 763898184e3Ssthen time_t timep = NO_INIT 764898184e3Ssthen char *host = "localhost"; 765898184e3Ssthen C_ARGS: 766898184e3Ssthen host, &timep 767898184e3Ssthen OUTPUT: 768898184e3Ssthen timep 769898184e3Ssthen RETVAL 770898184e3Ssthen 771898184e3Ssthen=head2 The SCOPE: Keyword 772898184e3Ssthen 773898184e3SsthenThe SCOPE: keyword allows scoping to be enabled for a particular XSUB. If 774898184e3Ssthenenabled, the XSUB will invoke ENTER and LEAVE automatically. 775898184e3Ssthen 776898184e3SsthenTo support potentially complex type mappings, if a typemap entry used 777898184e3Ssthenby an XSUB contains a comment like C</*scope*/> then scoping will 778898184e3Ssthenbe automatically enabled for that XSUB. 779898184e3Ssthen 780898184e3SsthenTo enable scoping: 781898184e3Ssthen 782898184e3Ssthen SCOPE: ENABLE 783898184e3Ssthen 784898184e3SsthenTo disable scoping: 785898184e3Ssthen 786898184e3Ssthen SCOPE: DISABLE 787898184e3Ssthen 788898184e3Ssthen=head2 The INPUT: Keyword 789898184e3Ssthen 790898184e3SsthenThe XSUB's parameters are usually evaluated immediately after entering the 791898184e3SsthenXSUB. The INPUT: keyword can be used to force those parameters to be 792898184e3Ssthenevaluated a little later. The INPUT: keyword can be used multiple times 793898184e3Ssthenwithin an XSUB and can be used to list one or more input variables. This 794898184e3Ssthenkeyword is used with the PREINIT: keyword. 795898184e3Ssthen 796898184e3SsthenThe following example shows how the input parameter C<timep> can be 797898184e3Ssthenevaluated late, after a PREINIT. 798898184e3Ssthen 799898184e3Ssthen bool_t 800898184e3Ssthen rpcb_gettime(host,timep) 801898184e3Ssthen char *host 802898184e3Ssthen PREINIT: 803898184e3Ssthen time_t tt; 804898184e3Ssthen INPUT: 805898184e3Ssthen time_t timep 806898184e3Ssthen CODE: 807898184e3Ssthen RETVAL = rpcb_gettime( host, &tt ); 808898184e3Ssthen timep = tt; 809898184e3Ssthen OUTPUT: 810898184e3Ssthen timep 811898184e3Ssthen RETVAL 812898184e3Ssthen 813898184e3SsthenThe next example shows each input parameter evaluated late. 814898184e3Ssthen 815898184e3Ssthen bool_t 816898184e3Ssthen rpcb_gettime(host,timep) 817898184e3Ssthen PREINIT: 818898184e3Ssthen time_t tt; 819898184e3Ssthen INPUT: 820898184e3Ssthen char *host 821898184e3Ssthen PREINIT: 822898184e3Ssthen char *h; 823898184e3Ssthen INPUT: 824898184e3Ssthen time_t timep 825898184e3Ssthen CODE: 826898184e3Ssthen h = host; 827898184e3Ssthen RETVAL = rpcb_gettime( h, &tt ); 828898184e3Ssthen timep = tt; 829898184e3Ssthen OUTPUT: 830898184e3Ssthen timep 831898184e3Ssthen RETVAL 832898184e3Ssthen 833898184e3SsthenSince INPUT sections allow declaration of C variables which do not appear 834898184e3Ssthenin the parameter list of a subroutine, this may be shortened to: 835898184e3Ssthen 836898184e3Ssthen bool_t 837898184e3Ssthen rpcb_gettime(host,timep) 838898184e3Ssthen time_t tt; 839898184e3Ssthen char *host; 840898184e3Ssthen char *h = host; 841898184e3Ssthen time_t timep; 842898184e3Ssthen CODE: 843898184e3Ssthen RETVAL = rpcb_gettime( h, &tt ); 844898184e3Ssthen timep = tt; 845898184e3Ssthen OUTPUT: 846898184e3Ssthen timep 847898184e3Ssthen RETVAL 848898184e3Ssthen 849898184e3Ssthen(We used our knowledge that input conversion for C<char *> is a "simple" one, 850898184e3Ssthenthus C<host> is initialized on the declaration line, and our assignment 851898184e3SsthenC<h = host> is not performed too early. Otherwise one would need to have the 852898184e3Ssthenassignment C<h = host> in a CODE: or INIT: section.) 853898184e3Ssthen 854898184e3Ssthen=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords 855898184e3Ssthen 856898184e3SsthenIn the list of parameters for an XSUB, one can precede parameter names 857898184e3Ssthenby the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords. 858898184e3SsthenC<IN> keyword is the default, the other keywords indicate how the Perl 859898184e3Sstheninterface should differ from the C interface. 860898184e3Ssthen 861898184e3SsthenParameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> 862898184e3Ssthenkeywords are considered to be used by the C subroutine I<via 863898184e3Ssthenpointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine 864898184e3Ssthendoes not inspect the memory pointed by this parameter, but will write 865898184e3Ssthenthrough this pointer to provide additional return values. 866898184e3Ssthen 867898184e3SsthenParameters preceded by C<OUTLIST> keyword do not appear in the usage 868898184e3Ssthensignature of the generated Perl function. 869898184e3Ssthen 870898184e3SsthenParameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as 871898184e3Ssthenparameters to the Perl function. With the exception of 872898184e3SsthenC<OUT>-parameters, these parameters are converted to the corresponding 873898184e3SsthenC type, then pointers to these data are given as arguments to the C 874898184e3Ssthenfunction. It is expected that the C function will write through these 875898184e3Ssthenpointers. 876898184e3Ssthen 877898184e3SsthenThe return list of the generated Perl function consists of the C return value 878898184e3Ssthenfrom the function (unless the XSUB is of C<void> return type or 879898184e3SsthenC<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST> 880898184e3Ssthenand C<IN_OUTLIST> parameters (in the order of appearance). On the 881898184e3Ssthenreturn from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be 882898184e3Ssthenmodified to have the values written by the C function. 883898184e3Ssthen 884898184e3SsthenFor example, an XSUB 885898184e3Ssthen 886898184e3Ssthen void 887898184e3Ssthen day_month(OUTLIST day, IN unix_time, OUTLIST month) 888898184e3Ssthen int day 889898184e3Ssthen int unix_time 890898184e3Ssthen int month 891898184e3Ssthen 892898184e3Ssthenshould be used from Perl as 893898184e3Ssthen 894898184e3Ssthen my ($day, $month) = day_month(time); 895898184e3Ssthen 896898184e3SsthenThe C signature of the corresponding function should be 897898184e3Ssthen 898898184e3Ssthen void day_month(int *day, int unix_time, int *month); 899898184e3Ssthen 900898184e3SsthenThe C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be 901898184e3Ssthenmixed with ANSI-style declarations, as in 902898184e3Ssthen 903898184e3Ssthen void 904898184e3Ssthen day_month(OUTLIST int day, int unix_time, OUTLIST int month) 905898184e3Ssthen 906898184e3Ssthen(here the optional C<IN> keyword is omitted). 907898184e3Ssthen 908898184e3SsthenThe C<IN_OUT> parameters are identical with parameters introduced with 909898184e3SsthenL<The & Unary Operator> and put into the C<OUTPUT:> section (see 910898184e3SsthenL<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar, 911898184e3Ssthenthe only difference being that the value C function writes through the 912898184e3Ssthenpointer would not modify the Perl parameter, but is put in the output 913898184e3Ssthenlist. 914898184e3Ssthen 915898184e3SsthenThe C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT> 916898184e3Ssthenparameters only by the initial value of the Perl parameter not 917898184e3Ssthenbeing read (and not being given to the C function - which gets some 918898184e3Ssthengarbage instead). For example, the same C function as above can be 919898184e3Sstheninterfaced with as 920898184e3Ssthen 921898184e3Ssthen void day_month(OUT int day, int unix_time, OUT int month); 922898184e3Ssthen 923898184e3Ssthenor 924898184e3Ssthen 925898184e3Ssthen void 926898184e3Ssthen day_month(day, unix_time, month) 927898184e3Ssthen int &day = NO_INIT 928898184e3Ssthen int unix_time 929898184e3Ssthen int &month = NO_INIT 930898184e3Ssthen OUTPUT: 931898184e3Ssthen day 932898184e3Ssthen month 933898184e3Ssthen 934898184e3SsthenHowever, the generated Perl function is called in very C-ish style: 935898184e3Ssthen 936898184e3Ssthen my ($day, $month); 937898184e3Ssthen day_month($day, time, $month); 938898184e3Ssthen 939898184e3Ssthen=head2 The C<length(NAME)> Keyword 940898184e3Ssthen 941898184e3SsthenIf one of the input arguments to the C function is the length of a string 942898184e3Ssthenargument C<NAME>, one can substitute the name of the length-argument by 943898184e3SsthenC<length(NAME)> in the XSUB declaration. This argument must be omitted when 944898184e3Ssthenthe generated Perl function is called. E.g., 945898184e3Ssthen 946898184e3Ssthen void 947898184e3Ssthen dump_chars(char *s, short l) 948898184e3Ssthen { 949898184e3Ssthen short n = 0; 950898184e3Ssthen while (n < l) { 951898184e3Ssthen printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]); 952898184e3Ssthen n++; 953898184e3Ssthen } 954898184e3Ssthen } 955898184e3Ssthen 956898184e3Ssthen MODULE = x PACKAGE = x 957898184e3Ssthen 958898184e3Ssthen void dump_chars(char *s, short length(s)) 959898184e3Ssthen 960898184e3Ssthenshould be called as C<dump_chars($string)>. 961898184e3Ssthen 962898184e3SsthenThis directive is supported with ANSI-type function declarations only. 963898184e3Ssthen 964898184e3Ssthen=head2 Variable-length Parameter Lists 965898184e3Ssthen 966898184e3SsthenXSUBs can have variable-length parameter lists by specifying an ellipsis 967898184e3SsthenC<(...)> in the parameter list. This use of the ellipsis is similar to that 968898184e3Ssthenfound in ANSI C. The programmer is able to determine the number of 969898184e3Ssthenarguments passed to the XSUB by examining the C<items> variable which the 970898184e3SsthenB<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can 971898184e3Ssthencreate an XSUB which accepts a list of parameters of unknown length. 972898184e3Ssthen 973898184e3SsthenThe I<host> parameter for the rpcb_gettime() XSUB can be 974898184e3Ssthenoptional so the ellipsis can be used to indicate that the 975898184e3SsthenXSUB will take a variable number of parameters. Perl should 976898184e3Ssthenbe able to call this XSUB with either of the following statements. 977898184e3Ssthen 978898184e3Ssthen $status = rpcb_gettime( $timep, $host ); 979898184e3Ssthen 980898184e3Ssthen $status = rpcb_gettime( $timep ); 981898184e3Ssthen 982898184e3SsthenThe XS code, with ellipsis, follows. 983898184e3Ssthen 984898184e3Ssthen bool_t 985898184e3Ssthen rpcb_gettime(timep, ...) 986898184e3Ssthen time_t timep = NO_INIT 987898184e3Ssthen PREINIT: 988898184e3Ssthen char *host = "localhost"; 989898184e3Ssthen CODE: 990898184e3Ssthen if( items > 1 ) 991898184e3Ssthen host = (char *)SvPV_nolen(ST(1)); 992898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 993898184e3Ssthen OUTPUT: 994898184e3Ssthen timep 995898184e3Ssthen RETVAL 996898184e3Ssthen 997898184e3Ssthen=head2 The C_ARGS: Keyword 998898184e3Ssthen 999898184e3SsthenThe C_ARGS: keyword allows creating of XSUBS which have different 1000898184e3Ssthencalling sequence from Perl than from C, without a need to write 1001898184e3SsthenCODE: or PPCODE: section. The contents of the C_ARGS: paragraph is 1002898184e3Ssthenput as the argument to the called C function without any change. 1003898184e3Ssthen 1004898184e3SsthenFor example, suppose that a C function is declared as 1005898184e3Ssthen 1006898184e3Ssthen symbolic nth_derivative(int n, symbolic function, int flags); 1007898184e3Ssthen 1008898184e3Ssthenand that the default flags are kept in a global C variable 1009898184e3SsthenC<default_flags>. Suppose that you want to create an interface which 1010898184e3Ssthenis called as 1011898184e3Ssthen 1012898184e3Ssthen $second_deriv = $function->nth_derivative(2); 1013898184e3Ssthen 1014898184e3SsthenTo do this, declare the XSUB as 1015898184e3Ssthen 1016898184e3Ssthen symbolic 1017898184e3Ssthen nth_derivative(function, n) 1018898184e3Ssthen symbolic function 1019898184e3Ssthen int n 1020898184e3Ssthen C_ARGS: 1021898184e3Ssthen n, function, default_flags 1022898184e3Ssthen 1023898184e3Ssthen=head2 The PPCODE: Keyword 1024898184e3Ssthen 1025898184e3SsthenThe PPCODE: keyword is an alternate form of the CODE: keyword and is used 1026898184e3Ssthento tell the B<xsubpp> compiler that the programmer is supplying the code to 1027898184e3Ssthencontrol the argument stack for the XSUBs return values. Occasionally one 1028898184e3Ssthenwill want an XSUB to return a list of values rather than a single value. 1029898184e3SsthenIn these cases one must use PPCODE: and then explicitly push the list of 1030898184e3Ssthenvalues on the stack. The PPCODE: and CODE: keywords should not be used 1031898184e3Ssthentogether within the same XSUB. 1032898184e3Ssthen 1033898184e3SsthenThe actual difference between PPCODE: and CODE: sections is in the 1034898184e3Sstheninitialization of C<SP> macro (which stands for the I<current> Perl 1035898184e3Ssthenstack pointer), and in the handling of data on the stack when returning 1036898184e3Ssthenfrom an XSUB. In CODE: sections SP preserves the value which was on 1037898184e3Ssthenentry to the XSUB: SP is on the function pointer (which follows the 1038898184e3Ssthenlast parameter). In PPCODE: sections SP is moved backward to the 1039898184e3Ssthenbeginning of the parameter list, which allows C<PUSH*()> macros 1040898184e3Ssthento place output values in the place Perl expects them to be when 1041898184e3Ssthenthe XSUB returns back to Perl. 1042898184e3Ssthen 1043898184e3SsthenThe generated trailer for a CODE: section ensures that the number of return 1044898184e3Ssthenvalues Perl will see is either 0 or 1 (depending on the C<void>ness of the 1045898184e3Ssthenreturn value of the C function, and heuristics mentioned in 1046898184e3SsthenL<"The RETVAL Variable">). The trailer generated for a PPCODE: section 1047898184e3Ssthenis based on the number of return values and on the number of times 1048898184e3SsthenC<SP> was updated by C<[X]PUSH*()> macros. 1049898184e3Ssthen 1050898184e3SsthenNote that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally 1051898184e3Ssthenwell in CODE: sections and PPCODE: sections. 1052898184e3Ssthen 1053898184e3SsthenThe following XSUB will call the C rpcb_gettime() function 1054898184e3Ssthenand will return its two output values, timep and status, to 1055898184e3SsthenPerl as a single list. 1056898184e3Ssthen 1057898184e3Ssthen void 1058898184e3Ssthen rpcb_gettime(host) 1059898184e3Ssthen char *host 1060898184e3Ssthen PREINIT: 1061898184e3Ssthen time_t timep; 1062898184e3Ssthen bool_t status; 1063898184e3Ssthen PPCODE: 1064898184e3Ssthen status = rpcb_gettime( host, &timep ); 1065898184e3Ssthen EXTEND(SP, 2); 1066898184e3Ssthen PUSHs(sv_2mortal(newSViv(status))); 1067898184e3Ssthen PUSHs(sv_2mortal(newSViv(timep))); 1068898184e3Ssthen 1069898184e3SsthenNotice that the programmer must supply the C code necessary 1070898184e3Ssthento have the real rpcb_gettime() function called and to have 1071898184e3Ssthenthe return values properly placed on the argument stack. 1072898184e3Ssthen 1073898184e3SsthenThe C<void> return type for this function tells the B<xsubpp> compiler that 1074898184e3Ssthenthe RETVAL variable is not needed or used and that it should not be created. 1075898184e3SsthenIn most scenarios the void return type should be used with the PPCODE: 1076898184e3Ssthendirective. 1077898184e3Ssthen 1078898184e3SsthenThe EXTEND() macro is used to make room on the argument 1079898184e3Ssthenstack for 2 return values. The PPCODE: directive causes the 1080898184e3SsthenB<xsubpp> compiler to create a stack pointer available as C<SP>, and it 1081898184e3Ssthenis this pointer which is being used in the EXTEND() macro. 1082898184e3SsthenThe values are then pushed onto the stack with the PUSHs() 1083898184e3Ssthenmacro. 1084898184e3Ssthen 1085898184e3SsthenNow the rpcb_gettime() function can be used from Perl with 1086898184e3Ssthenthe following statement. 1087898184e3Ssthen 1088898184e3Ssthen ($status, $timep) = rpcb_gettime("localhost"); 1089898184e3Ssthen 1090898184e3SsthenWhen handling output parameters with a PPCODE section, be sure to handle 1091898184e3Ssthen'set' magic properly. See L<perlguts> for details about 'set' magic. 1092898184e3Ssthen 1093898184e3Ssthen=head2 Returning Undef And Empty Lists 1094898184e3Ssthen 1095898184e3SsthenOccasionally the programmer will want to return simply 1096898184e3SsthenC<undef> or an empty list if a function fails rather than a 1097898184e3Ssthenseparate status value. The rpcb_gettime() function offers 1098898184e3Ssthenjust this situation. If the function succeeds we would like 1099898184e3Ssthento have it return the time and if it fails we would like to 1100898184e3Ssthenhave undef returned. In the following Perl code the value 1101898184e3Ssthenof $timep will either be undef or it will be a valid time. 1102898184e3Ssthen 1103898184e3Ssthen $timep = rpcb_gettime( "localhost" ); 1104898184e3Ssthen 1105898184e3SsthenThe following XSUB uses the C<SV *> return type as a mnemonic only, 1106898184e3Ssthenand uses a CODE: block to indicate to the compiler 1107898184e3Ssthenthat the programmer has supplied all the necessary code. The 1108898184e3Ssthensv_newmortal() call will initialize the return value to undef, making that 1109898184e3Ssthenthe default return value. 1110898184e3Ssthen 1111898184e3Ssthen SV * 1112898184e3Ssthen rpcb_gettime(host) 1113898184e3Ssthen char * host 1114898184e3Ssthen PREINIT: 1115898184e3Ssthen time_t timep; 1116898184e3Ssthen bool_t x; 1117898184e3Ssthen CODE: 1118898184e3Ssthen ST(0) = sv_newmortal(); 1119898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 1120898184e3Ssthen sv_setnv( ST(0), (double)timep); 1121898184e3Ssthen 1122898184e3SsthenThe next example demonstrates how one would place an explicit undef in the 1123898184e3Ssthenreturn value, should the need arise. 1124898184e3Ssthen 1125898184e3Ssthen SV * 1126898184e3Ssthen rpcb_gettime(host) 1127898184e3Ssthen char * host 1128898184e3Ssthen PREINIT: 1129898184e3Ssthen time_t timep; 1130898184e3Ssthen bool_t x; 1131898184e3Ssthen CODE: 1132898184e3Ssthen if( rpcb_gettime( host, &timep ) ){ 1133898184e3Ssthen ST(0) = sv_newmortal(); 1134898184e3Ssthen sv_setnv( ST(0), (double)timep); 1135898184e3Ssthen } 1136898184e3Ssthen else{ 1137898184e3Ssthen ST(0) = &PL_sv_undef; 1138898184e3Ssthen } 1139898184e3Ssthen 1140898184e3SsthenTo return an empty list one must use a PPCODE: block and 1141898184e3Ssthenthen not push return values on the stack. 1142898184e3Ssthen 1143898184e3Ssthen void 1144898184e3Ssthen rpcb_gettime(host) 1145898184e3Ssthen char *host 1146898184e3Ssthen PREINIT: 1147898184e3Ssthen time_t timep; 1148898184e3Ssthen PPCODE: 1149898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 1150898184e3Ssthen PUSHs(sv_2mortal(newSViv(timep))); 1151898184e3Ssthen else{ 1152898184e3Ssthen /* Nothing pushed on stack, so an empty 1153898184e3Ssthen * list is implicitly returned. */ 1154898184e3Ssthen } 1155898184e3Ssthen 1156898184e3SsthenSome people may be inclined to include an explicit C<return> in the above 1157898184e3SsthenXSUB, rather than letting control fall through to the end. In those 1158898184e3Ssthensituations C<XSRETURN_EMPTY> should be used, instead. This will ensure that 1159898184e3Ssthenthe XSUB stack is properly adjusted. Consult L<perlapi> for other 1160898184e3SsthenC<XSRETURN> macros. 1161898184e3Ssthen 1162898184e3SsthenSince C<XSRETURN_*> macros can be used with CODE blocks as well, one can 1163898184e3Ssthenrewrite this example as: 1164898184e3Ssthen 1165898184e3Ssthen int 1166898184e3Ssthen rpcb_gettime(host) 1167898184e3Ssthen char *host 1168898184e3Ssthen PREINIT: 1169898184e3Ssthen time_t timep; 1170898184e3Ssthen CODE: 1171898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 1172898184e3Ssthen if (RETVAL == 0) 1173898184e3Ssthen XSRETURN_UNDEF; 1174898184e3Ssthen OUTPUT: 1175898184e3Ssthen RETVAL 1176898184e3Ssthen 1177898184e3SsthenIn fact, one can put this check into a POSTCALL: section as well. Together 1178898184e3Ssthenwith PREINIT: simplifications, this leads to: 1179898184e3Ssthen 1180898184e3Ssthen int 1181898184e3Ssthen rpcb_gettime(host) 1182898184e3Ssthen char *host 1183898184e3Ssthen time_t timep; 1184898184e3Ssthen POSTCALL: 1185898184e3Ssthen if (RETVAL == 0) 1186898184e3Ssthen XSRETURN_UNDEF; 1187898184e3Ssthen 1188898184e3Ssthen=head2 The REQUIRE: Keyword 1189898184e3Ssthen 1190898184e3SsthenThe REQUIRE: keyword is used to indicate the minimum version of the 1191898184e3SsthenB<xsubpp> compiler needed to compile the XS module. An XS module which 1192898184e3Ssthencontains the following statement will compile with only B<xsubpp> version 1193898184e3Ssthen1.922 or greater: 1194898184e3Ssthen 1195898184e3Ssthen REQUIRE: 1.922 1196898184e3Ssthen 1197898184e3Ssthen=head2 The CLEANUP: Keyword 1198898184e3Ssthen 1199898184e3SsthenThis keyword can be used when an XSUB requires special cleanup procedures 1200898184e3Ssthenbefore it terminates. When the CLEANUP: keyword is used it must follow 1201*b8851fccSafresh1any CODE:, or OUTPUT: blocks which are present in the XSUB. The code 1202*b8851fccSafresh1specified for the cleanup block will be added as the last statements in 1203*b8851fccSafresh1the XSUB. 1204898184e3Ssthen 1205898184e3Ssthen=head2 The POSTCALL: Keyword 1206898184e3Ssthen 1207898184e3SsthenThis keyword can be used when an XSUB requires special procedures 1208898184e3Ssthenexecuted after the C subroutine call is performed. When the POSTCALL: 1209898184e3Ssthenkeyword is used it must precede OUTPUT: and CLEANUP: blocks which are 1210898184e3Ssthenpresent in the XSUB. 1211898184e3Ssthen 1212898184e3SsthenSee examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">. 1213898184e3Ssthen 1214898184e3SsthenThe POSTCALL: block does not make a lot of sense when the C subroutine 1215898184e3Ssthencall is supplied by user by providing either CODE: or PPCODE: section. 1216898184e3Ssthen 1217898184e3Ssthen=head2 The BOOT: Keyword 1218898184e3Ssthen 1219898184e3SsthenThe BOOT: keyword is used to add code to the extension's bootstrap 1220898184e3Ssthenfunction. The bootstrap function is generated by the B<xsubpp> compiler and 1221898184e3Ssthennormally holds the statements necessary to register any XSUBs with Perl. 1222898184e3SsthenWith the BOOT: keyword the programmer can tell the compiler to add extra 1223898184e3Ssthenstatements to the bootstrap function. 1224898184e3Ssthen 1225898184e3SsthenThis keyword may be used any time after the first MODULE keyword and should 1226898184e3Ssthenappear on a line by itself. The first blank line after the keyword will 1227898184e3Ssthenterminate the code block. 1228898184e3Ssthen 1229898184e3Ssthen BOOT: 1230898184e3Ssthen # The following message will be printed when the 1231898184e3Ssthen # bootstrap function executes. 1232898184e3Ssthen printf("Hello from the bootstrap!\n"); 1233898184e3Ssthen 1234898184e3Ssthen=head2 The VERSIONCHECK: Keyword 1235898184e3Ssthen 1236898184e3SsthenThe VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and 1237898184e3SsthenC<-noversioncheck> options. This keyword overrides the command line 1238898184e3Ssthenoptions. Version checking is enabled by default. When version checking is 1239898184e3Ssthenenabled the XS module will attempt to verify that its version matches the 1240898184e3Ssthenversion of the PM module. 1241898184e3Ssthen 1242898184e3SsthenTo enable version checking: 1243898184e3Ssthen 1244898184e3Ssthen VERSIONCHECK: ENABLE 1245898184e3Ssthen 1246898184e3SsthenTo disable version checking: 1247898184e3Ssthen 1248898184e3Ssthen VERSIONCHECK: DISABLE 1249898184e3Ssthen 1250898184e3SsthenNote that if the version of the PM module is an NV (a floating point 1251898184e3Ssthennumber), it will be stringified with a possible loss of precision 1252898184e3Ssthen(currently chopping to nine decimal places) so that it may not match 1253898184e3Ssthenthe version of the XS module anymore. Quoting the $VERSION declaration 1254898184e3Ssthento make it a string is recommended if long version numbers are used. 1255898184e3Ssthen 1256898184e3Ssthen=head2 The PROTOTYPES: Keyword 1257898184e3Ssthen 1258898184e3SsthenThe PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and 1259898184e3SsthenC<-noprototypes> options. This keyword overrides the command line options. 1260*b8851fccSafresh1Prototypes are disabled by default. When prototypes are enabled, XSUBs will 1261898184e3Ssthenbe given Perl prototypes. This keyword may be used multiple times in an XS 1262898184e3Ssthenmodule to enable and disable prototypes for different parts of the module. 1263*b8851fccSafresh1Note that B<xsubpp> will nag you if you don't explicitly enable or disable 1264*b8851fccSafresh1prototypes, with: 1265*b8851fccSafresh1 1266*b8851fccSafresh1 Please specify prototyping behavior for Foo.xs (see perlxs manual) 1267898184e3Ssthen 1268898184e3SsthenTo enable prototypes: 1269898184e3Ssthen 1270898184e3Ssthen PROTOTYPES: ENABLE 1271898184e3Ssthen 1272898184e3SsthenTo disable prototypes: 1273898184e3Ssthen 1274898184e3Ssthen PROTOTYPES: DISABLE 1275898184e3Ssthen 1276898184e3Ssthen=head2 The PROTOTYPE: Keyword 1277898184e3Ssthen 1278898184e3SsthenThis keyword is similar to the PROTOTYPES: keyword above but can be used to 1279898184e3Ssthenforce B<xsubpp> to use a specific prototype for the XSUB. This keyword 1280898184e3Ssthenoverrides all other prototype options and keywords but affects only the 1281898184e3Ssthencurrent XSUB. Consult L<perlsub/Prototypes> for information about Perl 1282898184e3Ssthenprototypes. 1283898184e3Ssthen 1284898184e3Ssthen bool_t 1285898184e3Ssthen rpcb_gettime(timep, ...) 1286898184e3Ssthen time_t timep = NO_INIT 1287898184e3Ssthen PROTOTYPE: $;$ 1288898184e3Ssthen PREINIT: 1289898184e3Ssthen char *host = "localhost"; 1290898184e3Ssthen CODE: 1291898184e3Ssthen if( items > 1 ) 1292898184e3Ssthen host = (char *)SvPV_nolen(ST(1)); 1293898184e3Ssthen RETVAL = rpcb_gettime( host, &timep ); 1294898184e3Ssthen OUTPUT: 1295898184e3Ssthen timep 1296898184e3Ssthen RETVAL 1297898184e3Ssthen 1298898184e3SsthenIf the prototypes are enabled, you can disable it locally for a given 1299898184e3SsthenXSUB as in the following example: 1300898184e3Ssthen 1301898184e3Ssthen void 1302898184e3Ssthen rpcb_gettime_noproto() 1303898184e3Ssthen PROTOTYPE: DISABLE 1304898184e3Ssthen ... 1305898184e3Ssthen 1306898184e3Ssthen=head2 The ALIAS: Keyword 1307898184e3Ssthen 1308898184e3SsthenThe ALIAS: keyword allows an XSUB to have two or more unique Perl names 1309898184e3Ssthenand to know which of those names was used when it was invoked. The Perl 1310898184e3Ssthennames may be fully-qualified with package names. Each alias is given an 1311898184e3Ssthenindex. The compiler will setup a variable called C<ix> which contain the 1312898184e3Ssthenindex of the alias which was used. When the XSUB is called with its 1313898184e3Ssthendeclared name C<ix> will be 0. 1314898184e3Ssthen 1315898184e3SsthenThe following example will create aliases C<FOO::gettime()> and 1316898184e3SsthenC<BAR::getit()> for this function. 1317898184e3Ssthen 1318898184e3Ssthen bool_t 1319898184e3Ssthen rpcb_gettime(host,timep) 1320898184e3Ssthen char *host 1321898184e3Ssthen time_t &timep 1322898184e3Ssthen ALIAS: 1323898184e3Ssthen FOO::gettime = 1 1324898184e3Ssthen BAR::getit = 2 1325898184e3Ssthen INIT: 1326898184e3Ssthen printf("# ix = %d\n", ix ); 1327898184e3Ssthen OUTPUT: 1328898184e3Ssthen timep 1329898184e3Ssthen 1330898184e3Ssthen=head2 The OVERLOAD: Keyword 1331898184e3Ssthen 1332898184e3SsthenInstead of writing an overloaded interface using pure Perl, you 1333898184e3Ssthencan also use the OVERLOAD keyword to define additional Perl names 1334898184e3Ssthenfor your functions (like the ALIAS: keyword above). However, the 1335898184e3Ssthenoverloaded functions must be defined with three parameters (except 1336898184e3Ssthenfor the nomethod() function which needs four parameters). If any 1337898184e3Ssthenfunction has the OVERLOAD: keyword, several additional lines 1338898184e3Ssthenwill be defined in the c file generated by xsubpp in order to 1339898184e3Ssthenregister with the overload magic. 1340898184e3Ssthen 1341898184e3SsthenSince blessed objects are actually stored as RV's, it is useful 1342898184e3Ssthento use the typemap features to preprocess parameters and extract 1343898184e3Ssthenthe actual SV stored within the blessed RV. See the sample for 1344898184e3SsthenT_PTROBJ_SPECIAL below. 1345898184e3Ssthen 1346898184e3SsthenTo use the OVERLOAD: keyword, create an XS function which takes 1347898184e3Ssthenthree input parameters ( or use the c style '...' definition) like 1348898184e3Ssthenthis: 1349898184e3Ssthen 1350898184e3Ssthen SV * 1351898184e3Ssthen cmp (lobj, robj, swap) 1352898184e3Ssthen My_Module_obj lobj 1353898184e3Ssthen My_Module_obj robj 1354898184e3Ssthen IV swap 1355898184e3Ssthen OVERLOAD: cmp <=> 1356898184e3Ssthen { /* function defined here */} 1357898184e3Ssthen 1358898184e3SsthenIn this case, the function will overload both of the three way 1359898184e3Ssthencomparison operators. For all overload operations using non-alpha 1360898184e3Ssthencharacters, you must type the parameter without quoting, separating 1361898184e3Ssthenmultiple overloads with whitespace. Note that "" (the stringify 1362898184e3Ssthenoverload) should be entered as \"\" (i.e. escaped). 1363898184e3Ssthen 1364898184e3Ssthen=head2 The FALLBACK: Keyword 1365898184e3Ssthen 1366898184e3SsthenIn addition to the OVERLOAD keyword, if you need to control how 1367898184e3SsthenPerl autogenerates missing overloaded operators, you can set the 1368898184e3SsthenFALLBACK keyword in the module header section, like this: 1369898184e3Ssthen 1370898184e3Ssthen MODULE = RPC PACKAGE = RPC 1371898184e3Ssthen 1372898184e3Ssthen FALLBACK: TRUE 1373898184e3Ssthen ... 1374898184e3Ssthen 1375898184e3Ssthenwhere FALLBACK can take any of the three values TRUE, FALSE, or 1376898184e3SsthenUNDEF. If you do not set any FALLBACK value when using OVERLOAD, 1377898184e3Ssthenit defaults to UNDEF. FALLBACK is not used except when one or 1378898184e3Ssthenmore functions using OVERLOAD have been defined. Please see 1379898184e3SsthenL<overload/fallback> for more details. 1380898184e3Ssthen 1381898184e3Ssthen=head2 The INTERFACE: Keyword 1382898184e3Ssthen 1383898184e3SsthenThis keyword declares the current XSUB as a keeper of the given 1384898184e3Ssthencalling signature. If some text follows this keyword, it is 1385898184e3Ssthenconsidered as a list of functions which have this signature, and 1386898184e3Ssthenshould be attached to the current XSUB. 1387898184e3Ssthen 1388898184e3SsthenFor example, if you have 4 C functions multiply(), divide(), add(), 1389898184e3Ssthensubtract() all having the signature: 1390898184e3Ssthen 1391898184e3Ssthen symbolic f(symbolic, symbolic); 1392898184e3Ssthen 1393898184e3Ssthenyou can make them all to use the same XSUB using this: 1394898184e3Ssthen 1395898184e3Ssthen symbolic 1396898184e3Ssthen interface_s_ss(arg1, arg2) 1397898184e3Ssthen symbolic arg1 1398898184e3Ssthen symbolic arg2 1399898184e3Ssthen INTERFACE: 1400898184e3Ssthen multiply divide 1401898184e3Ssthen add subtract 1402898184e3Ssthen 1403898184e3Ssthen(This is the complete XSUB code for 4 Perl functions!) Four generated 1404898184e3SsthenPerl function share names with corresponding C functions. 1405898184e3Ssthen 1406898184e3SsthenThe advantage of this approach comparing to ALIAS: keyword is that there 1407898184e3Ssthenis no need to code a switch statement, each Perl function (which shares 1408898184e3Ssthenthe same XSUB) knows which C function it should call. Additionally, one 1409898184e3Ssthencan attach an extra function remainder() at runtime by using 1410898184e3Ssthen 1411898184e3Ssthen CV *mycv = newXSproto("Symbolic::remainder", 1412898184e3Ssthen XS_Symbolic_interface_s_ss, __FILE__, "$$"); 1413898184e3Ssthen XSINTERFACE_FUNC_SET(mycv, remainder); 1414898184e3Ssthen 1415898184e3Ssthensay, from another XSUB. (This example supposes that there was no 1416898184e3SsthenINTERFACE_MACRO: section, otherwise one needs to use something else instead of 1417898184e3SsthenC<XSINTERFACE_FUNC_SET>, see the next section.) 1418898184e3Ssthen 1419898184e3Ssthen=head2 The INTERFACE_MACRO: Keyword 1420898184e3Ssthen 1421898184e3SsthenThis keyword allows one to define an INTERFACE using a different way 1422898184e3Ssthento extract a function pointer from an XSUB. The text which follows 1423898184e3Ssthenthis keyword should give the name of macros which would extract/set a 1424898184e3Ssthenfunction pointer. The extractor macro is given return type, C<CV*>, 1425898184e3Ssthenand C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv, 1426898184e3Ssthenand the function pointer. 1427898184e3Ssthen 1428898184e3SsthenThe default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>. 1429898184e3SsthenAn INTERFACE keyword with an empty list of functions can be omitted if 1430898184e3SsthenINTERFACE_MACRO keyword is used. 1431898184e3Ssthen 1432898184e3SsthenSuppose that in the previous example functions pointers for 1433898184e3Ssthenmultiply(), divide(), add(), subtract() are kept in a global C array 1434898184e3SsthenC<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>, 1435898184e3SsthenC<subtract_off>. Then one can use 1436898184e3Ssthen 1437898184e3Ssthen #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \ 1438898184e3Ssthen ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32]) 1439898184e3Ssthen #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \ 1440898184e3Ssthen CvXSUBANY(cv).any_i32 = CAT2( f, _off ) 1441898184e3Ssthen 1442898184e3Ssthenin C section, 1443898184e3Ssthen 1444898184e3Ssthen symbolic 1445898184e3Ssthen interface_s_ss(arg1, arg2) 1446898184e3Ssthen symbolic arg1 1447898184e3Ssthen symbolic arg2 1448898184e3Ssthen INTERFACE_MACRO: 1449898184e3Ssthen XSINTERFACE_FUNC_BYOFFSET 1450898184e3Ssthen XSINTERFACE_FUNC_BYOFFSET_set 1451898184e3Ssthen INTERFACE: 1452898184e3Ssthen multiply divide 1453898184e3Ssthen add subtract 1454898184e3Ssthen 1455898184e3Ssthenin XSUB section. 1456898184e3Ssthen 1457898184e3Ssthen=head2 The INCLUDE: Keyword 1458898184e3Ssthen 1459898184e3SsthenThis keyword can be used to pull other files into the XS module. The other 1460898184e3Ssthenfiles may have XS code. INCLUDE: can also be used to run a command to 1461898184e3Ssthengenerate the XS code to be pulled into the module. 1462898184e3Ssthen 1463898184e3SsthenThe file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function: 1464898184e3Ssthen 1465898184e3Ssthen bool_t 1466898184e3Ssthen rpcb_gettime(host,timep) 1467898184e3Ssthen char *host 1468898184e3Ssthen time_t &timep 1469898184e3Ssthen OUTPUT: 1470898184e3Ssthen timep 1471898184e3Ssthen 1472898184e3SsthenThe XS module can use INCLUDE: to pull that file into it. 1473898184e3Ssthen 1474898184e3Ssthen INCLUDE: Rpcb1.xsh 1475898184e3Ssthen 1476898184e3SsthenIf the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then 1477898184e3Ssthenthe compiler will interpret the parameters as a command. This feature is 1478898184e3Ssthenmildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented 1479898184e3Ssthenbelow. 1480898184e3Ssthen 1481898184e3Ssthen INCLUDE: cat Rpcb1.xsh | 1482898184e3Ssthen 1483898184e3SsthenDo not use this to run perl: C<INCLUDE: perl |> will run the perl that 1484898184e3Ssthenhappens to be the first in your path and not necessarily the same perl that is 1485898184e3Ssthenused to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">. 1486898184e3Ssthen 1487898184e3Ssthen=head2 The INCLUDE_COMMAND: Keyword 1488898184e3Ssthen 1489898184e3SsthenRuns the supplied command and includes its output into the current XS 1490898184e3Ssthendocument. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token 1491898184e3Ssthenin that it runs the same perl interpreter that is running C<xsubpp>: 1492898184e3Ssthen 1493898184e3Ssthen INCLUDE_COMMAND: cat Rpcb1.xsh 1494898184e3Ssthen 1495898184e3Ssthen INCLUDE_COMMAND: $^X -e ... 1496898184e3Ssthen 1497898184e3Ssthen=head2 The CASE: Keyword 1498898184e3Ssthen 1499898184e3SsthenThe CASE: keyword allows an XSUB to have multiple distinct parts with each 1500898184e3Ssthenpart acting as a virtual XSUB. CASE: is greedy and if it is used then all 1501898184e3Ssthenother XS keywords must be contained within a CASE:. This means nothing may 1502898184e3Ssthenprecede the first CASE: in the XSUB and anything following the last CASE: is 1503898184e3Ssthenincluded in that case. 1504898184e3Ssthen 1505898184e3SsthenA CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS: 1506898184e3Ssthenvariable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable 1507898184e3Ssthen(see L<"Variable-length Parameter Lists">). The last CASE: becomes the 1508898184e3SsthenB<default> case if it is not associated with a conditional. The following 1509898184e3Ssthenexample shows CASE switched via C<ix> with a function C<rpcb_gettime()> 1510898184e3Ssthenhaving an alias C<x_gettime()>. When the function is called as 1511898184e3SsthenC<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>, 1512898184e3Ssthenbut when the function is called as C<x_gettime()> its parameters are 1513898184e3Ssthenreversed, C<(time_t *timep, char *host)>. 1514898184e3Ssthen 1515898184e3Ssthen long 1516898184e3Ssthen rpcb_gettime(a,b) 1517898184e3Ssthen CASE: ix == 1 1518898184e3Ssthen ALIAS: 1519898184e3Ssthen x_gettime = 1 1520898184e3Ssthen INPUT: 1521898184e3Ssthen # 'a' is timep, 'b' is host 1522898184e3Ssthen char *b 1523898184e3Ssthen time_t a = NO_INIT 1524898184e3Ssthen CODE: 1525898184e3Ssthen RETVAL = rpcb_gettime( b, &a ); 1526898184e3Ssthen OUTPUT: 1527898184e3Ssthen a 1528898184e3Ssthen RETVAL 1529898184e3Ssthen CASE: 1530898184e3Ssthen # 'a' is host, 'b' is timep 1531898184e3Ssthen char *a 1532898184e3Ssthen time_t &b = NO_INIT 1533898184e3Ssthen OUTPUT: 1534898184e3Ssthen b 1535898184e3Ssthen RETVAL 1536898184e3Ssthen 1537898184e3SsthenThat function can be called with either of the following statements. Note 1538898184e3Ssthenthe different argument lists. 1539898184e3Ssthen 1540898184e3Ssthen $status = rpcb_gettime( $host, $timep ); 1541898184e3Ssthen 1542898184e3Ssthen $status = x_gettime( $timep, $host ); 1543898184e3Ssthen 1544898184e3Ssthen=head2 The EXPORT_XSUB_SYMBOLS: Keyword 1545898184e3Ssthen 1546898184e3SsthenThe EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need. 1547898184e3SsthenIn perl versions earlier than 5.16.0, this keyword does nothing. Starting 1548898184e3Ssthenwith 5.16, XSUB symbols are no longer exported by default. That is, they 1549898184e3Ssthenare C<static> functions. If you include 1550898184e3Ssthen 1551898184e3Ssthen EXPORT_XSUB_SYMBOLS: ENABLE 1552898184e3Ssthen 1553898184e3Ssthenin your XS code, the XSUBs following this line will not be declared C<static>. 1554898184e3SsthenYou can later disable this with 1555898184e3Ssthen 1556898184e3Ssthen EXPORT_XSUB_SYMBOLS: DISABLE 1557898184e3Ssthen 1558898184e3Ssthenwhich, again, is the default that you should probably never change. 1559898184e3SsthenYou cannot use this keyword on versions of perl before 5.16 to make 1560898184e3SsthenXSUBs C<static>. 1561898184e3Ssthen 1562898184e3Ssthen=head2 The & Unary Operator 1563898184e3Ssthen 1564898184e3SsthenThe C<&> unary operator in the INPUT: section is used to tell B<xsubpp> 1565898184e3Ssthenthat it should convert a Perl value to/from C using the C type to the left 1566898184e3Ssthenof C<&>, but provide a pointer to this value when the C function is called. 1567898184e3Ssthen 1568898184e3SsthenThis is useful to avoid a CODE: block for a C function which takes a parameter 1569898184e3Ssthenby reference. Typically, the parameter should be not a pointer type (an 1570898184e3SsthenC<int> or C<long> but not an C<int*> or C<long*>). 1571898184e3Ssthen 1572898184e3SsthenThe following XSUB will generate incorrect C code. The B<xsubpp> compiler will 1573898184e3Ssthenturn this into code which calls C<rpcb_gettime()> with parameters C<(char 1574898184e3Ssthen*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep> 1575898184e3Ssthenparameter to be of type C<time_t*> rather than C<time_t>. 1576898184e3Ssthen 1577898184e3Ssthen bool_t 1578898184e3Ssthen rpcb_gettime(host,timep) 1579898184e3Ssthen char *host 1580898184e3Ssthen time_t timep 1581898184e3Ssthen OUTPUT: 1582898184e3Ssthen timep 1583898184e3Ssthen 1584898184e3SsthenThat problem is corrected by using the C<&> operator. The B<xsubpp> compiler 1585898184e3Ssthenwill now turn this into code which calls C<rpcb_gettime()> correctly with 1586898184e3Ssthenparameters C<(char *host, time_t *timep)>. It does this by carrying the 1587898184e3SsthenC<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>. 1588898184e3Ssthen 1589898184e3Ssthen bool_t 1590898184e3Ssthen rpcb_gettime(host,timep) 1591898184e3Ssthen char *host 1592898184e3Ssthen time_t &timep 1593898184e3Ssthen OUTPUT: 1594898184e3Ssthen timep 1595898184e3Ssthen 1596898184e3Ssthen=head2 Inserting POD, Comments and C Preprocessor Directives 1597898184e3Ssthen 1598898184e3SsthenC preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, 1599898184e3SsthenPPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions. 1600898184e3SsthenComments are allowed anywhere after the MODULE keyword. The compiler will 1601898184e3Ssthenpass the preprocessor directives through untouched and will remove the 1602898184e3Ssthencommented lines. POD documentation is allowed at any point, both in the 1603898184e3SsthenC and XS language sections. POD must be terminated with a C<=cut> command; 1604898184e3SsthenC<xsubpp> will exit with an error if it does not. It is very unlikely that 1605898184e3Ssthenhuman generated C code will be mistaken for POD, as most indenting styles 1606898184e3Ssthenresult in whitespace in front of any line starting with C<=>. Machine 1607898184e3Ssthengenerated XS files may fall into this trap unless care is taken to 1608898184e3Ssthenensure that a space breaks the sequence "\n=". 1609898184e3Ssthen 1610898184e3SsthenComments can be added to XSUBs by placing a C<#> as the first 1611898184e3Ssthennon-whitespace of a line. Care should be taken to avoid making the 1612898184e3Ssthencomment look like a C preprocessor directive, lest it be interpreted as 1613898184e3Ssthensuch. The simplest way to prevent this is to put whitespace in front of 1614898184e3Ssthenthe C<#>. 1615898184e3Ssthen 1616898184e3SsthenIf you use preprocessor directives to choose one of two 1617898184e3Ssthenversions of a function, use 1618898184e3Ssthen 1619898184e3Ssthen #if ... version1 1620898184e3Ssthen #else /* ... version2 */ 1621898184e3Ssthen #endif 1622898184e3Ssthen 1623898184e3Ssthenand not 1624898184e3Ssthen 1625898184e3Ssthen #if ... version1 1626898184e3Ssthen #endif 1627898184e3Ssthen #if ... version2 1628898184e3Ssthen #endif 1629898184e3Ssthen 1630898184e3Ssthenbecause otherwise B<xsubpp> will believe that you made a duplicate 1631898184e3Ssthendefinition of the function. Also, put a blank line before the 1632898184e3Ssthen#else/#endif so it will not be seen as part of the function body. 1633898184e3Ssthen 1634898184e3Ssthen=head2 Using XS With C++ 1635898184e3Ssthen 1636898184e3SsthenIf an XSUB name contains C<::>, it is considered to be a C++ method. 1637898184e3SsthenThe generated Perl function will assume that 1638898184e3Ssthenits first argument is an object pointer. The object pointer 1639898184e3Ssthenwill be stored in a variable called THIS. The object should 1640898184e3Ssthenhave been created by C++ with the new() function and should 1641898184e3Ssthenbe blessed by Perl with the sv_setref_pv() macro. The 1642898184e3Ssthenblessing of the object by Perl can be handled by a typemap. An example 1643898184e3Ssthentypemap is shown at the end of this section. 1644898184e3Ssthen 1645898184e3SsthenIf the return type of the XSUB includes C<static>, the method is considered 1646898184e3Ssthento be a static method. It will call the C++ 1647898184e3Ssthenfunction using the class::method() syntax. If the method is not static 1648898184e3Ssthenthe function will be called using the THIS-E<gt>method() syntax. 1649898184e3Ssthen 1650898184e3SsthenThe next examples will use the following C++ class. 1651898184e3Ssthen 1652898184e3Ssthen class color { 1653898184e3Ssthen public: 1654898184e3Ssthen color(); 1655898184e3Ssthen ~color(); 1656898184e3Ssthen int blue(); 1657898184e3Ssthen void set_blue( int ); 1658898184e3Ssthen 1659898184e3Ssthen private: 1660898184e3Ssthen int c_blue; 1661898184e3Ssthen }; 1662898184e3Ssthen 1663898184e3SsthenThe XSUBs for the blue() and set_blue() methods are defined with the class 1664898184e3Ssthenname but the parameter for the object (THIS, or "self") is implicit and is 1665898184e3Ssthennot listed. 1666898184e3Ssthen 1667898184e3Ssthen int 1668898184e3Ssthen color::blue() 1669898184e3Ssthen 1670898184e3Ssthen void 1671898184e3Ssthen color::set_blue( val ) 1672898184e3Ssthen int val 1673898184e3Ssthen 1674898184e3SsthenBoth Perl functions will expect an object as the first parameter. In the 1675898184e3Ssthengenerated C++ code the object is called C<THIS>, and the method call will 1676898184e3Ssthenbe performed on this object. So in the C++ code the blue() and set_blue() 1677898184e3Ssthenmethods will be called as this: 1678898184e3Ssthen 1679898184e3Ssthen RETVAL = THIS->blue(); 1680898184e3Ssthen 1681898184e3Ssthen THIS->set_blue( val ); 1682898184e3Ssthen 1683898184e3SsthenYou could also write a single get/set method using an optional argument: 1684898184e3Ssthen 1685898184e3Ssthen int 1686898184e3Ssthen color::blue( val = NO_INIT ) 1687898184e3Ssthen int val 1688898184e3Ssthen PROTOTYPE $;$ 1689898184e3Ssthen CODE: 1690898184e3Ssthen if (items > 1) 1691898184e3Ssthen THIS->set_blue( val ); 1692898184e3Ssthen RETVAL = THIS->blue(); 1693898184e3Ssthen OUTPUT: 1694898184e3Ssthen RETVAL 1695898184e3Ssthen 1696898184e3SsthenIf the function's name is B<DESTROY> then the C++ C<delete> function will be 1697898184e3Ssthencalled and C<THIS> will be given as its parameter. The generated C++ code for 1698898184e3Ssthen 1699898184e3Ssthen void 1700898184e3Ssthen color::DESTROY() 1701898184e3Ssthen 1702898184e3Ssthenwill look like this: 1703898184e3Ssthen 1704898184e3Ssthen color *THIS = ...; // Initialized as in typemap 1705898184e3Ssthen 1706898184e3Ssthen delete THIS; 1707898184e3Ssthen 1708898184e3SsthenIf the function's name is B<new> then the C++ C<new> function will be called 1709898184e3Ssthento create a dynamic C++ object. The XSUB will expect the class name, which 1710898184e3Ssthenwill be kept in a variable called C<CLASS>, to be given as the first 1711898184e3Ssthenargument. 1712898184e3Ssthen 1713898184e3Ssthen color * 1714898184e3Ssthen color::new() 1715898184e3Ssthen 1716898184e3SsthenThe generated C++ code will call C<new>. 1717898184e3Ssthen 1718898184e3Ssthen RETVAL = new color(); 1719898184e3Ssthen 1720898184e3SsthenThe following is an example of a typemap that could be used for this C++ 1721898184e3Ssthenexample. 1722898184e3Ssthen 1723898184e3Ssthen TYPEMAP 1724898184e3Ssthen color * O_OBJECT 1725898184e3Ssthen 1726898184e3Ssthen OUTPUT 1727898184e3Ssthen # The Perl object is blessed into 'CLASS', which should be a 1728898184e3Ssthen # char* having the name of the package for the blessing. 1729898184e3Ssthen O_OBJECT 1730898184e3Ssthen sv_setref_pv( $arg, CLASS, (void*)$var ); 1731898184e3Ssthen 1732898184e3Ssthen INPUT 1733898184e3Ssthen O_OBJECT 1734898184e3Ssthen if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) ) 1735898184e3Ssthen $var = ($type)SvIV((SV*)SvRV( $arg )); 1736898184e3Ssthen else{ 17376fb12b70Safresh1 warn("${Package}::$func_name() -- " . 17386fb12b70Safresh1 "$var is not a blessed SV reference"); 1739898184e3Ssthen XSRETURN_UNDEF; 1740898184e3Ssthen } 1741898184e3Ssthen 1742898184e3Ssthen=head2 Interface Strategy 1743898184e3Ssthen 1744898184e3SsthenWhen designing an interface between Perl and a C library a straight 1745898184e3Ssthentranslation from C to XS (such as created by C<h2xs -x>) is often sufficient. 1746898184e3SsthenHowever, sometimes the interface will look 1747898184e3Ssthenvery C-like and occasionally nonintuitive, especially when the C function 1748898184e3Ssthenmodifies one of its parameters, or returns failure inband (as in "negative 1749898184e3Ssthenreturn values mean failure"). In cases where the programmer wishes to 1750898184e3Ssthencreate a more Perl-like interface the following strategy may help to 1751898184e3Ssthenidentify the more critical parts of the interface. 1752898184e3Ssthen 1753898184e3SsthenIdentify the C functions with input/output or output parameters. The XSUBs for 1754898184e3Ssthenthese functions may be able to return lists to Perl. 1755898184e3Ssthen 1756898184e3SsthenIdentify the C functions which use some inband info as an indication 1757898184e3Ssthenof failure. They may be 1758898184e3Ssthencandidates to return undef or an empty list in case of failure. If the 1759898184e3Ssthenfailure may be detected without a call to the C function, you may want to use 1760898184e3Ssthenan INIT: section to report the failure. For failures detectable after the C 1761898184e3Ssthenfunction returns one may want to use a POSTCALL: section to process the 1762898184e3Ssthenfailure. In more complicated cases use CODE: or PPCODE: sections. 1763898184e3Ssthen 1764898184e3SsthenIf many functions use the same failure indication based on the return value, 1765898184e3Ssthenyou may want to create a special typedef to handle this situation. Put 1766898184e3Ssthen 1767898184e3Ssthen typedef int negative_is_failure; 1768898184e3Ssthen 1769898184e3Ssthennear the beginning of XS file, and create an OUTPUT typemap entry 1770898184e3Ssthenfor C<negative_is_failure> which converts negative values to C<undef>, or 1771898184e3Ssthenmaybe croak()s. After this the return value of type C<negative_is_failure> 1772898184e3Ssthenwill create more Perl-like interface. 1773898184e3Ssthen 1774898184e3SsthenIdentify which values are used by only the C and XSUB functions 1775898184e3Ssthenthemselves, say, when a parameter to a function should be a contents of a 1776898184e3Ssthenglobal variable. If Perl does not need to access the contents of the value 1777898184e3Ssthenthen it may not be necessary to provide a translation for that value 1778898184e3Ssthenfrom C to Perl. 1779898184e3Ssthen 1780898184e3SsthenIdentify the pointers in the C function parameter lists and return 1781898184e3Ssthenvalues. Some pointers may be used to implement input/output or 1782898184e3Ssthenoutput parameters, they can be handled in XS with the C<&> unary operator, 1783898184e3Ssthenand, possibly, using the NO_INIT keyword. 1784898184e3SsthenSome others will require handling of types like C<int *>, and one needs 1785898184e3Ssthento decide what a useful Perl translation will do in such a case. When 1786898184e3Ssthenthe semantic is clear, it is advisable to put the translation into a typemap 1787898184e3Ssthenfile. 1788898184e3Ssthen 1789898184e3SsthenIdentify the structures used by the C functions. In many 1790898184e3Ssthencases it may be helpful to use the T_PTROBJ typemap for 1791898184e3Ssthenthese structures so they can be manipulated by Perl as 1792898184e3Ssthenblessed objects. (This is handled automatically by C<h2xs -x>.) 1793898184e3Ssthen 1794898184e3SsthenIf the same C type is used in several different contexts which require 1795898184e3Ssthendifferent translations, C<typedef> several new types mapped to this C type, 1796898184e3Ssthenand create separate F<typemap> entries for these new types. Use these 1797898184e3Ssthentypes in declarations of return type and parameters to XSUBs. 1798898184e3Ssthen 1799898184e3Ssthen=head2 Perl Objects And C Structures 1800898184e3Ssthen 1801898184e3SsthenWhen dealing with C structures one should select either 1802898184e3SsthenB<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are 1803898184e3Ssthendesigned to handle pointers to complex objects. The 1804898184e3SsthenT_PTRREF type will allow the Perl object to be unblessed 1805898184e3Ssthenwhile the T_PTROBJ type requires that the object be blessed. 1806898184e3SsthenBy using T_PTROBJ one can achieve a form of type-checking 1807898184e3Ssthenbecause the XSUB will attempt to verify that the Perl object 1808898184e3Ssthenis of the expected type. 1809898184e3Ssthen 1810898184e3SsthenThe following XS code shows the getnetconfigent() function which is used 1811898184e3Ssthenwith ONC+ TIRPC. The getnetconfigent() function will return a pointer to a 1812898184e3SsthenC structure and has the C prototype shown below. The example will 1813898184e3Ssthendemonstrate how the C pointer will become a Perl reference. Perl will 1814898184e3Ssthenconsider this reference to be a pointer to a blessed object and will 1815898184e3Ssthenattempt to call a destructor for the object. A destructor will be 1816898184e3Ssthenprovided in the XS source to free the memory used by getnetconfigent(). 1817898184e3SsthenDestructors in XS can be created by specifying an XSUB function whose name 1818898184e3Ssthenends with the word B<DESTROY>. XS destructors can be used to free memory 1819898184e3Ssthenwhich may have been malloc'd by another XSUB. 1820898184e3Ssthen 1821898184e3Ssthen struct netconfig *getnetconfigent(const char *netid); 1822898184e3Ssthen 1823898184e3SsthenA C<typedef> will be created for C<struct netconfig>. The Perl 1824898184e3Ssthenobject will be blessed in a class matching the name of the C 1825898184e3Ssthentype, with the tag C<Ptr> appended, and the name should not 1826898184e3Ssthenhave embedded spaces if it will be a Perl package name. The 1827898184e3Ssthendestructor will be placed in a class corresponding to the 1828898184e3Ssthenclass of the object and the PREFIX keyword will be used to 1829898184e3Ssthentrim the name to the word DESTROY as Perl will expect. 1830898184e3Ssthen 1831898184e3Ssthen typedef struct netconfig Netconfig; 1832898184e3Ssthen 1833898184e3Ssthen MODULE = RPC PACKAGE = RPC 1834898184e3Ssthen 1835898184e3Ssthen Netconfig * 1836898184e3Ssthen getnetconfigent(netid) 1837898184e3Ssthen char *netid 1838898184e3Ssthen 1839898184e3Ssthen MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ 1840898184e3Ssthen 1841898184e3Ssthen void 1842898184e3Ssthen rpcb_DESTROY(netconf) 1843898184e3Ssthen Netconfig *netconf 1844898184e3Ssthen CODE: 1845898184e3Ssthen printf("Now in NetconfigPtr::DESTROY\n"); 1846898184e3Ssthen free( netconf ); 1847898184e3Ssthen 1848898184e3SsthenThis example requires the following typemap entry. Consult 1849898184e3SsthenL<perlxstypemap> for more information about adding new typemaps 1850898184e3Ssthenfor an extension. 1851898184e3Ssthen 1852898184e3Ssthen TYPEMAP 1853898184e3Ssthen Netconfig * T_PTROBJ 1854898184e3Ssthen 1855898184e3SsthenThis example will be used with the following Perl statements. 1856898184e3Ssthen 1857898184e3Ssthen use RPC; 1858898184e3Ssthen $netconf = getnetconfigent("udp"); 1859898184e3Ssthen 1860898184e3SsthenWhen Perl destroys the object referenced by $netconf it will send the 1861898184e3Ssthenobject to the supplied XSUB DESTROY function. Perl cannot determine, and 1862898184e3Ssthendoes not care, that this object is a C struct and not a Perl object. In 1863898184e3Ssthenthis sense, there is no difference between the object created by the 1864898184e3Ssthengetnetconfigent() XSUB and an object created by a normal Perl subroutine. 1865898184e3Ssthen 1866898184e3Ssthen=head2 Safely Storing Static Data in XS 1867898184e3Ssthen 1868898184e3SsthenStarting with Perl 5.8, a macro framework has been defined to allow 1869898184e3Ssthenstatic data to be safely stored in XS modules that will be accessed from 1870898184e3Ssthena multi-threaded Perl. 1871898184e3Ssthen 1872898184e3SsthenAlthough primarily designed for use with multi-threaded Perl, the macros 1873898184e3Ssthenhave been designed so that they will work with non-threaded Perl as well. 1874898184e3Ssthen 1875898184e3SsthenIt is therefore strongly recommended that these macros be used by all 1876898184e3SsthenXS modules that make use of static data. 1877898184e3Ssthen 1878898184e3SsthenThe easiest way to get a template set of macros to use is by specifying 1879898184e3Ssthenthe C<-g> (C<--global>) option with h2xs (see L<h2xs>). 1880898184e3Ssthen 1881898184e3SsthenBelow is an example module that makes use of the macros. 1882898184e3Ssthen 18836fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 1884898184e3Ssthen #include "EXTERN.h" 1885898184e3Ssthen #include "perl.h" 1886898184e3Ssthen #include "XSUB.h" 1887898184e3Ssthen 1888898184e3Ssthen /* Global Data */ 1889898184e3Ssthen 1890898184e3Ssthen #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION 1891898184e3Ssthen 1892898184e3Ssthen typedef struct { 1893898184e3Ssthen int count; 1894898184e3Ssthen char name[3][100]; 1895898184e3Ssthen } my_cxt_t; 1896898184e3Ssthen 1897898184e3Ssthen START_MY_CXT 1898898184e3Ssthen 1899898184e3Ssthen MODULE = BlindMice PACKAGE = BlindMice 1900898184e3Ssthen 1901898184e3Ssthen BOOT: 1902898184e3Ssthen { 1903898184e3Ssthen MY_CXT_INIT; 1904898184e3Ssthen MY_CXT.count = 0; 1905898184e3Ssthen strcpy(MY_CXT.name[0], "None"); 1906898184e3Ssthen strcpy(MY_CXT.name[1], "None"); 1907898184e3Ssthen strcpy(MY_CXT.name[2], "None"); 1908898184e3Ssthen } 1909898184e3Ssthen 1910898184e3Ssthen int 1911898184e3Ssthen newMouse(char * name) 1912898184e3Ssthen PREINIT: 1913898184e3Ssthen dMY_CXT; 1914898184e3Ssthen CODE: 1915898184e3Ssthen if (MY_CXT.count >= 3) { 1916898184e3Ssthen warn("Already have 3 blind mice"); 1917898184e3Ssthen RETVAL = 0; 1918898184e3Ssthen } 1919898184e3Ssthen else { 1920898184e3Ssthen RETVAL = ++ MY_CXT.count; 1921898184e3Ssthen strcpy(MY_CXT.name[MY_CXT.count - 1], name); 1922898184e3Ssthen } 19236fb12b70Safresh1 OUTPUT: 19246fb12b70Safresh1 RETVAL 1925898184e3Ssthen 1926898184e3Ssthen char * 1927898184e3Ssthen get_mouse_name(index) 1928898184e3Ssthen int index 19296fb12b70Safresh1 PREINIT: 1930898184e3Ssthen dMY_CXT; 19316fb12b70Safresh1 CODE: 1932898184e3Ssthen if (index > MY_CXT.count) 1933898184e3Ssthen croak("There are only 3 blind mice."); 1934898184e3Ssthen else 19356fb12b70Safresh1 RETVAL = MY_CXT.name[index - 1]; 19366fb12b70Safresh1 OUTPUT: 19376fb12b70Safresh1 RETVAL 1938898184e3Ssthen 1939898184e3Ssthen void 1940898184e3Ssthen CLONE(...) 1941898184e3Ssthen CODE: 1942898184e3Ssthen MY_CXT_CLONE; 1943898184e3Ssthen 19446fb12b70Safresh1=head3 MY_CXT REFERENCE 1945898184e3Ssthen 1946898184e3Ssthen=over 5 1947898184e3Ssthen 1948898184e3Ssthen=item MY_CXT_KEY 1949898184e3Ssthen 1950898184e3SsthenThis macro is used to define a unique key to refer to the static data 1951898184e3Ssthenfor an XS module. The suggested naming scheme, as used by h2xs, is to 1952898184e3Ssthenuse a string that consists of the module name, the string "::_guts" 1953898184e3Ssthenand the module version number. 1954898184e3Ssthen 1955898184e3Ssthen #define MY_CXT_KEY "MyModule::_guts" XS_VERSION 1956898184e3Ssthen 1957898184e3Ssthen=item typedef my_cxt_t 1958898184e3Ssthen 1959898184e3SsthenThis struct typedef I<must> always be called C<my_cxt_t>. The other 1960898184e3SsthenC<CXT*> macros assume the existence of the C<my_cxt_t> typedef name. 1961898184e3Ssthen 1962898184e3SsthenDeclare a typedef named C<my_cxt_t> that is a structure that contains 1963898184e3Ssthenall the data that needs to be interpreter-local. 1964898184e3Ssthen 1965898184e3Ssthen typedef struct { 1966898184e3Ssthen int some_value; 1967898184e3Ssthen } my_cxt_t; 1968898184e3Ssthen 1969898184e3Ssthen=item START_MY_CXT 1970898184e3Ssthen 1971898184e3SsthenAlways place the START_MY_CXT macro directly after the declaration 1972898184e3Ssthenof C<my_cxt_t>. 1973898184e3Ssthen 1974898184e3Ssthen=item MY_CXT_INIT 1975898184e3Ssthen 19766fb12b70Safresh1The MY_CXT_INIT macro initializes storage for the C<my_cxt_t> struct. 1977898184e3Ssthen 1978898184e3SsthenIt I<must> be called exactly once, typically in a BOOT: section. If you 1979898184e3Ssthenare maintaining multiple interpreters, it should be called once in each 1980898184e3Sstheninterpreter instance, except for interpreters cloned from existing ones. 1981898184e3Ssthen(But see L</MY_CXT_CLONE> below.) 1982898184e3Ssthen 1983898184e3Ssthen=item dMY_CXT 1984898184e3Ssthen 1985898184e3SsthenUse the dMY_CXT macro (a declaration) in all the functions that access 1986898184e3SsthenMY_CXT. 1987898184e3Ssthen 1988898184e3Ssthen=item MY_CXT 1989898184e3Ssthen 1990898184e3SsthenUse the MY_CXT macro to access members of the C<my_cxt_t> struct. For 1991898184e3Ssthenexample, if C<my_cxt_t> is 1992898184e3Ssthen 1993898184e3Ssthen typedef struct { 1994898184e3Ssthen int index; 1995898184e3Ssthen } my_cxt_t; 1996898184e3Ssthen 1997898184e3Ssthenthen use this to access the C<index> member 1998898184e3Ssthen 1999898184e3Ssthen dMY_CXT; 2000898184e3Ssthen MY_CXT.index = 2; 2001898184e3Ssthen 2002898184e3Ssthen=item aMY_CXT/pMY_CXT 2003898184e3Ssthen 2004898184e3SsthenC<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead 2005898184e3Ssthenof invoking it in each function it is possible to pass the declaration 2006898184e3Ssthenonto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg 2007898184e3Ssthen 2008898184e3Ssthen void sub1() { 2009898184e3Ssthen dMY_CXT; 2010898184e3Ssthen MY_CXT.index = 1; 2011898184e3Ssthen sub2(aMY_CXT); 2012898184e3Ssthen } 2013898184e3Ssthen 2014898184e3Ssthen void sub2(pMY_CXT) { 2015898184e3Ssthen MY_CXT.index = 2; 2016898184e3Ssthen } 2017898184e3Ssthen 2018898184e3SsthenAnalogously to C<pTHX>, there are equivalent forms for when the macro is the 2019898184e3Ssthenfirst or last in multiple arguments, where an underscore represents a 2020898184e3Ssthencomma, i.e. C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>. 2021898184e3Ssthen 2022898184e3Ssthen=item MY_CXT_CLONE 2023898184e3Ssthen 2024898184e3SsthenBy default, when a new interpreter is created as a copy of an existing one 2025898184e3Ssthen(eg via C<< threads->create() >>), both interpreters share the same physical 2026898184e3Ssthenmy_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's 2027898184e3SsthenC<CLONE()> function), causes a byte-for-byte copy of the structure to be 2028898184e3Ssthentaken, and any future dMY_CXT will cause the copy to be accessed instead. 2029898184e3Ssthen 2030898184e3Ssthen=item MY_CXT_INIT_INTERP(my_perl) 2031898184e3Ssthen 2032898184e3Ssthen=item dMY_CXT_INTERP(my_perl) 2033898184e3Ssthen 2034898184e3SsthenThese are versions of the macros which take an explicit interpreter as an 2035898184e3Ssthenargument. 2036898184e3Ssthen 2037898184e3Ssthen=back 2038898184e3Ssthen 2039898184e3SsthenNote that these macros will only work together within the I<same> source 2040898184e3Ssthenfile; that is, a dMY_CTX in one source file will access a different structure 2041898184e3Ssthenthan a dMY_CTX in another source file. 2042898184e3Ssthen 2043898184e3Ssthen=head2 Thread-aware system interfaces 2044898184e3Ssthen 2045898184e3SsthenStarting from Perl 5.8, in C/C++ level Perl knows how to wrap 2046898184e3Ssthensystem/library interfaces that have thread-aware versions 2047898184e3Ssthen(e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that 2048898184e3Ssthencorrectly handle the multithreaded interaction with the Perl 2049898184e3Sstheninterpreter. This will happen transparently, the only thing 2050898184e3Ssthenyou need to do is to instantiate a Perl interpreter. 2051898184e3Ssthen 2052898184e3SsthenThis wrapping happens always when compiling Perl core source 2053898184e3Ssthen(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is 2054898184e3Ssthendefined). When compiling XS code outside of Perl core the wrapping 2055898184e3Ssthendoes not take place. Note, however, that intermixing the _r-forms 2056898184e3Ssthen(as Perl compiled for multithreaded operation will do) and the _r-less 2057898184e3Ssthenforms is neither well-defined (inconsistent results, data corruption, 2058898184e3Ssthenor even crashes become more likely), nor is it very portable. 2059898184e3Ssthen 2060898184e3Ssthen=head1 EXAMPLES 2061898184e3Ssthen 2062898184e3SsthenFile C<RPC.xs>: Interface to some ONC+ RPC bind library functions. 2063898184e3Ssthen 20646fb12b70Safresh1 #define PERL_NO_GET_CONTEXT 2065898184e3Ssthen #include "EXTERN.h" 2066898184e3Ssthen #include "perl.h" 2067898184e3Ssthen #include "XSUB.h" 2068898184e3Ssthen 2069898184e3Ssthen #include <rpc/rpc.h> 2070898184e3Ssthen 2071898184e3Ssthen typedef struct netconfig Netconfig; 2072898184e3Ssthen 2073898184e3Ssthen MODULE = RPC PACKAGE = RPC 2074898184e3Ssthen 2075898184e3Ssthen SV * 2076898184e3Ssthen rpcb_gettime(host="localhost") 2077898184e3Ssthen char *host 2078898184e3Ssthen PREINIT: 2079898184e3Ssthen time_t timep; 2080898184e3Ssthen CODE: 2081898184e3Ssthen ST(0) = sv_newmortal(); 2082898184e3Ssthen if( rpcb_gettime( host, &timep ) ) 2083898184e3Ssthen sv_setnv( ST(0), (double)timep ); 2084898184e3Ssthen 2085898184e3Ssthen Netconfig * 2086898184e3Ssthen getnetconfigent(netid="udp") 2087898184e3Ssthen char *netid 2088898184e3Ssthen 2089898184e3Ssthen MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ 2090898184e3Ssthen 2091898184e3Ssthen void 2092898184e3Ssthen rpcb_DESTROY(netconf) 2093898184e3Ssthen Netconfig *netconf 2094898184e3Ssthen CODE: 2095898184e3Ssthen printf("NetconfigPtr::DESTROY\n"); 2096898184e3Ssthen free( netconf ); 2097898184e3Ssthen 2098898184e3SsthenFile C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>) 2099898184e3Ssthen 2100898184e3Ssthen TYPEMAP 2101898184e3Ssthen Netconfig * T_PTROBJ 2102898184e3Ssthen 2103898184e3SsthenFile C<RPC.pm>: Perl module for the RPC extension. 2104898184e3Ssthen 2105898184e3Ssthen package RPC; 2106898184e3Ssthen 2107898184e3Ssthen require Exporter; 2108898184e3Ssthen require DynaLoader; 2109898184e3Ssthen @ISA = qw(Exporter DynaLoader); 2110898184e3Ssthen @EXPORT = qw(rpcb_gettime getnetconfigent); 2111898184e3Ssthen 2112898184e3Ssthen bootstrap RPC; 2113898184e3Ssthen 1; 2114898184e3Ssthen 2115898184e3SsthenFile C<rpctest.pl>: Perl test program for the RPC extension. 2116898184e3Ssthen 2117898184e3Ssthen use RPC; 2118898184e3Ssthen 2119898184e3Ssthen $netconf = getnetconfigent(); 2120898184e3Ssthen $a = rpcb_gettime(); 2121898184e3Ssthen print "time = $a\n"; 2122898184e3Ssthen print "netconf = $netconf\n"; 2123898184e3Ssthen 2124898184e3Ssthen $netconf = getnetconfigent("tcp"); 2125898184e3Ssthen $a = rpcb_gettime("poplar"); 2126898184e3Ssthen print "time = $a\n"; 2127898184e3Ssthen print "netconf = $netconf\n"; 2128898184e3Ssthen 21296fb12b70Safresh1=head1 CAVEATS 21306fb12b70Safresh1 21316fb12b70Safresh1XS code has full access to system calls including C library functions. 21326fb12b70Safresh1It thus has the capability of interfering with things that the Perl core 21336fb12b70Safresh1or other modules have set up, such as signal handlers or file handles. 21346fb12b70Safresh1It could mess with the memory, or any number of harmful things. Don't. 21356fb12b70Safresh1 21366fb12b70Safresh1Some modules have an event loop, waiting for user-input. It is highly 21376fb12b70Safresh1unlikely that two such modules would work adequately together in a 21386fb12b70Safresh1single Perl application. 21396fb12b70Safresh1 21406fb12b70Safresh1In general, the perl interpreter views itself as the center of the 21416fb12b70Safresh1universe as far as the Perl program goes. XS code is viewed as a 21426fb12b70Safresh1help-mate, to accomplish things that perl doesn't do, or doesn't do fast 21436fb12b70Safresh1enough, but always subservient to perl. The closer XS code adheres to 21446fb12b70Safresh1this model, the less likely conflicts will occur. 21456fb12b70Safresh1 21466fb12b70Safresh1One area where there has been conflict is in regards to C locales. (See 21476fb12b70Safresh1L<perllocale>.) perl, with one exception and unless told otherwise, 2148*b8851fccSafresh1sets up the underlying locale the program is running in to the locale 2149*b8851fccSafresh1passed 2150*b8851fccSafresh1into it from the environment. This is an important difference from a 2151*b8851fccSafresh1generic C language program, where the underlying locale is the "C" 2152*b8851fccSafresh1locale unless the program changes it. As of v5.20, this underlying 2153*b8851fccSafresh1locale is completely hidden from pure perl code outside the lexical 2154*b8851fccSafresh1scope of C<S<use locale>> except for a couple of function calls in the 2155*b8851fccSafresh1POSIX module which of necessity use it. But the underlying locale, with 2156*b8851fccSafresh1that 2157*b8851fccSafresh1one exception is exposed to XS code, affecting all C library routines 2158*b8851fccSafresh1whose behavior is locale-dependent. Your XS code better not assume that 2159*b8851fccSafresh1the underlying locale is "C". The exception is the 21606fb12b70Safresh1L<C<LC_NUMERIC>|perllocale/Category LC_NUMERIC: Numeric Formatting> 21616fb12b70Safresh1locale category, and the reason it is an exception is that experience 21626fb12b70Safresh1has shown that it can be problematic for XS code, whereas we have not 21636fb12b70Safresh1had reports of problems with the 21646fb12b70Safresh1L<other locale categories|perllocale/WHAT IS A LOCALE>. And the reason 21656fb12b70Safresh1for this one category being problematic is that the character used as a 21666fb12b70Safresh1decimal point can vary. Many European languages use a comma, whereas 21676fb12b70Safresh1English, and hence Perl are expecting a dot (U+002E: FULL STOP). Many 21686fb12b70Safresh1modules can handle only the radix character being a dot, and so perl 21696fb12b70Safresh1attempts to make it so. Up through Perl v5.20, the attempt was merely 21706fb12b70Safresh1to set C<LC_NUMERIC> upon startup to the C<"C"> locale. Any 21716fb12b70Safresh1L<setlocale()|perllocale/The setlocale function> otherwise would change 21726fb12b70Safresh1it; this caused some failures. Therefore, starting in v5.22, perl tries 21736fb12b70Safresh1to keep C<LC_NUMERIC> always set to C<"C"> for XS code. 21746fb12b70Safresh1 21756fb12b70Safresh1To summarize, here's what to expect and how to handle locales in XS code: 21766fb12b70Safresh1 21776fb12b70Safresh1=over 21786fb12b70Safresh1 21796fb12b70Safresh1=item Non-locale-aware XS code 21806fb12b70Safresh1 21816fb12b70Safresh1Keep in mind that even if you think your code is not locale-aware, it 21826fb12b70Safresh1may call a C library function that is. Hopefully the man page for such 21836fb12b70Safresh1a function will indicate that dependency, but the documentation is 21846fb12b70Safresh1imperfect. 21856fb12b70Safresh1 2186*b8851fccSafresh1The current locale is exposed to XS code except possibly C<LC_NUMERIC> 2187*b8851fccSafresh1(explained in the next paragraph). 2188*b8851fccSafresh1There have not been reports of problems with the other categories. 2189*b8851fccSafresh1Perl initializes things on start-up so that the current locale is the 2190*b8851fccSafresh1one which is indicated by the user's environment in effect at that time. 2191*b8851fccSafresh1See L<perllocale/ENVIRONMENT>. 21926fb12b70Safresh1 2193*b8851fccSafresh1However, up through v5.20, Perl initialized things on start-up so that 2194*b8851fccSafresh1C<LC_NUMERIC> was set to the "C" locale. But if any code anywhere 2195*b8851fccSafresh1changed it, it would stay changed. This means that your module can't 21966fb12b70Safresh1count on C<LC_NUMERIC> being something in particular, and you can't 21976fb12b70Safresh1expect floating point numbers (including version strings) to have dots 21986fb12b70Safresh1in them. If you don't allow for a non-dot, your code could break if 2199*b8851fccSafresh1anyone anywhere changed the locale. For this reason, v5.22 changed 22006fb12b70Safresh1the behavior so that Perl tries to keep C<LC_NUMERIC> in the "C" locale 22016fb12b70Safresh1except around the operations internally where it should be something 22026fb12b70Safresh1else. Misbehaving XS code will always be able to change the locale 22036fb12b70Safresh1anyway, but the most common instance of this is checked for and 22046fb12b70Safresh1handled. 22056fb12b70Safresh1 22066fb12b70Safresh1=item Locale-aware XS code 22076fb12b70Safresh1 22086fb12b70Safresh1If the locale from the user's environment is desired, there should be no 22096fb12b70Safresh1need for XS code to set the locale except for C<LC_NUMERIC>, as perl has 22106fb12b70Safresh1already set it up. XS code should avoid changing the locale, as it can 22116fb12b70Safresh1adversely affect other, unrelated, code and may not be thread safe. 22126fb12b70Safresh1However, some alien libraries that may be called do set it, such as 22136fb12b70Safresh1C<Gtk>. This can cause problems for the perl core and other modules. 22146fb12b70Safresh1Starting in v5.20.1, calling the function 22156fb12b70Safresh1L<sync_locale()|perlapi/sync_locale> from XS should be sufficient to 22166fb12b70Safresh1avoid most of these problems. Prior to this, you need a pure Perl 2217*b8851fccSafresh1statement that does this: 22186fb12b70Safresh1 22196fb12b70Safresh1 POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL)); 22206fb12b70Safresh1 2221*b8851fccSafresh1In the event that your XS code may need the underlying C<LC_NUMERIC> 2222*b8851fccSafresh1locale, there are macros available to access this; see 2223*b8851fccSafresh1L<perlapi/Locale-related functions and macros>. 22246fb12b70Safresh1 22256fb12b70Safresh1=back 2226898184e3Ssthen 2227898184e3Ssthen=head1 XS VERSION 2228898184e3Ssthen 2229898184e3SsthenThis document covers features supported by C<ExtUtils::ParseXS> 2230898184e3Ssthen(also known as C<xsubpp>) 3.13_01. 2231898184e3Ssthen 2232898184e3Ssthen=head1 AUTHOR 2233898184e3Ssthen 2234898184e3SsthenOriginally written by Dean Roehrich <F<roehrich@cray.com>>. 2235898184e3Ssthen 2236898184e3SsthenMaintained since 1996 by The Perl Porters <F<perlbug@perl.org>>. 2237